# Account, credits, and this key's scopes Source: https://askeditor.com/docs/api-reference/account-credits-and-this-keys-scopes /api-reference/openapi.json get /v1/me # Estimate a run (free) Source: https://askeditor.com/docs/api-reference/estimate-a-run-free /api-reference/openapi.json get /v1/estimate # Fill a ticket from a shell (no browser) Source: https://askeditor.com/docs/api-reference/fill-a-ticket-from-a-shell-no-browser /api-reference/openapi.json post /v1/uploads/{ticket}/file The ticket IS the credential: one file, one project, once, within 30 minutes. No API key here on purpose — never put a spending credential in a shell command. # Get a job envelope (queued templates) Source: https://askeditor.com/docs/api-reference/get-a-job-envelope-queued-templates /api-reference/openapi.json get /v1/jobs/{envelopeId} # List recent jobs Source: https://askeditor.com/docs/api-reference/list-recent-jobs /api-reference/openapi.json get /v1/jobs # List templates (the menu) Source: https://askeditor.com/docs/api-reference/list-templates-the-menu /api-reference/openapi.json get /v1/recipes # Mint an upload ticket Source: https://askeditor.com/docs/api-reference/mint-an-upload-ticket /api-reference/openapi.json post /v1/uploads # Platform API Source: https://askeditor.com/docs/api-reference/overview One key-authenticated surface; templates are addresses. ## Base URL ```txt theme={null} https://api.askeditor.com ``` Auth: `Authorization: Bearer ` on every call (except filling an upload ticket, which is its own one-time credential). Every response is wrapped `{ success, data }`; errors carry a typed `errorCode`. | Endpoint | Purpose | | -------------------------------- | ------------------------------------------------ | | `GET /v1/recipes` | The template menu: contracts, prices, ETAs | | `GET /v1/estimate?recipeId={id}` | Free: price + typed blockers before any spend | | `POST /v1/uploads` | Mint a one-time upload ticket | | `POST /v1/uploads/{ticket}/file` | Fill the ticket from a shell (multipart, no key) | | `GET /v1/uploads/{ticket}` | Poll the ticket → the `material` handle | | `POST /v1/run/remove-background` | Synchronous run: the response is the result | | `GET /v1/jobs` | Recent jobs | | `GET /v1/jobs/{envelopeId}` | One job's envelope (queued templates) | | `GET /v1/me` | Account, credits remaining, this key's scopes | The same surface is also mounted at `/api/mcp/v1/*` (the MCP connector's address); the two are identical. The full machine-readable spec lives at a stable URL: [`/api-reference/openapi.json`](/docs/api-reference/openapi.json), generated from the same registry as the Templates tab, so the two cannot disagree. # Poll a ticket Source: https://askeditor.com/docs/api-reference/poll-a-ticket /api-reference/openapi.json get /v1/uploads/{ticket} # Run: Remove Background (synchronous) Source: https://askeditor.com/docs/api-reference/run:-remove-background-synchronous /api-reference/openapi.json post /v1/run/remove-background Cut the subject out of a video: the person isolated on a true alpha channel, ready to composite anywhere. SYNCHRONOUS: the call returns the finished cutout (~40-90s), no polling. The reflex call when an agent needs a background gone. # Changelog Source: https://askeditor.com/docs/changelog Template versions and platform changes. **`tracked-title-card` is live** at 75 credits: frosted cards pinned in world space, riding the camera, with the subject genuinely passing in front of them. **`remove-background` is live** at 25 credits and is the first SYNCHRONOUS template — the call holds open and returns the cutout, with no job to poll. **Both are now callable over MCP.** They reached the menu before the connector had verbs for them, so an agent could list them and not run them; `remove_background` and `create_tracked_title_card` close that. The connector's deploy now refuses on menu-vs-verb drift, so a template cannot be advertised without something to call. **Every template page gained a "See it" section**: your input video and the output, side by side, from real runs. `tighten` also shows the transcript with the removed words struck through, because a subtractive cut changes duration rather than picture — the numbers and the words are the only honest way to show it. Docs preview scaffolded: Documentation + Templates + Platform API tabs; template pages generated from the recipes registry. Live templates at scaffold time: `launch-cut`, `tighten`. Drafted (pending menu wiring): `remove-background`, `literally-me`, `tracked-title-card`. # Templates, Material, Spec, Cut Source: https://askeditor.com/docs/concepts/templates-material-spec-cut The four nouns the whole API hangs off. | Noun | What it is | Who owns it | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | **Template** | *How* a kind of film is made: the encoded editing craft: stages, composition rules, grading constants, QA gates. Versioned by us; addressed by id (`tighten`, `remove-background`). | AskEditor | | **Material** | Your raw footage. Templates never alter it: they derive from it. | You | | **Spec** | The knobs of one run (target length, brand name, aspect). Typed per template. | You, per run | | **Cut** | What *this particular* film is: the per-run decisions (which spans survive, which beats exist). Some templates expose the cut for review before rendering; revising it is cheap and never re-runs the pipeline. | Generated, yours to approve | The analogy: a template is the standard plan set for a house *type*; material is your timber and your site; the spec is your choices of finish; the cut is the working drawings for *this* build. You can revise the working drawings without redesigning the house type, which is why "make beat 7 longer" costs a revision, not a re-run. # The editable canvas Source: https://askeditor.com/docs/concepts/the-editable-canvas Some templates hand back an mp4, some hand back an editable timeline. Which one, and why it matters before you spend. ## Delivery: `file` or `canvas` Every template declares a **`delivery`** on the menu, and it is the most useful thing to read before you spend anything. It tells you what the run is guaranteed to hand back: | `delivery` | What you get | Example | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | **`file`** | An **mp4**. The run ends in an encoder, `outputUrl` is the product. A canvas usually comes too, but the file is the promise. | `remove-background`, `tighten`, `launch-cut` | | **`canvas`** | An **editable arrangement**, and no mp4. `canvasId` is the product: the value is *which* word, *when*, in *what layer order* — and it stays adjustable. | `text-behind` | It is a floor, not an exclusive. `remove-background` returns both and is still `file`, because the file is what it promises. **Why a canvas template does not just render you an mp4 as well.** Its price is bounded by the EFFECT — text-behind mattes at most four moments of four seconds — while a render is bounded by the RECORDING. Auto-exporting a 20-minute take to show four words would cost far more than the effect did. So you ask for the file when you actually want one, after you have looked at the result. Check `delivery` before you promise a user a video file. A `canvas` template delivering exactly what it should still has no `finalUrl`, and that is not a failure. ## What the canvas is For a `canvas` template this **is** the deliverable; for a `file` template it arrives alongside the mp4. Either way it is the same edit, open in the AskEditor editor as real layers: * clips with their trims (often windows onto your *original* material, so adjusting a cut point is a drag, at master quality), * text, music and effect elements, live and selectable, * the animations the template applied, as editable properties. ## Why it changes the integration A flat file makes every revision a re-run. A canvas makes the common revisions (nudge this cut, swap that word, try the other music) a 30-second human edit. For agent products this is the escape hatch that keeps users happy when "almost right" happens, which in video is often. ## Semantic layers, not render dumps Templates deliver canvases **decomposed the way a human editor would want them**, not as a literal translation of the render. A background built from hundreds of per-frame swaps arrives as one background element with its source plates in the media library; a subtractive cut arrives as one clip per kept span with the removed material still behind the trim handles. Each template's page notes its delivery shape. ## Provenance Canvases carry a stamp of *how* they were made: the template and version, the parameters per layer, so the edit can be re-derived or re-run against changed inputs later. # Build with AskEditor Source: https://askeditor.com/docs/index The video editing API for AI agents. Raw footage in, a finished edit out: plus an editable timeline, every time. AskEditor turns raw video into finished, directed edits through one API. An agent (or your code) names a **template**, hands over **material**, and gets back a finished edit. What "finished" means is stated on every template as its **`delivery`**: * **`delivery: "file"`** — an **mp4** at `finalUrl`, plus **`canvasUrl`**: the same edit as an **editable timeline** in the AskEditor editor. Not a screenshot of the result: the layers, trims, animations and audio, live and adjustable. * **`delivery: "canvas"`** — the **editable timeline is the deliverable**, and there is no mp4. These templates sell an arrangement rather than pixels — which word, when, in what layer order — and it stays adjustable. Export it yourself when you want a file. No other video API returns the second one, and the `canvas` templates exist *because* of it. [How delivery works](/docs/concepts/the-editable-canvas). ## Start here One config block connects Claude, Cursor, or any MCP client. Most integrations start (and finish) here. Key → upload → run → poll, in curl, JavaScript, or Python. The catalog. Each template is a finished edit with a typed input contract: what to record, the knobs, the price, the ETA. Why every response carries a timeline, and what your users can do with it. ## The shape of every call ```bash theme={null} POST /v1/run/{template_id} # material + spec → job_id GET /v1/jobs/{job_id} # queued → running → { finalUrl?, canvasUrl } # finalUrl only when delivery is "file" ``` Templates are addresses, not endpoints: the API surface never grows as the catalog does. List them at [`GET /v1/templates`](/docs/api-reference/overview) or via the [`list_templates`](/docs/mcp/tools) MCP tool. # Agent surfaces Source: https://askeditor.com/docs/mcp/agent-surfaces Every machine-readable surface AskEditor publishes, in one place. If you're an agent (or building one), these are the surfaces meant for you: | Surface | URL | What it carries | | --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | MCP connector | `https://mcp.askeditor.com` | The full tool surface: templates, uploads, jobs. | | llms.txt | `/llms.txt` on this docs site | The docs index for language models (auto-generated on deploy). | | llms-full.txt | `/llms-full.txt` on this docs site | The full docs content in one file (auto-generated on deploy). | | OAuth discovery | `mcp.askeditor.com/.well-known/oauth-protected-resource` | RFC 9728 metadata; a bare request to the MCP server 401s with the challenge, so clients self-configure. | | OpenAPI spec | `/api-reference/openapi.json` | The REST surface, typed. Stable URL. | | Template index | `GET /v1/templates` | The live menu as JSON: same data as the Templates tab. | Two design guarantees worth relying on: 1. **The menu is honest**: it lists only what a key can actually run today. A template on the menu is a template that works. 2. **Refusals and blockers are typed**: branch on codes, never parse prose. # Connect over MCP Source: https://askeditor.com/docs/mcp/connect The hosted connector: one URL, OAuth, done. AskEditor's MCP connector is hosted at **`https://mcp.askeditor.com`** (Streamable HTTP, OAuth 2.1). It is the only supported MCP route: there is no npm package to install. **You don't need an API key.** An unauthenticated request to the server returns `401` with an RFC 9728 `WWW-Authenticate` challenge, so a compliant MCP client discovers the OAuth flow and runs it automatically: you authorize in a browser window, approve the scopes, and the agent acts as you, on your credits. Clients register themselves via Dynamic Client Registration; PKCE (S256) and refresh tokens are supported. ## Endpoints | What | URL | | ---------------------------------------- | ------------------------------------------------------------------ | | MCP server | `https://mcp.askeditor.com/mcp` | | Protected resource metadata (RFC 9728) | `https://mcp.askeditor.com/.well-known/oauth-protected-resource` | | Authorization server metadata (RFC 8414) | `https://api.askeditor.com/.well-known/oauth-authorization-server` | | Dynamic Client Registration (RFC 7591) | `https://api.askeditor.com/oauth/register` | ```bash theme={null} claude mcp add askeditor --transport http https://mcp.askeditor.com ``` Settings → Connectors → **Add custom connector** → `https://mcp.askeditor.com` → **Authorize** with your AskEditor account. Add an MCP server with URL `https://mcp.askeditor.com` and complete the OAuth flow in the browser window that opens. Once authorized, the agent can list templates, estimate, upload material, run jobs, and fetch results: see [Tools](/docs/mcp/tools). **Troubleshooting**: if the connector won't connect, re-authorize from your client's connector settings; tool lists are cached by some clients, so reconnect after we announce new tools. # MCP tools Source: https://askeditor.com/docs/mcp/tools A small, stable tool surface; the growing catalog arrives as data. The connector deliberately exposes **few tools**: agents discover the growing template catalog by *listing*, so integrating once means every future template works with zero context cost. | Tool | What it does | | ------------------------------------ | -------------------------------------------------------------------------------- | | `list_recipes` | The template menu: id, summary, material contract, spec fields, price, ETA. | | `estimate` | Free: price + typed blockers for a template against your account. | | `request_upload` / `wait_for_upload` | Get material in from the agent's machine (one-time upload link for large files). | | Template run tools | Named run verbs per live template (e.g. `tighten_cut`, `create_launch_cut`). | | `get_job` / `list_jobs` | Job status and the final envelope: `finalUrl`, `canvasId`, `canvasUrl`. | Review-gated templates additionally expose their review verbs (preview, approve, revise) so the human-in-the-loop step is explicit in the agent's conversation. ## Choosing between similar tools A few verbs sound like the same job. When two could plausibly answer a request, **prefer the more robust one** — the one with the widest material contract, typed refusals, and a result that stands on its own. Reach for a narrower verb only when you are already inside its pipeline. | If the user asks… | Use | Not | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | "remove the background", "cut me out", "put me on green" | `remove_background` — any clip up to 15s, typed refusals, cached retries, returns a file **and** an editable canvas | `cut_out_subject` | | "put a word behind me" | Start at `preview_text_behind` — the cutout is step 2 of that flow | `remove_background` (it cuts the whole clip and cannot produce the per-moment cutouts this needs) | `cut_out_subject` is not a general background remover: it cuts only the moments a placement names, and its output is an **input to `apply_text_behind`**, not a deliverable. That narrowness is the point — a 20-minute recording costs the same as a 20-second one — but it makes it the wrong answer to a plain "cut me out". Every run verb states its own price and its refusals in its description, and `estimate` is free and authoritative. When two tools look equally valid, estimate both and quote the user the numbers before spending anything. # Quickstart: Agents (MCP) Source: https://askeditor.com/docs/quickstart/agents Connect any MCP client to AskEditor in one config block. The fastest integration is no integration: AskEditor ships a hosted MCP connector. Point your agent at it and the whole catalog becomes callable. ## Connect ```bash theme={null} claude mcp add askeditor --transport http https://mcp.askeditor.com ``` Settings → Connectors → **Add custom connector** → `https://mcp.askeditor.com` → **Authorize**. Add a custom MCP server with URL `https://mcp.askeditor.com` (Streamable HTTP). Complete the OAuth prompt when asked. Authorization uses your AskEditor account via OAuth: no key handling. ## First job, in plain language Once connected, this is a conversation, not code: > "List the AskEditor templates." → the agent calls `list_recipes` > > "Tighten this recording: \~/Desktop/take-3.mp4" → the agent uploads the > file, gets a free estimate (price + any blockers), asks you to confirm, > runs the job, and returns **two links**: the finished mp4 and the > editable canvas. ## What the agent sees Every job resolves to the same envelope: ```json theme={null} { "status": "completed", "finalUrl": "https://…/cut.mp4", "canvasId": "66f…", "canvasUrl": "https://askeditor.com/…/editor?canvas=66f…" } ``` Refusals are typed and free: if the material can't carry the template (silent recording, no visible subject, too long), the agent gets a machine-readable reason before anything is charged. See [Refusals](/docs/setting-up/refusals). # Quickstart: REST Source: https://askeditor.com/docs/quickstart/rest Key → upload → run. Five minutes to a finished, editable cutout. This walkthrough removes the background from a clip: the lead template, and a synchronous one, so there is no polling: the run call returns the result. ## Base URL All API calls go to one host: ```txt theme={null} https://api.askeditor.com ``` Every response is wrapped as `{ "success": true, "data": … }`; errors carry `{ "success": false, "errorCode": … }`. Create one at [Workspace → Your Account → API Keys](/docs/setting-up/get-your-api-key) with the **For skills** preset, and export it: ```bash theme={null} export ASKEDITOR_API_KEY="ake_live_…" ``` ```bash theme={null} curl https://api.askeditor.com/v1/me \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" # → data: { projectName, plan, creditsRemaining, scopes } ``` Skip this step if your video is already at a public https url: a run accepts the url directly. For a local file, mint a ticket and post the file to it: ```bash theme={null} curl -X POST https://api.askeditor.com/v1/uploads \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "purpose": "clip for background removal" }' # → data: { ticket: "upl_…", uploadUrl: "…" } # uploadUrl is the BROWSER path for humans (open it, drop the file). # From a shell, ignore it and post the file directly, as below. curl -X POST https://api.askeditor.com/v1/uploads/upl_…/file \ -F "file=@clip.mp4" # → data: { material: "mat…", status: "uploaded" } ``` The file call needs no API key: the ticket is a one-time, single-purpose credential, safe to use in a shell. ```bash theme={null} curl "https://api.askeditor.com/v1/estimate?recipeId=remove-background" \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" # → data: { credits: 25, etaSeconds: 90, blockers: [] } ``` Blockers are typed (`INSUFFICIENT_CREDITS`, `IN_FLIGHT`, `SCOPE_DENIED`, `RECIPE_NOT_ALLOWED`, `SPEND_CAP_REACHED`): branch on codes, never parse prose. ```bash theme={null} curl -X POST https://api.askeditor.com/v1/run/remove-background \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ --max-time 600 \ -d '{ "material": "mat…" }' ``` The call holds open while the GPU mattes the clip (\~40-90s), then: ```json theme={null} { "success": true, "data": { "status": "completed", "processedVideoUrl": "https://…/processed.webm", "canvasId": "66f…", "editorPath": "/workspace/canvas/editor/66f…", "credits": 25, "creditsCharged": true, "cached": false } } ``` The webm carries a true alpha channel, ready to composite. `editorPath` (on askeditor.com) opens the same cutout as an editable canvas: see [The editable canvas](/docs/concepts/the-editable-canvas). Retrying the identical call returns `"cached": true` and charges nothing. Queued templates (tighten, launch-cut) run through the [MCP connector](/docs/quickstart/agents) and resolve via [`GET /v1/jobs/{id}`](/docs/setting-up/jobs-and-polling). # Concurrency limits Source: https://askeditor.com/docs/setting-up/concurrency-limits How many jobs can run at once, and what happens at the cap. GPU stages are scheduled fairly across accounts, so per-account in-flight caps apply: * **In-flight jobs per account**: template pages note any per-template caps (GPU-heavy stages like matting cap at **3 concurrent** per account). * At the cap, new runs return the typed blocker `IN_FLIGHT` at estimate time, or HTTP 429 at run time. Back off and retry; don't tight-loop. * Queue position and estimated wait are reported on the job while queued. Higher limits for production workloads: contact us: the caps are policy, not physics. # Data retention Source: https://askeditor.com/docs/setting-up/data-retention How long material, outputs, and canvases live, and why retention is product behavior here. Retention matters more on AskEditor than on a typical media API, because of the editable canvas: **a delivered canvas can reference your original uploads directly** (that's what makes it losslessly editable). If the source material expires, the mp4 remains but parts of the canvas would degrade. Read this page before building retention-sensitive workflows. ## Current policy * **Material (your uploads)**: retained while your account is active. * **Rendered outputs (`finalUrl`)**: retained; a canvas always keeps the flat mp4 as its fallback, so a canvas remains a working video even if a referenced source disappears. * **Canvases**: live in your account like any project; open and edit them any time. * **Deletion**: deleting material from your library removes it from storage; canvases referencing it fall back to their flat render. Formal retention windows (per plan tier) will be published here before self-serve keys go live. Nothing shortens silently: policy changes are announced in the changelog first. # Get your API key Source: https://askeditor.com/docs/setting-up/get-your-api-key Create a key, set it, scope it, test it. Requests to AskEditor require authentication: you need an API key to call templates from code, CI, or any agent that cannot sign in. (Connecting Claude or another MCP client? You don't need a key at all: the [connector](/docs/mcp/connect) signs in with OAuth.) Keys are tied to a **workspace**, not a person. A key is minted inside the workspace you're standing in, spends that workspace's credits, and stays bound to it for life. It can never spend more than the workspace's balance, and every call it makes is logged against it. ## Create your API key Navigate to [Workspace → Your Account → API Keys](https://askeditor.com/login?callbackUrl=%2Fworkspace%2Fprofile%2Fapi-keys). Signed in, the link goes straight to your keys; signed out, it takes you through sign-in and lands you there. Click **Add key**, give it a name you'll recognise later, and pick its [scopes](#key-scopes). Copy the key immediately. **It is shown exactly once**: only its hash is stored, so nobody can retrieve it again, not you, not support. Lose it → revoke it and create another. ## Set your API key Keys look like `ake_live_…`. Set yours as an environment variable: ```bash theme={null} export ASKEDITOR_API_KEY="ake_live_…" ``` ```powershell theme={null} $env:ASKEDITOR_API_KEY = "ake_live_…" ``` ```bash theme={null} ASKEDITOR_API_KEY=ake_live_… ``` Every call carries it in the `Authorization` header: ```bash theme={null} Authorization: Bearer ake_live_… ``` **Best practice**: keep keys in environment variables, never hardcoded, and never in client-side code. For browser apps, proxy calls through your backend. Separate keys for development and production make revocation painless. ## Key scopes When creating a key you choose its scopes: they're frozen into the key, and every endpoint requires one. A key without the needed scope gets the typed `SCOPE_DENIED` blocker at estimate time, before any spend. Scopes only ever carve *down* from what your account can already do. | Scope | What it allows | Credits | | ---------------- | ------------------------------------------------------ | ------------------ | | `recipes:read` | See which templates exist: the menu, contracts, prices | free | | `jobs:read` | Check the status of work already submitted | free | | `blocks:read` | Read the building blocks of a project | free | | `library:read` | Browse assets already in the workspace | free | | `canvas:read` | Read a canvas and its timeline | free | | `material:write` | Upload recordings, clips and photos to a project | free | | `render:submit` | Start cuts and renders | **spends credits** | | `export:submit` | Export finished video | **spends credits** | Not sure what to pick? The two presets in the dialog cover most keys: **Read only** (safe for dashboards and monitoring) and **For skills** (`recipes:read`, `jobs:read`, `material:write`, `render:submit`: what an agent needs to make videos end to end). You can always create another key with more scope later. Some scopes deliberately do not exist yet: there is no `canvas:write`, no `social:publish`, and no `billing:*`. A key can never edit your canvases behind your back, post to your social accounts, or touch billing. Those capabilities are withheld from the scope vocabulary itself, so no combination of checkboxes can grant them. ## Test your key Verify it works with the identity call: it needs only `recipes:read` and costs nothing. ```bash theme={null} curl https://api.askeditor.com/api/mcp/v1/me \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" ``` A working key answers with your workspace, plan, remaining credits, and the scopes this key holds: ```json theme={null} { "projectName": "…", "plan": "…", "creditsRemaining": 27900, "scopes": ["recipes:read", "jobs:read", "material:write", "render:submit"] } ``` ## One account, one login method Signing in with Google and signing in with the same address by email create **two different accounts** with separate keys and credits. Pick one method and stay with it. # Infrastructure errors Source: https://askeditor.com/docs/setting-up/infrastructure-errors 5xx, timeouts, and retries: the failures that are on us. Distinct from [refusals](/docs/setting-up/refusals) (facts about your material), these are faults in our infrastructure. **Failed jobs are not charged.** * **HTTP 5xx on any endpoint**: safe to retry with backoff (30s, 60s, 120s). Job creation is idempotent on identical input. * **Job stuck in `queued`**: the queue reports position and estimated wait; sustained stalls beyond 2× the posted `etaSeconds` warrant a retry or a support ping. * **HTTP 429**: you've hit a [concurrency limit](/docs/setting-up/concurrency-limits) or rate limit; back off and retry, don't tight-loop. Live platform status: the status page linked in the footer. # Jobs & polling Source: https://askeditor.com/docs/setting-up/jobs-and-polling Async by design: run returns a job id; the job resolves to the mp4 and the canvas. Video work takes seconds to minutes, so the API is **queue-first**: ``` queued templates: run → { jobId }, then GET /v1/jobs/{jobId} until done sync templates: POST /v1/run/{id} holds open and RETURNS the result ``` `remove-background` is synchronous: no polling at all. `tighten` and `launch-cut` are queued and resolve through the jobs envelope. ## Job states `queued → running → completed | refused | failed` * `completed` carries the full envelope: `finalUrl`, `canvasUrl`, `recipeVersion`, timings. * `refused` carries a [typed reason](/docs/setting-up/refusals): free. * `failed` is on us: see [Infrastructure errors](/docs/setting-up/infrastructure-errors); failed jobs are not charged. ## Estimate first `GET /v1/estimate?recipeId={id}` is free and returns `{ credits, etaSeconds, creditsRemaining, blockers[] }` with typed blockers (`INSUFFICIENT_CREDITS`, `IN_FLIGHT`, `SCOPE_DENIED`, `RECIPE_NOT_ALLOWED`, `SPEND_CAP_REACHED`). Agents should estimate, ask consent, then run. An estimate validates the PRICE and your ACCOUNT (credits, scopes, in-flight caps), not your material: material checks (duration, readability, subject presence) happen at run time, and when they fail you get a free typed refusal, never a charge. ## Polling etiquette Poll every 5-15s; each template page posts an `etaSeconds` to calibrate expectations. Webhooks (`callback_url`) are on the roadmap for fire-and-forget integrations. # Pricing Source: https://askeditor.com/docs/setting-up/pricing Prepaid credits, a posted price per template, and a free estimate that is always authoritative. AskEditor bills in **prepaid credits**. You top up in the dashboard; runs draw the balance down. One wallet serves both doors: the app and the API spend the same credits, so nothing about your plan changes when you switch between them. ## Per-template pricing Every template posts one price, charged **per run**: | Template | Price | Unit | | ------------------------------------------------------ | ----------- | --------------------- | | [Tighten](/docs/templates/tighten) | 200 credits | per run | | [Launch Cut](/docs/templates/launch-cut) | 500 credits | per run | | [Remove Background](/docs/templates/remove-background) | 25 credits | per run (synchronous) | The number on a template's page, the number `estimate` returns, and the number you're charged come from the same registry entry: they cannot disagree. New templates arrive with their price posted on day one. ## What you pay for Successful renders. That's the whole list. ## What you are never charged for * **Refusals**: a template that can't work on your material says so with a [typed reason](/docs/setting-up/refusals), free. * **Failures**: an infrastructure error on our side ([5xx](/docs/setting-up/infrastructure-errors)) is never billed. * **Queue time**: waiting for a worker costs nothing; only the run counts. * **Estimates**: always free, call them as often as you like. * **Retries of a completed job**: identical input returns the cached result, not a second charge. ## Checking prices programmatically The menu carries prices, so an agent can quote costs before asking consent: ```bash theme={null} curl https://api.askeditor.com/v1/recipes \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" ``` And `estimate` confirms the price for a specific run, with typed blockers if it can't go ahead: ```bash theme={null} curl "https://api.askeditor.com/v1/estimate?recipeId=tighten" \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" # → data: { "credits": 200, "etaSeconds": 60, "blockers": [] } ``` Your remaining balance rides on the identity call (`GET /v1/me` → `creditsRemaining`), so a long-running agent can watch its own budget. ## Buying credits Credits come from your plan's allowance and top-up packs, managed at [askeditor.com/pricing](https://askeditor.com/pricing). Your balance and usage live in the [workspace credits page](https://askeditor.com/login?callbackUrl=%2Fworkspace%2Fprofile%2Fcredits). ## Review gates A template with a review gate (marked on its page, e.g. [Launch Cut](/docs/templates/launch-cut)) parks for **your approval** after planning and before any spend. Agent integrations should surface that approval to the human rather than auto-confirming it. ## Volume and enterprise Running templates at production volume, or need custom terms? [Book a call](https://cal.com/askeditor/askeditor-demo) and we'll set it up per account. # Refusals Source: https://askeditor.com/docs/setting-up/refusals When a template can't work on your material, it says so: typed, before money is spent, and always free. A refusal is not an error. It is the template telling you a **fact about the material**: retrying the same call will not change it; different material will. ## Why this exists An edit that silently produces garbage costs you credits and trust. So every template declares what it needs, checks it up front, and refuses with a machine-readable code an agent can branch on. ## Common refusal codes | Code | Meaning | What to do | | ---------------------- | ----------------------------------------------- | --------------------------------------- | | `NO_SUBJECT` | No person detected in the shot | Use footage with a visible person | | `SUBJECT_TOO_SMALL` | The person is too small/far to carry the effect | Reframe or record closer | | `SUBJECT_LEAVES_FRAME` | The subject exits mid-take | Trim to a span where they stay in frame | | `SPAN_TOO_LONG` | A requested span exceeds the template's cap | Split or shorten | | `NO_USABLE_SPANS` | Nothing in the material fits the template | Different material | | `UNREADABLE` | The file has no readable video stream | Re-export and re-upload | Template pages list which refusals apply to them. Estimate-time blockers (`INSUFFICIENT_CREDITS`, `IN_FLIGHT`, `SCOPE_DENIED`, `RECIPE_NOT_ALLOWED`) are documented under [Jobs & polling](/docs/setting-up/jobs-and-polling). Refusals are never charged, and they are deliberate: "refuse broken, allow odd." Unusual footage that passes the gate is allowed to be unusual. # Uploading material Source: https://askeditor.com/docs/setting-up/uploading-material How raw footage gets to us. **Material** is your raw input: a recording, a screen capture, a clip. It is yours; templates never alter it, they derive from it. A run's `material` field takes one of the following. ## A public https URL (simplest) Pass a public `https://` URL as `material` and we fetch it server-side (with SSRF guards). No upload step needed: ```json theme={null} { "material": "https://your-cdn.com/clip.mp4" } ``` ## An upload ticket (for local files) Uploading is **two calls**: mint a one-time ticket, then post the file to it. The file call needs no API key, because the ticket is its own single-use credential. ```bash theme={null} # 1. Mint a ticket curl -X POST https://api.askeditor.com/v1/uploads \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "purpose": "clip for background removal" }' # → data: { "ticket": "upl_…", "uploadUrl": "…", "expiresInSec": 1800 } # 2. Post the file to the ticket (no auth header) curl -X POST https://api.askeditor.com/v1/uploads/upl_…/file \ -F "file=@clip.mp4" # → data: { "material": "mat_…", "bytes": …, "status": "uploaded" } ``` Pass the returned **`material`** handle (`mat_…`) as the run's `material`. (The `uploadUrl` in the ticket response is a browser path for humans to drop a file in; from a shell, ignore it and use the `/file` endpoint above.) Poll a ticket any time with `GET /v1/uploads/{ticket}`; its `status` goes `pending → uploaded`, and `material` is set once the file lands. ## Via MCP The [connector](/docs/mcp/connect)'s upload tools drive the same ticket flow for files on the agent's machine, including large-file handling. ## What templates check Each template declares what material it accepts (kind, duration bounds, orientation, content requirements like "one person, front-facing"). The check runs **before** the pipeline and before any charge: a mismatch comes back as a [typed refusal](/docs/setting-up/refusals), not a failed render. # Launch Cut Source: https://askeditor.com/docs/templates/launch-cut Turn a raw screen recording plus the product's website into a directed, narrated, brand-matched demo film: the kind a founder posts on ship day.. Turn a raw screen recording plus the product's website into a directed, narrated, brand-matched demo film: the kind a founder posts on ship day. ## See it ## Material A screen recording between 15 seconds and 20 minutes, with the narration audible. If the take is silent, set narrationSource='screen' and the director writes and speaks the narration instead. ## Spec | Field | Type | Required | Description | | ----------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `siteUrl` | string | **yes** | The product's public website. The brand (colours, type, logo) is measured from it. | | `brandName` | string | **yes** | How the product should be named on screen. | | `narrationSource` | enum (`user` \| `screen`) | no | 'user' (default) uses the voice on the recording. 'screen' writes narration from the frames and the site: opt-in only, for a silent take. | | `directorNote` | string | no | One instruction to the director, e.g. 'lead with the pricing moment'. | ## Pricing & timing | | | | ------------ | ------------------------------------------------------------------------------------ | | **Delivery** | **File** — an mp4 at `outputUrl`, plus an editable canvas | | Price | 500 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative | | Typical run | \~600s | | Review gate | **Yes**: the run parks for your approval before spending | ## Refusals this template can return * `UNREADABLE` Refusals are free and typed: see [Refusals](/docs/setting-up/refusals). ## Run it ```bash theme={null} # 1. mint an upload ticket, then put the file against it curl -X POST https://api.askeditor.com/v1/uploads \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" -d '{"purpose":"launch-cut"}' # → { "ticket": "upl_…", "uploadUrl": "…" } curl -X POST https://api.askeditor.com/v1/uploads/{ticket}/file \ -F "file=@./recording.mp4" # → { "material": "mat_…" } # 2. submit the run curl -X POST https://api.askeditor.com/api/launch-cut/jobs \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "material": "mat_…", "clientRequestId": "your-own-id", "siteUrl": …, "brandName": … }' # → { "jobId": "…", "envelopeId": "launch-cut:…", "credits": { "quoted": 500, "charged": 0 } } # 3. poll until it resolves curl https://api.askeditor.com/v1/jobs/{envelopeId} \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" ``` `clientRequestId` is **required**: reuse the same value on a retry and you cannot be charged twice for the same run. Connected via the [MCP connector](/docs/mcp/connect)? It is one sentence: > "Run the **Launch Cut** template on \~/Desktop/recording.mp4" The agent lists the menu, estimates (free), asks your consent, uploads, runs, and polls [`GET /v1/jobs/{id}`](/docs/setting-up/jobs-and-polling) to the finished envelope. **Editable delivery:** Delivers decomposed: one clip per beat plus the narration mix as its own audio element. # Message Bubbles Source: https://askeditor.com/docs/templates/message-bubbles A text conversation floating in the room next to you, one bubble popping in after another, each pinned in 3D space so it foreshortens and parallaxes as the camera moves. A text conversation floating in the room next to you, one bubble popping in after another, each pinned in 3D space so it foreshortens and parallaxes as the camera moves. Real iMessage geometry: blue sent bubbles right-aligned with the flick tail, grey replies on the left, sender and time above each, frosted-glass finish by default. Turn the sound on: every message lands with a soft chime. Ask for the Android look and your sent bubbles turn Apple's SMS green. ## See it ## Material One person in a room with texture around them (desk, window, shelves), up to 30 seconds. The camera should move: a slow orbit, a walk-in, or even the settling pull-back after you place the phone is enough, and it is what makes the thread feel like it is hanging in the air. A locked-off tripod shot still works (the bubbles simply hold their place) but shows the effect at its least. Your body is masked out of the tracking, so you can move freely. ## Spec | Field | Type | Required | Description | | ------------ | ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messages` | array | **yes** | 2 to 6 messages in order. Each: `from` (sender name for the label), `text` (one or two lines; emoji welcome), `dir` (`out` = sent by the person on camera, blue, tail bottom-right; `in` = a reply, grey, tail bottom-left). The default conversation is the person texting AskEditor and AskEditor making the very bubbles you are watching. Message cadence follows the reference (about 1.2 to 1.5 s apart) unless you pass `at` seconds per message. | | `style` | enum (`imessage` \| `android`) | no | `imessage` (default): sent bubbles in Apple's iMessage blue. `android`: sent bubbles in Apple's SMS green, the way an Android contact's thread looks on an iPhone. Replies are grey in both. | | `finish` | enum (`glass` \| `flat`) | no | `glass` (default): frosted backdrop blur, translucent tint, hairline and soft shadow, one continuous silhouette including the tail. `flat`: opaque, exactly like the phone. | | `stabilizer` | number | no | Gimbal cutoff in Hz, default 2. The bubbles follow camera motion slower than this and have inertia against anything faster, with no lag. 1.5 for slow cinematic orbits; do not go below 1 (the thread starts gliding away from the room). | ## Pricing & timing | | | | ------------ | ------------------------------------------------------------------------------------ | | **Delivery** | **File** — an mp4 at `outputUrl`, plus an editable canvas | | Price | 100 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative | | Typical run | \~300s | | Review gate | No: runs straight through | ## Refusals this template can return * `NO_SUBJECT` * `NO_TRACKABLE_BACKGROUND` * `MATERIAL_TOO_LONG` * `UNREADABLE` * `BAD_SPEC` Refusals are free and typed: see [Refusals](/docs/setting-up/refusals). ## Run it ```bash theme={null} # 1. mint an upload ticket, then put the file against it curl -X POST https://api.askeditor.com/v1/uploads \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" -d '{"purpose":"message-bubbles"}' # → { "ticket": "upl_…", "uploadUrl": "…" } curl -X POST https://api.askeditor.com/v1/uploads/{ticket}/file \ -F "file=@./recording.mp4" # → { "material": "mat_…" } # 2. submit the run curl -X POST https://api.askeditor.com/api/message-bubbles/jobs \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "material": "mat_…", "clientRequestId": "your-own-id", "messages": … }' # → { "jobId": "…", "envelopeId": "message-bubbles:…", "credits": { "quoted": 100, "charged": 0 } } # 3. poll until it resolves curl https://api.askeditor.com/v1/jobs/{envelopeId} \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" ``` `clientRequestId` is **required**: reuse the same value on a retry and you cannot be charged twice for the same run. Connected via the [MCP connector](/docs/mcp/connect)? It is one sentence: > "Run the **Message Bubbles** template on \~/Desktop/recording.mp4" The agent lists the menu, estimates (free), asks your consent, uploads, runs, and polls [`GET /v1/jobs/{id}`](/docs/setting-up/jobs-and-polling) to the finished envelope. **Editable delivery:** Delivers the finished mp4 with the chimes mixed under your audio. The editable form (each bubble as a live element carrying its 3D track, plus the solved camera so you can add messages later) ships with the bubble element; until then the copy is baked. The tracking is a real camera solve, not a 2D sticker track: the bubbles are planes fixed in the room, so they foreshorten and drift against the background exactly like objects would. Validated against a professional After Effects reference over a 60-degree orbit, and against the real scene at about a fifth of a pixel of reprojection error on the clip shown here. Width shapes copy: a bubble is its longest line plus padding, and sent bubbles stop short of your face. Long sentences wrap to two lines; if a message will not fit beside you, the run tells you rather than covering you. # Templates Source: https://askeditor.com/docs/templates/overview The catalog. Each template is a finished edit with a typed contract. A **template** is a complete, directed edit: you bring material, it brings the editing craft. Live templates below are callable today at `POST /v1/run/{id}`; drafts show their contract ahead of launch. A text conversation floating in the room next to you, one bubble popping in after another, each pinned in 3D space so it foreshortens and parallaxes as the camera moves. Cut the subject out of a video: the person isolated on a true alpha channel, ready to composite anywhere. Give a long raw take back SHORTER. Turn a raw screen recording plus the product's website into a directed, narrated, brand-matched demo film: the kind a founder posts on ship day.. Pin frosted, notification-style cards to points IN THE WORLD of your video. Put a word BEHIND the speaker so their head and shoulders cut across the letters. # Remove Background Source: https://askeditor.com/docs/templates/remove-background Cut the subject out of a video: the person isolated on a true alpha channel, ready to composite anywhere. Cut the subject out of a video: the person isolated on a true alpha channel, ready to composite anywhere. SYNCHRONOUS: the call returns the finished cutout (\~40-90s), no polling. The reflex call when an agent needs a background gone. ## See it **29s** start to finish · **25** credits · **1080p** in and out ## Material A video with one clear subject, up to 15 SECONDS. Any orientation; output is capped at 1080p on the long edge and 30fps. Pass an upload handle or a public https url. ## Spec | Field | Type | Required | Description | | -------------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `quality` | enum (`best` \| `fast`) | no | 'best' (default) is the quality pick. 'fast' trades a little edge fidelity for speed. | | `outputFormat` | enum (`webm` \| `mov` \| `mp4`) | no | 'webm' (default) = VP9 with true alpha. 'mov' = ProRes 4444 alpha. 'mp4' = green screen. | ## Pricing & timing | | | | ------------ | ----------------------------------------------------------------------------------- | | **Delivery** | **File** — an mp4 at `outputUrl`, plus an editable canvas | | Price | 25 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative | | Typical run | \~90s | | Review gate | No: runs straight through | ## Refusals this template can return * `NO_SUBJECT` * `SUBJECT_TOO_SMALL` * `SUBJECT_LEAVES_FRAME` * `UNREADABLE` Refusals are free and typed: see [Refusals](/docs/setting-up/refusals). ## Run it SYNCHRONOUS: the call holds open (\~90s) and the response IS the result. No job to poll. ```bash theme={null} curl -X POST https://api.askeditor.com/v1/run/remove-background \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ --max-time 600 \ -d '{ "material": "https://…/clip.mp4", "quality": "best" }' ``` `material` is a public https url, or the handle from an [upload](/docs/setting-up/uploading-material). ```json theme={null} { "success": true, "data": { "status": "completed", "processedVideoUrl": "https://…/processed.webm", "canvasId": "…", "editorPath": "/workspace/canvas/editor/…", "credits": 25, "creditsCharged": true, "cached": false } } ``` Retrying the identical call returns the same result with `"cached": true` and no second charge. Connected via the [MCP connector](/docs/mcp/connect)? Just ask: > "Remove the background from \~/Desktop/clip.mp4" The agent estimates (free), asks your consent, uploads, runs, and hands back the cutout plus the editable canvas. **Editable delivery:** The canvas delivers the cutout as a live alpha layer over a swappable background element. Verifying alpha: a naive ffprobe reports `pix_fmt=yuv420p` because VP9 alpha travels as a WebM side channel. Check the stream tag `ALPHA_MODE=1`, or decode with `-c:v libvpx-vp9` (the default decoder silently drops the alpha plane). # Text Behind the Subject Source: https://askeditor.com/docs/templates/text-behind Put a word BEHIND the speaker so their head and shoulders cut across the letters. Put a word BEHIND the speaker so their head and shoulders cut across the letters. Driven by the TRANSCRIPT, not by timestamps: the opening earns one word naming what the video is about, and an emphasis phrase earns the word that follows it. Three steps — preview the placements for free, matte only those moments, then apply. ## Material One recording of a person talking, with intelligible speech: the placements are decided from the words. ANY LENGTH — matting is per-placement, so a 20-minute take costs the same as a 20-second one. The subject must be in shot, large enough in frame, and must not leave it. ## Spec | Field | Type | Required | Description | | ---------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `position` | enum (`top` \| `middle` \| `bottom`) | no | Where the word sits relative to the speaker. Omit and the plan decides per placement. | | `cadence` | number | no | How many moments the finished piece should carry, up to 4. Omit and you get exactly what the intro and emphasis rules earned — on a calm recording that is one, and that is correct. A target is not a guarantee: a take with nothing to say in a stretch comes back short and says why. | | `only` | string | no | One explicit word to place, overriding both drivers. Use when the user names the word themselves. | ## Pricing & timing | | | | ------------ | -------------------------------------------------------------------------------------------------------------- | | **Delivery** | **Editable canvas** — this template returns a canvas and **no mp4**. [Why](/docs/concepts/the-editable-canvas) | | Price | 75 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative | | Typical run | \~120s | | Review gate | No: runs straight through | ## Refusals this template can return * `NO_SUBJECT` * `SUBJECT_TOO_SMALL` * `SUBJECT_LEAVES_FRAME` * `UNREADABLE` Refusals are free and typed: see [Refusals](/docs/setting-up/refusals). ## Run it ⚠️ **This template is a THREE-CALL FLOW, not one submit.** The plan is agreed before any GPU is spent, which is why the preview is free and the charge lands on step 2. ```bash theme={null} # 0. read the recording — uploads it AND transcribes, returns projectId + words curl -X POST https://api.askeditor.com/api/talking-head-cut/read \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -F "recording=@./recording.mp4" # → { "projectId": "…", "transcript": [ { "t": "word", "s": 0.1, "e": 0.4 }, … ] } # 1. PLAN — which word, when. FREE, changes nothing, iterate until happy curl -X POST https://api.askeditor.com/api/text-behind/plan \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" -H "Content-Type: application/json" \ -d '{ "projectId": "…", "words": [ … ], "durationSec": 165.5 }' # → { "placements": [ { "startSec": 0.56, "endSec": 4.56, "text": "RIGHT", "why": "the opening" } ], # "quotedCredits": 75 } # 2. SUBJECT — matte ONLY those moments. 75 credits, charged on success curl -X POST https://api.askeditor.com/api/text-behind/subject \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" -H "Content-Type: application/json" \ -d '{ "projectId": "…", "placements": [ … ] }' # → { "baseUrl": "…", "cutouts": [ … ], "width": 1920, "height": 1080 } # 3. APPLY — write the canvas. Free curl -X POST https://api.askeditor.com/api/text-behind/apply \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" -H "Content-Type: application/json" \ -d '{ "projectId": "…", "placements": [ … ], "cutouts": [ … ], "baseUrl": "…", "width": 1920, "height": 1080, "durationSec": 165.5 }' # → { "canvasId": "…", "elements": 5 } ``` 🚨 **Pass step 2's own `baseUrl` to step 3**, never the original upload: the cut-out step normalises rotation, and the two layers must agree or the subject comes back on its side. There is **no job to poll** — apply returns the canvas id directly. See [delivery](/docs/concepts/the-editable-canvas). Connected via the [MCP connector](/docs/mcp/connect)? It is one sentence: > "Put a word behind me in \~/Desktop/recording.mp4" The agent reads the recording, previews the placements for free, shows you which words it chose and why, then mattes and applies once you agree. **Editable delivery:** Delivers an EDITABLE CANVAS and no flat mp4 — three layers: the recording, one live text element per placement, and the subject cut-out on top. The text stays draggable and re-typeable, and the occlusion is a consequence of the stacking order rather than a composite. Export the canvas when you want a file. The word going BEHIND the speaker is the entire effect. A word that never passes behind them is a caption, and this template is not a caption tool. Charged 75 credits flat on the cut-out step, on success only. The flat price holds because at most 4 placements of at most 4 seconds each reach the GPU — matting is per-span, never the whole recording. Two tiers, sized against each other: the word BEHIND the subject is the headline (240px on a 1080 short edge) and the optional caption rail in FRONT sits smaller. If you turn captions on, expect both. # Tighten Source: https://askeditor.com/docs/templates/tighten Give a long raw take back SHORTER. Give a long raw take back SHORTER. Pre-roll, false starts, restarts, take-fumbles and dead air come out; the argument, the voice and the natural rhythm stay in. NOTHING is composited, reframed, restyled, captioned or added: this register ONLY EVER REMOVES TIME, which is why it takes any orientation and hands back the source's own frame. ## See it **2:45 → 2:25** one take, tightened · **20.9s** removed · **13%** shorter ### What came out
right, pretty much before the AI storm of LLMs. So five years ago, it's 2026, it was probably just in 2021 or like late, uh, around '21, '22, just before, uh, the real LLMs start coming up into the mainstream of where we are right now. And ever since that, there's been a lot of changes in all industries from, of course, software engineering to just even normal day productivity of working with Excel also. Before you would have learned how to do things, um, and understand the actual Excel macro spreadsheets even like that. That's been updated. Now, where we are now, fast-forward five years, what we've been up to? Well, there's been a lot that has been, uh, happening behind the scenes, of course. Um, and where we are right now-- In fact, I just wanna go straight into it. Long story short, we-- Uh, the thing before
■ removed — fillers, false starts, restarts and dead air. Everything else is the take's own words, in its own order: tighten never rewrites, it only leaves things out. ## Material One recording of someone talking, UP TO 20 MINUTES. Any orientation, any resolution: the cut is a splice, so the output keeps the source's own dimensions. The only real requirement is intelligible speech, because the cut is decided from the words. ## Spec | Field | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `targetSeconds` | number | no | Leave unset to let the take decide. Setting it asks the director to REACH a length, which means dropping content and not just fumbles. | | `maxSeconds` | number | no | Cap on the finished cut, default 1200 (20 min). | ## Pricing & timing | | | | ------------ | ------------------------------------------------------------------------------------ | | **Delivery** | **File** — an mp4 at `outputUrl`, plus an editable canvas | | Price | 200 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative | | Typical run | \~60s | | Review gate | No: runs straight through | ## Refusals this template can return * `NO_USABLE_SPANS` * `SPAN_TOO_LONG` * `UNREADABLE` Refusals are free and typed: see [Refusals](/docs/setting-up/refusals). ## Run it ```bash theme={null} # 1. mint an upload ticket, then put the file against it curl -X POST https://api.askeditor.com/v1/uploads \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" -d '{"purpose":"tighten"}' # → { "ticket": "upl_…", "uploadUrl": "…" } curl -X POST https://api.askeditor.com/v1/uploads/{ticket}/file \ -F "file=@./recording.mp4" # → { "material": "mat_…" } # 2. submit the run curl -X POST https://api.askeditor.com/api/talking-head-cut/jobs \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "material": "mat_…", "clientRequestId": "your-own-id" }' # → { "jobId": "…", "envelopeId": "tighten:…", "credits": { "quoted": 200, "charged": 0 } } # 3. poll until it resolves curl https://api.askeditor.com/v1/jobs/{envelopeId} \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" ``` `clientRequestId` is **required**: reuse the same value on a retry and you cannot be charged twice for the same run. Connected via the [MCP connector](/docs/mcp/connect)? It is one sentence: > "Run the **Tighten** template on \~/Desktop/recording.mp4" The agent lists the menu, estimates (free), asks your consent, uploads, runs, and polls [`GET /v1/jobs/{id}`](/docs/setting-up/jobs-and-polling) to the finished envelope. **Editable delivery:** Delivers as PARTS: one clip per kept span, each a trim of your ORIGINAL recording. A cut you disagree with costs a drag instead of a re-run, and everything plays at master quality. # Tracked Title Card Source: https://askeditor.com/docs/templates/tracked-title-card Pin frosted, notification-style cards to points IN THE WORLD of your video. Pin frosted, notification-style cards to points IN THE WORLD of your video. Each card rides the camera motion exactly, holds constant screen size, and the subject genuinely passes IN FRONT of it (real occlusion via a subject matte). One card is a world-space title; several, staggered to the subject's glances with rising-pitch chimes, read as thoughts arriving on screen. ## See it ## Material One subject with visible background texture near the subject's depth (a wall is ideal), up to 30 seconds. The camera should move at least a little: small handheld drift is enough, and it is what makes the cards feel welded to the scene. A locked-off tripod shot gives the effect nothing to prove. ## Spec | Field | Type | Required | Description | | -------- | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cards` | array | **yes** | 1 to 4 cards. Each card: `name` (sender, shown bold), `message` (one line, no emoji), optional `avatarHue` (two RGB stops for the avatar gradient), optional `placement` (`graze-left` \| `graze-right` \| `stackOn:` \| `backdrop`), optional `scale` (0.5-1.2; 1.0 at a graze spot, 0.8 for a background card), optional `tEnter` (seconds, 0-60; omit it and the cards stagger about 2.9s apart). Placements are measured from the subject matte, never guessed, so the subject's silhouette grazes the card instead of burying it. | | `chimes` | enum (`rising` \| `single` \| `none`) | no | 'rising' (default) plays one soft two-note chime per card, pitched up a step each time and easing down in volume as the cards pile up. 'single' uses one pitch for every card. 'none' leaves the source audio untouched. | ## Pricing & timing | | | | ------------ | ----------------------------------------------------------------------------------- | | **Delivery** | **File** — an mp4 at `outputUrl`, plus an editable canvas | | Price | 75 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative | | Typical run | \~240s | | Review gate | No: runs straight through | ## Refusals this template can return * `NO_SUBJECT` * `NO_TRACKABLE_BACKGROUND` * `MATERIAL_TOO_LONG` * `UNREADABLE` * `BAD_SPEC` Refusals are free and typed: see [Refusals](/docs/setting-up/refusals). ## Run it ```bash theme={null} # 1. mint an upload ticket, then put the file against it curl -X POST https://api.askeditor.com/v1/uploads \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" -d '{"purpose":"tracked-title-card"}' # → { "ticket": "upl_…", "uploadUrl": "…" } curl -X POST https://api.askeditor.com/v1/uploads/{ticket}/file \ -F "file=@./recording.mp4" # → { "material": "mat_…" } # 2. submit the run curl -X POST https://api.askeditor.com/api/tracked-title-card/jobs \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "material": "mat_…", "clientRequestId": "your-own-id", "cards": … }' # → { "jobId": "…", "envelopeId": "tracked-title-card:…", "credits": { "quoted": 75, "charged": 0 } } # 3. poll until it resolves curl https://api.askeditor.com/v1/jobs/{envelopeId} \ -H "Authorization: Bearer $ASKEDITOR_API_KEY" ``` `clientRequestId` is **required**: reuse the same value on a retry and you cannot be charged twice for the same run. Connected via the [MCP connector](/docs/mcp/connect)? It is one sentence: > "Run the **Tracked Title Card** template on \~/Desktop/recording.mp4" The agent lists the menu, estimates (free), asks your consent, uploads, runs, and polls [`GET /v1/jobs/{id}`](/docs/setting-up/jobs-and-polling) to the finished envelope. **Editable delivery:** Delivers the finished mp4. The canvas form (base video, the tracked cards, and the subject cutout as separate live layers) ships with the card element; until then the card copy is baked. The occlusion is the entire effect: cards render BEHIND the subject, so a head or hand crossing one sells that it lives in the scene. Cards without occlusion are lower-thirds, and this template refuses to be one. Charged on completion, never on submit: a refusal or a failure costs nothing. The posted price and ETA are measured from real runs on this surface, not estimated. # Why AskEditor Source: https://askeditor.com/docs/why-askeditor Task-level video editing, not model inference, and every output is editable. ## Finished edits, not model outputs Model APIs give you inference: a clip from a prompt, a matte from a frame. AskEditor is one level up: **templates** are complete, directed edits (a launch film, a tightened take, a background removed and recomposed) with the judgment already encoded: composition rules, grading constants, cut craft, QA gates. You bring footage; the template brings the editor's eye. ## The editable canvas Every job returns `finalUrl` (mp4) **and** `canvasUrl`, the same edit as a live timeline. When your user says "almost, can the text come in later?", that's a drag in the editor, not a re-run of the pipeline. Results first, refinement when it's wanted. ## Built for agents The primary reader of these docs is an agent: * **MCP-native**: the connector is a first-class door, not a wrapper. * **Typed refusals**: a template that can't work on the given material says so with a machine-readable reason ([Refusals](/docs/setting-up/refusals)), before money is spent. * **Estimate before run**: price and blockers are a free call, so an agent can ask consent honestly. * **Machine-readable everything**: llms.txt, a stable OpenAPI URL, a JSON template index ([Agent surfaces](/docs/mcp/agent-surfaces)).