realcut

List projects

List the user's Real Cut projects, newest first, with status and footage counts. Use this to find an existing project before creating a new one, or to recover a project_id the user refers to by name. Free; paginate with cursor.

Create project

Create a new editing project and get back a project_id plus a browser upload link (magic_link) the user can open to drag footage in. Use submit_footage instead of the link when the footage is reachable by URL. Set aspect and target duration here if the user already knows them; duration left unset means AUTO — the footage decides the length. Free.

Submit footage

Add raw footage to a project without moving bytes through the conversation: pass source_urls for the server to fetch (Drive links, public MP4s), or request presigned upload URLs for a programmatic pipeline. Returns per-file footage_ids and ingest status; footage must reach status "ready" before request_edit will use it. Free per call; stored footage is metered by plan tier.

Request an edit

Ask Real Cut to edit the project's footage into a finished cut: it watches the raw footage, decides what to keep and drop, and produces a cut with per-decision rationale. Costs credits (credits_quoted in the response; refunded automatically if the job fails). Returns a job_id immediately — the edit runs asynchronously, so poll get_edit_status until status is "done", then call get_edit to read the result.

Check edit status

Check the progress of an edit or export job by job_id. Returns the current stage with an honest one-line stage_message you can relay to the user, plus poll_after_s for the next check. On "done" it carries the edit (or export download URL); on "failed" the reason and confirmation that credits were refunded. Free — poll as often as the response suggests.

Read the finished edit

Read a finished edit: preview URL, the ordered list of editing decisions (source clip, in/out timecodes, transcript, and the rationale for keeping each segment), and what was deliberately dropped and why. Use the rationale to explain the cut to the user and the timecodes to anchor refine_edit notes. Free.

Refine an edit

Revise an existing edit with time-anchored notes ("keep the laugh at 0:42", "0:10–0:15 too slow, tighten") and/or whole-cut direction. Produces a new version; the previous one is kept. Costs credits (less than a fresh request_edit; refunded on failure). Returns a job_id — poll get_edit_status, then get_edit for the new version.

Export an edit

Render an edit to a downloadable file (mp4, optional burned-in captions, chosen resolution). Costs credits; refunded on failure. Returns a job_id — poll get_edit_status until "done", which carries a signed download_url that expires, so pass it to the user promptly.

Account and credits

Read the user's plan, remaining credits, renewal date, and whether MCP access is enabled for their tier. Call this before quoting costs to the user or when a tool returns out_of_credits. Free.

List invoices

List the user's Real Cut payment history — invoices and receipts, newest first: date, amount, status, invoice number, and links to the hosted invoice page, the invoice PDF, and the receipt. Links are fetched live and expire, so pass them to the user promptly. available:false means billing is not configured. Free.

RCM 1 direct edit (dormant)

Ask the RCM 1 model directly for an edit of a project's footage — the same job/poll pattern as request_edit, fulfilled by the deployed model version instead of the bench. DORMANT TODAY: returns model_not_deployed (with the live deployment status) until a trained version is deployed and the inference worker is armed. Use request_edit meanwhile — it is the same queue the web app uses.