10 active keys per userRevoke one to mint another.
Credits are the only quotaOne meter with the product; plans include credits — see pricing. Top-ups: $10 for 40 credits.
Bytes never travel through the APIFootage arrives by URL fetch or a presigned PUT.
Request body: 4.5MB JSON ceilingA platform limit, not a design choice — send footage by URL or presigned PUT instead.
One open edit job per projectA second request while one is open is refused until it settles.
Reads are free, alwaysPace polling by poll_after_s in every job response.
Authentication
AuthorizationBearer rc_live_… — required on every authenticated call, both fronts.REQUIRED
Content-Typeapplication/json — required on POST.REQUIRED
A wrong key is indistinguishable from a missing one, by design.
REST — POST /api/model/v1/edit
Request
project_idThe project whose READY footage the model edits. Required.
briefEditing brief, up to 4000 characters. Optional.
target_duration_sMaximum length of the finished cut, in seconds (5-3600). Omit for AUTO — the footage decides the length.
aspect9:16, 1:1, or 16:9. Optional; defaults to the project setting.
edit_typetalking_head, voiceover, talking_broll, or music. Optional; defaults to the project setting.
Response — when RCM 1 is live (contract-final)
job_idIdentifies the queued job. Poll get_edit_status with it.
statusAlways "queued" on acceptance.
model_versionThe deployed model version that will fulfill this job.
credits_quotedDebited at accept time; refunded in full if the job fails.
credits_remainingBalance after this job’s credits are debited.
poll_after_sWait at least this many seconds before the first status poll.
Response — today (first-class, not a placeholder)
errorAlways "MODEL_NOT_DEPLOYED" today.
messageHuman-readable, live deployment truth — not a canned string.
active_versionThe deployed version pointer, when one exists. Deploy is not the same as serving.
inference_worker_armedWhether the RCM 1 inference worker seam is armed.
retryableAlways true. Retrying later is safe — the contract will not change.
use_insteadWhere edits work today: the bench-fulfilled queue.
as_ofISO 8601 timestamp of this answer.
Status codes
401 unauthorizedMissing or invalid API key. A wrong key is indistinguishable from a missing one, by design.
400 invalid_inputThe request body failed validation; zod field errors are attached.
503 MODEL_NOT_DEPLOYEDThe documented answer to every valid call today. Carries live deployment truth — a first-class response, not a placeholder.
500 internalAn unexpected server error.
GET — contract discovery
Public, no auth. Always returns the current machine-readable contract.
Lifecycles
Footage must reach status "ready" before request_edit will use it.
JobStatus
queuedAccepted, waiting to start.
analyzingWatching the footage.
cuttingDeciding what to keep and drop.
renderingProducing the output file.
doneFinished — the result is attached to this response.
failedDid not complete. Credits are refunded automatically.
FootageStatus
fetchingThe server is retrieving the file from a submitted URL.
uploadedBytes are in place; analysis has not started.
analyzingDuration and other properties are being read.
readyUsable by request_edit.
failedCould not be fetched or read.
ProjectStatus
awaiting_footageCreated; no footage submitted yet.
processing_footageFootage submitted; not all of it is ready yet.
ready_to_editAll submitted footage is ready.
editingAn edit job is in flight.
edit_readyAt least one finished edit exists.
No webhooks today. Every accepted mutation returns a job_id and each status response carries poll_after_s — that is the pacing contract. If webhooks ship they will be additive and announced on this page.
MCP reference
Streamable HTTP, JSON-RPC 2.0, stateless. initialize / tools/list / ping are public; tools/call needs a key.
initialize, tools/list, and ping are public. tools/call requires a key.
list_projects · FREE · READ-ONLY
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.
INPUT
limitintegerOPTIONAL
cursorstringOPTIONAL
OUTPUT
projectsarrayREQUIRED
next_cursorstringOPTIONAL
create_project · FREE · MUTATES
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.
INPUT
titlestringOPTIONAL
aspectstringOPTIONAL
target_duration_sintegerOPTIONAL
style_notesstringOPTIONAL
OUTPUT
project_idstringREQUIRED
uploadobjectREQUIRED
next_actionsarrayREQUIRED
submit_footage · FREE · MUTATES
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.
INPUT
project_idstringREQUIRED
source_urlsarrayOPTIONAL
request_upload_urlsarrayOPTIONAL
OUTPUT
footagearrayREQUIRED
upload_urlsarrayOPTIONAL
request_edit · METERED · MUTATES
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.
INPUT
project_idstringREQUIRED
briefstringOPTIONAL
target_duration_sintegerOPTIONAL
aspectstringOPTIONAL
edit_typestringOPTIONAL
variationsintegerOPTIONAL
OUTPUT
job_idstringREQUIRED
statusstringREQUIRED
estimated_sintegerREQUIRED
credits_quotednumberREQUIRED
credits_remainingnumberREQUIRED
poll_after_sintegerREQUIRED
get_edit_status · FREE · READ-ONLY
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.
INPUT
job_idstringREQUIRED
OUTPUT
job_idstringREQUIRED
statusstringREQUIRED
progress_pctnumberOPTIONAL
stage_messagestringOPTIONAL
poll_after_sintegerOPTIONAL
editobjectOPTIONAL
exportobjectOPTIONAL
errorobjectOPTIONAL
get_edit · FREE · READ-ONLY
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.
INPUT
edit_idstringREQUIRED
OUTPUT
edit_idstringREQUIRED
project_idstringREQUIRED
preview_urlstringREQUIRED
duration_snumberREQUIRED
decisionsarrayREQUIRED
droppedarrayREQUIRED
captions_availablebooleanREQUIRED
refine_edit · METERED · MUTATES
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.
INPUT
edit_idstringREQUIRED
notesarrayOPTIONAL
global_notesstringOPTIONAL
OUTPUT
job_idstringREQUIRED
statusstringREQUIRED
credits_quotednumberREQUIRED
credits_remainingnumberREQUIRED
poll_after_sintegerREQUIRED
export_edit · METERED · MUTATES
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.
INPUT
edit_idstringREQUIRED
resolutionstringOPTIONAL
captionsbooleanOPTIONAL
formatstringOPTIONAL
OUTPUT
job_idstringREQUIRED
statusstringREQUIRED
credits_quotednumberREQUIRED
credits_remainingnumberREQUIRED
poll_after_sintegerREQUIRED
get_account · FREE · READ-ONLY
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.
INPUT: no fields.
OUTPUT
planstringREQUIRED
credits_remainingnumberREQUIRED
credits_renew_atunknownREQUIRED
mcp_enabledbooleanREQUIRED
manage_urlstringREQUIRED
list_invoices · FREE · READ-ONLY
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.
INPUT
limitintegerOPTIONAL
OUTPUT
availablebooleanREQUIRED
rowsarrayREQUIRED
rcm1_edit · METERED · MUTATES
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.
INPUT
project_idstringREQUIRED
briefstringOPTIONAL
target_duration_sintegerOPTIONAL
aspectstringOPTIONAL
edit_typestringOPTIONAL
OUTPUT
job_idstringREQUIRED
statusstringREQUIRED
model_versionstringREQUIRED
credits_quotednumberREQUIRED
credits_remainingnumberREQUIRED
poll_after_sintegerREQUIRED
METERED: request_edit, refine_edit, export_edit + rcm1_edit. Every metered call quotes credits before work starts and refunds automatically on failure. Reads are free, always — one credit pool, shared with the web app.
Tool error codes
unauthorizedMissing or invalid API key.retryable: false
forbidden_planThe account’s plan does not include this tool.retryable: false · upgrade_url
not_foundThe referenced project, footage, or edit does not exist or is not yours.retryable: false
invalid_inputThe request failed validation, or (on request_edit/refine_edit) a job is already open for the project.retryable: sometimes — true when the cause is transient (an open job, footage still processing)
out_of_creditsThe balance is short of the quoted cost.retryable: false · upgrade_url
rate_limitedReserved. Not currently enforced during the dormant preview.retryable: true
job_failedThe job failed. Credits were refunded automatically.retryable: false — resubmit as a new job
model_not_deployedrcm1_edit’s honest-dormant answer, carrying live deployment status.retryable: true
internalAn unexpected server error.retryable: sometimes
JSON-RPC protocol errors (malformed envelope, unknown method) answer the standard -326xx codes; an unauthenticated tools/call answers -32001.
VERSIONING
The REST surface is path-versioned (/v1). Within v1, changes are additive only: fields are never removed or retyped, and new optional request fields or new response fields may appear — treat unknown fields and unknown enum values as forward-compatible. A breaking change ships as /v2, announced on this page and in the GET discovery payload, with at least 12 months of v1 support from the announcement. While the model is dormant, the v1 contract does not change shape before arming — retryable: true is that promise in the wire format. MCP: the server is at version 0.1; tools are additive, and a tool removal or breaking input change bumps the server version and is announced here at least 90 days ahead. Pricing on this page is a preview and may change at GA — the contract promise above is independent of pricing.