Upload, edit, render, deliver
- Upload. Request an upload URL, PUT the bytes, confirm.
upload_id is the item’s id from here on.
- Transcribe. Media under five minutes is transcribed within the call. Longer media returns a job, and once
get_jobsreports it done, the same call returns the stored words.
- Build a timeline. Create one, then add the clip.
sourceis the part of the file to use, in seconds. Leaving outfromplaces the clip after the last one on that track, and a fresh timeline has one visual track,visual-main. A fresh document nobody has edited accepts a write withoutif_revision.
- Check, then render.
check_timelineis free and reports problems a render would show. The render accepts an idempotency key made for this call.
- Get the result. By polling, or from a webhook.
One call over many items
The CLI is the same API from a shell, and--json returns { ok, data } with the tool’s data. A read tool also answers GET with query parameters.
update_items applies each item separately. A failure on one item is reported alongside the results for the others, and set names what changed on each. A page’s next_cursor, sent back with the same filters, returns the next page.
A charged call, retried
A generation is charged when it starts, so the idempotency key is what makes a retry safe.503 unavailable or a dropped connection, a retry with the same body and the same key returns the job already started, and nothing is charged twice. A 402 insufficient_credits won’t succeed on a retry. get_balance shows what is left and where more can be added, and get_checkout_link returns a link where the user can pay.
estimate_cost gives the price of the same call before it runs, for free, from the same rates.
