Typecut API reference

List projects

Returns the projects the authenticated API key can access. Account-level keys see all projects in the account; workspace-scoped keys see only projects in their workspace. Cursor-paginated (created_at DESC, id DESC).

Parameters

Response — 200

200 A page of projects.400 Invalid query parameters.401 Missing or invalid API key.

Create a project

Create a new project. Mode-discriminated by `mode`: - `templates` — runs the full plan → scaffold → generate pipeline from a template + a topic (`prompt`) or your own `script` (markdown-structured supported). The main path. - `blank` — an empty project with one chapter, no planning; edit it via later API calls. For `templates`, call GET /v1/projects/requirements first to learn the required inputs (and preview a script's parsed structure).

Request body

Response — 201

201 Project created.400 Invalid request body.401 Missing or invalid API key.402 Plan limit reached (free tier project cap, lapsed subscription, etc).403 API key cannot create projects in the requested workspace.

List media assets

Returns the media library assets the API key can access (confirmed, excluding scene thumbnails). RLS-scoped to the account; workspace-scoped keys see only their workspace. Cursor-paginated (created_at DESC, id DESC). Optional `project_id` filter.

Parameters

Response — 200

200 A page of media assets.400 Invalid query parameters.401 Missing or invalid API key.

Add media to the library

Record an already-hosted asset URL into the project media library. This is for URLs that are already reachable (e.g. your own hosted file); it does not upload a file. Rate-limited per account.

Request body

Response — 201

201 Media asset recorded.400 Invalid request body.401 Missing or invalid API key.403 project_id is outside the key's workspace scope.404 project_id not found for this account.429 Rate limit exceeded.

Import an external asset

Download an EXTERNAL url (a discovery result, a file on the web) and re-host it on Typecut storage as a library asset with provenance + dimensions, captioned on ingest. Free. Use this, not the raw provider url, before building a scene on found material — provider links expire. Contrast POST /media, which records a url you host yourself without copying it.

Request body

Response — 201

201 Asset imported.400 Invalid request body or unreachable url.401 Missing or invalid API key.403 project_id is outside the key's workspace scope.404 project_id not found for this account.429 Rate limit exceeded.

Get a link to upload a file

A short-lived signed link to PUT ONE file from your own disk, so its bytes never pass through an agent's conversation. Text (html, js, css, json; UTF-8, up to 2,000,000 bytes): pass public_url as a scene's src_url or reference it from scenes with <script src>. AUDIO you rendered yourself (wav, mp3, ogg, m4a, flac; up to 50 MB, counted against the storage quota) goes straight to storage: PUT it to the presigned upload_url with the returned headers (Content-Type is signed), then POST complete_url, which checks the stored bytes' magic number, records the file in the media library and as a music track that is transcoded and tempo/beat-analysed like any other (kind "sfx": library entry only), and returns track_id; the returned curl does both. Then PATCH /projects/{id}/music with trackId (or url: public_url) makes it the project music. Same access as landing authored compositions. Images and video also go straight to storage (see complete_url). Free.

Request body

Response — 200

200 Upload link issued.400 Invalid body or an unsupported extension.401 Missing or invalid API key.403 The account may not land authored work.

Send the file to an upload link

The upload_url POST /uploads returned. Authorised by the signed token in the path, not an API key: send the raw bytes (curl -X PUT --data-binary @file). Text and fonts only: text must be UTF-8, a font must carry its container's magic number (otherwise 415 type_mismatch). An audio, image or video token is refused here (400 wrong_door): those go to their presigned upload_url, then complete_url.

Parameters

Response — 200

200 Stored.400 Empty body, text that is not UTF-8, or an audio/image/video token (wrong_door).403 The link is invalid or has expired.413 Over the size cap.415 The font bytes are not the format the file name promised.

Finish an image, video or audio upload

After the bytes of an image/video/audio upload are in storage (one PUT to upload_url, or every part), POST here. Assembles a multipart upload, checks the stored file (its magic number must match the extension; size caps; the plan's storage) and files it in the media library through the ingest pipeline. Audio also becomes a music track (transcoded + tempo/beat-analysed; not for kind "sfx") and the response is ReceivedUploadResponse (track_id, asset_id, analysis). A refused file is deleted. Authorised by the signed token in the path. Idempotent.

Parameters

Response — 200

200 Filed. Image/video: CompletedMediaUploadResponse; audio: ReceivedUploadResponse.400 Empty file.403 The link is invalid or has expired.409 Nothing uploaded yet, or parts missing (listed).413 Over the size cap, or the plan's storage is full.415 The bytes are not the format the file name promised.

Get the upload URL for one part

For a multipart image/video upload: the presigned storage URL for part n (1..part_count), as plain text (JSON with Accept: application/json). PUT bytes [(n-1)·part_size, n·part_size) of the file to it. Authorised by the signed token in the path.

Parameters

200 The part URL.400 Not a multipart upload, or n out of range.403 The link is invalid or has expired.

Mint a key scoped to one project

A long-lived API key (default 30 days, up to 90) for a CLI session on this project (typecut dev / typecut add). It reaches only /projects/{id}/… and POST /uploads (which files into this project), plus GET /me; it cannot mint keys. Listed and revocable in Settings → API keys. Free.

Parameters

Request body

Response — 201

201 Minted.403 Called with a project key.404 No such project.

Revoke a project CLI key

Parameters

Response — 200

200 Revoked.404 No live CLI key with that id on this project.

Hear a stretch of the film (the mix, measured)

The export's own mix of a window on the film clock (at most 120 s), rendered whole and per group — dialogue (narration + scene speech), music (cues and beds), effects (SFX + scene sounds) — and measured: short-term LUFS every 0.5 s per group, integrated loudness and true peak against -14 LUFS / -1 dBTP, sounds more than outlier_db (default 6) above their surroundings named by cue / sound / scene, music or effects within mask_db (default 6) of the voice in 1-2 / 2-4 kHz while it speaks, the voice-over-bed ratio, and verdicts in words. bounce: true also hosts an m4a of the window. Free.

Parameters

Request body

Response — 200

200 Measured.400 Bad window.404 No such project.

Ingest a video link (admin-only)

ADMIN-ONLY. Download a public video from a link — X/Twitter, TikTok, Reddit, Instagram, a direct file, or a file already on Typecut storage — and host it as a library video with poster, subtitles and source metadata, ready for analysis. Free. Asynchronous: the first call returns 202 `status: "pending"`; call again with the same url to poll (200, same asset). A failed ingest is retried by calling again. YouTube is refused (422 youtube_unsupported): it blocks server downloads.

Request body

Response — 200

200 Existing ingest for this url, in its current state.202 Ingest queued.400 Invalid request body.401 Missing or invalid API key.403 Not an admin, or project_id outside the key's workspace scope.404 project_id not found for this account.422 YouTube url (youtube_unsupported).

Read a project’s sources and transcripts

What the project was grounded in and what was said in it. Each source reports its state and, when something went wrong, the reason in words — the read half of transcription, without which a caller can start work it cannot observe. Transcripts come back as timed SEGMENTS rather than words: a quote and a clip window are the same object, and words are 180 KB nobody can hold. Free.

Parameters

Response — 200

200 The project’s sources.401 Missing or invalid API key.404 Project not found for this account.

Read the project’s asset shelf

Everything the film could use — the user’s files and what discovery and stock found for the topic — each with a licence, a relevance score and a decision (auto · kept · pinned · rejected). Decided items come first. Free.

Parameters

Response — 200

200 The shelf.401 Missing or invalid API key.404 Project not found for this account.

Put found material on the asset shelf

Add up to 50 candidates an agent found — an imported clip, a figure, a post — with what it is (caption, entities), the beat it serves, relevance, licence and credit, for a person to keep, pin or reject. Each item needs media_asset_id (preferred: hosted, cannot expire) or url. Unknown licence is allowed; such items are placed only when pinned. Idempotent on url: a re-add refreshes the description and never changes a decision. Free.

Parameters

Request body

Response — 201

201 Items added (and any already on the shelf refreshed); skipped lists items that could not be added and why.400 Invalid body.401 Missing or invalid API key.404 Project not found for this account.

Keep, pin or reject shelf items

Set decisions on up to 50 shelf items. pinned = must be placed in the film (the note says how, e.g. "use for the intro"); kept = may be used; rejected = never used; auto = back to undecided. Free.

Parameters

Request body

Response — 200

200 The updated items, and any ids not on this shelf.400 Invalid body.401 Missing or invalid API key.404 Project not found for this account.

Transcribe a recording in the library

Read the words out of an audio or video asset already in the library and record them as a project SOURCE, with word-level timings. The second door to speech-to-text: `sources` on POST /projects only exists at creation time and only takes a url, so a file already in a project was otherwise unreachable. SPENDS CREDITS by duration (~1 credit per minute of audio, from a generation_pricing row). Asynchronous — 202 with a status to poll; a repeat call on the same asset reports state rather than queueing a second pass, and costs nothing.

Parameters

Request body

Response — 200

200 Already transcribed.202 Transcription started or already running.400 Not an audio/video asset, or no project to ground.401 Missing or invalid API key.402 Not enough credits for a recording of this length.404 Media asset or project not found for this account.429 Rate limit exceeded.

Clone a voice from a recording

Start cloning a voice from a library asset (media_id) or a url (upload_url). The recording is checked (at least 10s of speech, at least 40% of it speech, not too noisy or clipped); the best 10–30s stretch becomes the reference clip and is transcribed. On success a voice (tts_presets row) is created for the account. Asynchronous — 202 with an id; poll GET /voices/clones/{cloneId}. Requires consent.attested = true. Disabled unless the deployment enables voice cloning (403 feature_disabled).

Request body

Response — 202

202 Accepted — processing.400 Invalid request, or consent.attested is not true (consent_required).401 Missing or invalid API key.403 Voice cloning is not enabled (feature_disabled).404 Media asset not found for this account.429 Rate limit exceeded.

Get a voice clone

The state of a voice clone: processing, ready (with tts_preset_id to narrate with) or rejected (with reject_reason), and the intake measures. Free.

Parameters

Response — 200

200 The voice clone.401 Missing or invalid API key.403 Voice cloning is not enabled (feature_disabled).404 Voice clone not found for this account.

Take to voice

Listen to a recorded take (words and timings, sounds, mood), write it as Drama 3 expression tags and pauses, and speak it in a chosen voice. Asynchronous: 202 with an id; poll GET /voices/perform/{performanceId}. dry_run quotes. Pacing, pauses, sighs and mood survive; singing and real laughs do not. Credits: listening per second of take, plus the voice; refunded on failure.

Request body

Response — 200

200 dry_run: the quote.202 Accepted: listening.400 Invalid request.401 Missing or invalid API key.402 Not enough credits.404 Take or voice not found for this account.429 Rate limit exceeded.

Get a take-to-voice run

Where a run is: queued, listening, writing, speaking, ready (url, text_with_tags, heard) or failed (error; credits refunded). Free. The call that finds the tags written also speaks the line, so it can take a few seconds.

Parameters

Response — 200

200 The run.401 Missing or invalid API key.404 Not found for this account.

Analyse a reference video

Break any video into what an agent can read, in one call: frame-accurate shots (ffmpeg scene cuts, adaptive dark-scene cuts and dips to black) with duration, motion energy, a 480p keyframe, a class (talking head, B-roll, screen recording, motion graphics, title card…), on-screen text, graphics and voice-over; contact sheets of up to 16 shots with the shot number and time range burned in; the transcript; the sound (speech / music / singing segments, timed sound effects, and the music reading only when there is music); and `condensed`, the whole video as one readable timeline. The first 10 minutes are analysed. Asynchronous — 202 with an analysis at queued; poll GET /video-analyses/{analysisId}. 200 when the same source + options already has an analysis (returned instead of a new job). Free.

Request body

Response — 200

200 An existing analysis of this source (ready or still running).202 Accepted — queued.400 Invalid request (not exactly one source, not a video, bad url).401 Missing or invalid API key.404 Media asset not found for this account.429 Rate limit exceeded.

Get a video analysis

The state of a video analysis: queued / processing (poll again), ready (result) or failed (error). ?words=true adds the word-level transcript. ?t0=&t1= (seconds) cuts the result to one stretch — shots, words, sound segments, sfx and music marks inside it. result.motion says what moves inside shots (events/min, static share, blank runs, recommended_probes); its events page by t0/t1. ?detail=events|strips (with t0/t1, optional fps) re-senses the window: exact motion events, or labelled dense frames (window at most 30 s). Free; CPU, seconds.

Parameters

Response — 200

200 The analysis.400 The id is not a uuid.401 Missing or invalid API key.404 Analysis not found for this account.

Find the best clips in an analysed video

The best self-contained reels in an analysed video, ranked 0-100, each with snapped cut points (start on a sentence start with a short head; end on a sentence end with a 0.45 s tail past the last word), the hook line, a cold-open suggestion when the strongest line is not the first, the transcript, the signals and the reasons. Needs a ready analysis with a speech transcript. A transparent heuristic, not a view prediction. Free; CPU, seconds.

Parameters

Response — 200

200 Ranked clip candidates.400 Bad id/options, or the analysis has no usable speech.401 Missing or invalid API key.404 Analysis not found for this account.409 The analysis is not ready yet.

A picture of an analysed source at any time, width and crop

One hosted JPEG per requested time of the analysed source: "the reference at 47.3 s, 640 wide, the lower third" without re-sensing a window. The urls are named by content, so the same request returns the same urls and a repeat decodes nothing. A time past the end returns the last frame (noted). Free; CPU, seconds.

Parameters

Response — 200

200 The frames.400 Bad id, times, width or crop; or the analysis failed.401 Missing or invalid API key.404 Analysis not found for this account.

Analyse audio or a music track

What a recording contains, as data: detect (music / speech / singing / silence timeline and tags) and, for music, the tracked beats and bars, drum hits with accent, bass and lead notes, key, sections with energy and the salient moments. Up to 20 minutes. Asynchronous — 202 with an analysis at queued; poll GET /audio-analyses/{analysisId}. 200 when the same source already has an analysis (returned, free). PRICED per second of audio (about 1 credit per minute); library tracks are free; a failed analysis is refunded.

Request body

Response — 200

200 An existing analysis of this source (ready or still running).202 Accepted — queued and charged.400 Invalid request (not exactly one source, not audio/video, too long, still ingesting).401 Missing or invalid API key.402 Not enough credits.404 Media asset or track not found for this account.429 Rate limit exceeded.

Get an audio analysis

The state of an audio analysis: queued / processing (poll again), ready (result) or failed (error; refunded). ?events=hit.snare,downbeat&t0=&t1= adds those event lists windowed to seconds. Free.

Parameters

Response — 200

200 The analysis.400 The id is not a uuid.401 Missing or invalid API key.404 Analysis not found for this account.500 The event file could not be read.

Audition voices

Synthesise the same short line with up to 4 voices — library presets or your own clones — and get a playable clip per voice. Synchronous. A voice that fails comes back with `error` beside the others. Free; rate limited per account (429 with retry_after).

Request body

Response — 200

200 One clip (or error) per voice.400 Invalid request (no voices, more than 4, text over 400 characters).401 Missing or invalid API key.429 Audition rate limit reached.

Speak a line into the library

Speak ONE line (≤1500 characters) with ONE voice — a library preset or your own clone — and keep it as a library audio asset with word timings. Synchronous. Charged at the voice-over rate (per character, the voice provider's price); refunded if the voice fails. Rate limited per account (429 with retry_after).

Request body

Response — 201

201 The spoken line.400 Invalid request.401 Missing or invalid API key.402 Not enough credits.404 No such voice.429 Rate limit reached.502 The voice provider failed (credits refunded).

Generate or edit a picture

Make ONE standalone image — text-to-image, or an edit of the given reference image(s) — into the project media library. SPENDS CREDITS (generation type `image-chat`). Not a scene element: use the returned url as a scene background, as a `reference_image_url`, or as the input of another edit. Waits up to ~50s by default; a slower image returns 202 with `status: "generating"` — poll GET /generations/{id}. A failed job refunds its credits.

Request body

Response — 200

200 Finished (or failed after starting — see `status`).202 Still generating; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id not found for this account.

Generate a video clip

ONE standalone clip (≤ 8 s) into the media library: image-to-video from asset_id / image_url, or text-to-video from the prompt. SPENDS CREDITS per second (generation type `video-gen`); dry_run quotes. Clips take 30 s to a few minutes: waits ~50 s, then 202 `status: "generating"` — poll GET /generations/{id} or POST /status. A failed job refunds its credits.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Make a face speak

A face (library image or video, or a public https url) lip-synced to a voice (a library audio asset such as a speak result, or a public https audio url with audio_seconds). At most 60 s of voice per clip. SPENDS CREDITS per second of voice (generation type `talking-head`); dry_run quotes. Takes a minute or more: waits ~50 s, then 202 `status: "generating"` — poll GET /generations/{id} or POST /status. A failed job refunds its credits.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Upscale a picture

One picture at 2× or 4× the pixels, re-hosted as a PNG library asset. SPENDS CREDITS (generation type `image-upscale`); dry_run quotes. Waits up to ~50s. `model` runs one upscaler (GET /catalogs/models?modality=upscale) instead of the deployment's chain in order.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Generate a storyboard or sprite sheet

MANY pictures from ONE image call, each cell hosted as its own library asset plus a contact sheet. mode `panels`: a cols × rows storyboard (≤ 4 × 4) of consecutive beats on one set with one cast — drawn together they keep the set, characters and story state consistent, for one call. mode `items`: a sprite sheet of ≤ 12 labelled props, each cut out. mode `sprite`: an animation strip of one action. SPENDS CREDITS: the model's per-call price for the sheet (generation type `image-grid` for models without one) + the `image-upscale` price per cell with `upscale`; dry_run quotes. Waits ~50 s, then 202 `status: "generating"` — poll GET /generations/{id}, whose `result` is the same compact grid. 503 `not_available` while the sheet job is rolling out.

Request body

Response — 200

200 Finished (`result` {mode, model, contact_sheet_url, cells[{index, label?, url, asset_id, width, height, box}]}), failed after starting, or a dry-run quote {credits, cells, available}.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id not found for this account.503 not_available: the sheet job is not on production yet.

Find the named parts of a picture

Per named part: a mask PNG (alpha), box [x,y,w,h], polygon, SVG path, centroid and quad. SPENDS CREDITS (generation type `image-segment`); dry_run quotes. Waits up to ~50s; a slower call returns 202 with `status: "generating"` — poll GET /generations/{id}, whose `result` carries the same output. A failed job refunds its credits.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Depth map of a picture

A 16-bit depth PNG (white = near) and parallax bands with z and a mask each. SPENDS CREDITS (generation type `image-depth`); dry_run quotes. Waits up to ~50s; a slower call returns 202 with `status: "generating"` — poll GET /generations/{id}, whose `result` carries the same output. A failed job refunds its credits.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Clean plate

The picture with the named parts inpainted away, same size as the source. SPENDS CREDITS (generation type `image-plate`); dry_run quotes. Waits up to ~50s; a slower call returns 202 with `status: "generating"` — poll GET /generations/{id}, whose `result` carries the same output. A failed job refunds its credits.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Cut a part out of a picture

The named parts (default: the main subject) on transparency. SPENDS CREDITS (generation type `image-cutout`); dry_run quotes. Waits up to ~50s; a slower call returns 202 with `status: "generating"` — poll GET /generations/{id}, whose `result` carries the same output. A failed job refunds its credits.

Request body

Response — 200

200 Finished, failed after starting, or a dry-run quote.202 Still running; poll GET /generations/{id}.400 Invalid request body.401 Missing or invalid API key.402 Insufficient credits.404 project_id or asset_id not found for this account.

Get a generation

Poll ONE credit-spending job by the `generation_id` the starting call returned (POST /media/generate, POST /scenes/{sceneId}/elements, …): status, error, and for an image the finished asset. GET /projects/{id}/resolution answers for a whole project; this is the per-job receipt. 404 (not 403) when not accessible. `wait` (seconds, ≤ 120) holds the answer until the job is completed or failed, or the wait is up — one call instead of a poll loop.

Parameters

Response — 200

200 The generation.400 Malformed id.401 Missing or invalid API key.404 Generation not found or not accessible.

Cancel a running generation

Stop a render-project job (more job types later; others answer 422). Queued scenes are dropped, in-flight GPU scene jobs are aborted and the film stitch is skipped. Billing: only scenes already rendered are charged (cached scenes are free); the remaining credits are refunded once through the credit ledger, never twice. Idempotent, and safe on a job that already finished: it returns the final state unchanged. Only the account that owns the generation can cancel it (404 otherwise). GET /generations/{id} then shows `status: cancelled`, `charged_credits` and `scenes_rendered`.

Parameters

Response — 200

200 The generation after the cancel (or its final state).400 Malformed id.401 Missing or invalid API key.404 Generation not found or not accessible.422 This generation type cannot be cancelled yet.503 Render service unavailable; the cancel was not delivered. Retry.

Get a project

Fetch one project by id. Returns 404 (not 403) when the project exists but is not accessible by the API key — so callers cannot probe for existence.

Parameters

Response — 200

200 Project found.401 Missing or invalid API key.404 Project not found or not accessible.

Get a project generation trace

A token-light audit of how a project was planned and generated — what template resolved, whether it drove the plan, the pacing decision, per-scene/model summaries, and LLM step summaries. Compact by default; opt into detail with ?include=raw (full structure_config/prompt_config/catalog + per-element model list) and/or ?include=prompts (full LLM prompt blobs). 404 (not 403) when not accessible.

Parameters

Response — 200

200 The project trace digest.401 Missing or invalid API key.404 Project not found or not accessible.

List workspaces

Returns the workspaces the API key can access. Account-level keys see all workspaces; workspace-scoped keys see only the one they are scoped to. Archived workspaces are omitted. Cursor-paginated.

Parameters

Response — 200

200 A page of workspaces.400 Invalid query parameters.401 Missing or invalid API key.

Create a workspace

Create a workspace: one per brand, channel or client, carrying the defaults its projects inherit. Account-level keys only (workspace-scoped keys get 403). Limited by the plan (max_channels); archived workspaces do not count. Over the limit returns 402 plan_limit_reached with `limit`, `current` and `upgrade_url`.

Request body

Response — 201

201 Workspace created.400 Invalid body.401 Missing or invalid API key.402 Plan workspace limit reached, or subscription inactive.403 The key is scoped to one workspace.

Get a workspace

Fetch one workspace by id. Returns 404 (not 403) when the workspace exists but is not accessible by the API key.

Parameters

Response — 200

200 Workspace found.401 Missing or invalid API key.404 Workspace not found or not accessible.

Search open & archival assets

Entity-grounded asset search across open / archival sources (Wikimedia Commons, NASA, ...). Resolves the query to a real-world entity, fans out to the sources, filters to commercially-usable licenses, and returns ranked candidates with license + provenance. Read-only; no asset is downloaded or stored by this call.

Request body

Response — 200

200 Ranked, license-cleared candidates.400 Invalid request body.401 Missing or invalid API key.502 Upstream discovery engine error.

Get render status

Poll the latest render job for a project: phase, per-scene progress, stitch progress, and the final MP4 URL (`render_url` / `job.output_url`) once completed.

Parameters

Response — 200

200 Current render status.404 Project not found or not accessible.

Render a project to video

Trigger a full project video render. Validates readiness first: every chapter that has narration/dialogue must have its voiceover (a chapter with nothing spoken — music only, or silent — needs none; nor does a project with no voice) and every scene must have visual content. On readiness failure the 422 response carries machine-readable `blockers` (chapter ids missing audio, scene ids missing visuals) so callers can resolve them programmatically. Credits are deducted up front and refunded automatically if the render cannot be queued. Poll GET /projects/{id}/render for progress and the final MP4 URL.

Parameters

Request body

Response — 202

202 Render queued.402 Insufficient credits.404 Project not found or not accessible.409 Project is already rendering.422 Project not ready to render — `blockers` lists the chapters missing audio and scenes missing visuals.503 Render queue unavailable (credits were refunded).

List thumbnail options

The project's current thumbnail, every generated option, and thumbnail generations still running.

Parameters

Response — 200

200 Thumbnails.404 Project not found or not accessible.

Generate thumbnail options

Design 1–3 YouTube thumbnail options, each a different concept, styled after a frame of the video unless `reference_url` is given. Charged per option up front; options that fail are refunded. Asynchronous — poll GET /projects/{id}/thumbnails until `pending` is empty. Never replaces a thumbnail the project already has; choose one with PUT.

Parameters

Request body

Response — 202

202 Generation queued.400 Invalid body.402 Insufficient credits.404 Project not found or not accessible.503 Queue unavailable (nothing was charged).

Set the project thumbnail

Make one image the project thumbnail: a generated option, or a file already in your library.

Parameters

Request body

Response — 200

200 Thumbnail set.400 Not a candidate or library file.404 Project not found or not accessible.

Get resolution status

What's resolved vs unresolved in a project, and the estimated credits to resolve the rest. A scene is resolved once it has renderable content; voice-over is tracked per chapter. Read-only counterpart to POST /projects/{id}/resolve — the counts match the editor's readiness UI exactly (shared logic).

Parameters

Response — 200

200 Resolution status + cost quote.404 Project not found or not accessible.

Resolve (generate) unresolved work

Generate everything unresolved in a scope — its unresolved scenes (composition) plus voice-over. Mirrors the editor's "Generate everything" actions; each underlying generation charges and refunds itself. Scenes with nothing to generate from are skipped (`skipped_unresolvable`). Pass `dryRun:true` for the credit quote without firing anything (identical numbers to GET /projects/{id}/resolution).

Parameters

Request body

Response — 200

200 Dry-run quote — nothing was fired.202 Resolution started — generations were queued.400 Invalid scope (e.g. chapter scope without chapterId).403 Subscription inactive (past_due / unpaid).404 Project, chapter, or block not found.

List a value catalog

The discoverability layer: every value project creation/editing accepts by id or slug is listable here, straight from the live registries. Catalogs: `transitions` (scene transition slugs + render mode + default duration), `caption-styles` (caption style ids + preview clips), `voices` (TTS presets — system + your own; each with provider, model, tier, supported_languages, is_clone and a preview in the `language` asked for when baked; filter with ?language= and ?provider=), `music` (published music tracks + license info). Pass the returned slug/id values to the matching creation or editing fields.

Parameters

Response — 200

200 Catalog rows.404 Unknown catalog.

Attach media to a scene

Set a scene's background to an image or video URL. The first editor-mutation primitive on the API: it shares the editor's media-attach service, so the change appears live in any open editor (via Realtime, applied in place) and behaves identically to picking media in the UI. Scene ids are globally unique, so the flat path is unambiguous.

Parameters

Request body

Response — 200

200 Media attached; scene background updated.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.

List every look you can pick or author

Brand-mark motion (built-ins marked `built_in`, active authored rows, your own held drafts) and caption motion (the published catalog plus your own private ones). Narrow with `?slot=`.

Parameters

Response — 200

200 The catalog.401 Missing or invalid API key.

Author a formula

A formula is a look expressed as INGREDIENTS in a row, linted at write, instead of a code drop. Two systems carry them and this is the one place to see and write both. **slot `bug`** — the brand mark's motion. `spec` is `{recipe, params}` over three carriers: `entry-exit`, `beat-envelope` and `trigger-lift`; `on` names a ruler (bar, beat, 2beat, hit, cam). You choose the slug. The row is born `held` and reaches no render until it is promoted to `active`. A spec that could strobe or reach outside its own element is refused (422). **slot `caption`** — how words move: entry/life/exit/field ingredients. The id is MINTED from the title, because the renderer keys the compiled template on the row id, so a slug is not honoured and the reply carries the id that was used. Saved private; reaching the shared catalog is moderated rather than a status flip. Both are validated by composing the real thing and checking what comes out, not by matching a schema: either grammar can be valid JSON and still name an ingredient that does not exist, which renders as a duller look with no error anywhere.

Request body

Response — 201

201 Stored.400 Invalid body.401 Missing or invalid API key.409 Reserved built-in slug, or an operation the slot does not support.422 The spec failed its linter; the message lists every problem.

Author or replace a brand-mark formula

A formula is a look expressed as INGREDIENTS in a row, linted at write, instead of a code drop. Two systems carry them and this is the one place to see and write both. **slot `bug`** — the brand mark's motion. `spec` is `{recipe, params}` over three carriers: `entry-exit`, `beat-envelope` and `trigger-lift`; `on` names a ruler (bar, beat, 2beat, hit, cam). You choose the slug. The row is born `held` and reaches no render until it is promoted to `active`. A spec that could strobe or reach outside its own element is refused (422). **slot `caption`** — how words move: entry/life/exit/field ingredients. The id is MINTED from the title, because the renderer keys the compiled template on the row id, so a slug is not honoured and the reply carries the id that was used. Saved private; reaching the shared catalog is moderated rather than a status flip. Both are validated by composing the real thing and checking what comes out, not by matching a schema: either grammar can be valid JSON and still name an ingredient that does not exist, which renders as a duller look with no error anywhere. This route is the `bug` slot only; author a caption formula with POST /formulas.

Parameters

Request body

Response — 200

200 Stored, with what the spec emits.400 Invalid body or slug.401 Missing or invalid API key.403 The slug belongs to another account.409 The slug is a reserved built-in.422 The spec failed the linter.

Promote, park or retire a brand-mark formula

Move a formula between `held`, `active` and `disabled`. Promotion re-lints the stored spec, because `active` is the moment it starts reaching renders and a row may have been written under an older contract. A disabled formula leaves existing projects rendering a static mark. The `bug` slot only: a caption formula has no held/active machine, because publishing to the shared catalog is moderated.

Parameters

Request body

Response — 200

200 Status changed.401 Missing or invalid API key.403 The formula belongs to another account.404 No such formula.409 The caption slot does not support a status change.422 The stored spec no longer passes the linter.

What is true at this moment of the project

The read to make BEFORE authoring anything that has to land ON something — a brand-mark formula, a cue, a reactive overlay. It answers, in one call, the questions that decide whether an authored thing will actually fire: - **narration** — the words this scene speaks and the second each is HEARD. Already on the timeline clock, so pauses and silence trims are applied; `retimed` says whether this block has any. A cue addressed at a word from this list will resolve. - **rulers** — the grid a formula resolves against, and the cues already resolved to `hit:<name>`. `source: "archetype"` means the 100 BPM fallback, not the track. - **cues** — each authored cue with `resolvesAt`. `null` means it will NEVER fire, which is otherwise invisible until you watch the export and see nothing happen. - **signals** — whether an audio signal exists to bind to, and its channels. - **mark** — what the bug is set to now, and which slugs it can take. Assembled from the renderer's own functions, so what you read here and what the MP4 does are one computation rather than two that ought to agree. It does not restate structure or composition — GET /scenes/{sceneId} returns the source.

Parameters

Response — 200

200 The scene's resolved temporal and signal facts.401 Missing or invalid API key.404 Scene not found.

Read a scene's named moments

Named moments on a scene. A cue does NOTHING on its own — it is an ADDRESS, so something else can be told to fire on it. Today the brand mark reads them: PUT /projects/{id}/branding with `formula: "ghost"` rests the mark low and lifts it on `hit:<name>`, which is how a subscribe bump lands on the exact word rather than on a beat. `at` is seconds from the scene start, or a moment on the scene's own rulers — `word:subscribe`, `word:#4`, `bar:3`, `beat:7`, `cam:hero`, `end-2`, with `+0.25` / `+1b` / `+2B` offsets. Prefer the moment form: a cue pinned to a word survives a re-cut of the narration and one pinned to 4.2s does not. It resolves at render against the scene's measured grid, and a cue that does not resolve is dropped rather than firing at zero. The list is REPLACED, not merged.

Parameters

Response — 200

200 The scene's cues.401 Missing or invalid API key.404 Scene not found.

Replace a scene's named moments

Named moments on a scene. A cue does NOTHING on its own — it is an ADDRESS, so something else can be told to fire on it. Today the brand mark reads them: PUT /projects/{id}/branding with `formula: "ghost"` rests the mark low and lifts it on `hit:<name>`, which is how a subscribe bump lands on the exact word rather than on a beat. `at` is seconds from the scene start, or a moment on the scene's own rulers — `word:subscribe`, `word:#4`, `bar:3`, `beat:7`, `cam:hero`, `end-2`, with `+0.25` / `+1b` / `+2B` offsets. Prefer the moment form: a cue pinned to a word survives a re-cut of the narration and one pinned to 4.2s does not. It resolves at render against the scene's measured grid, and a cue that does not resolve is dropped rather than firing at zero. The list is REPLACED, not merged.

Parameters

Request body

Response — 200

200 Cues replaced.400 Invalid body, an unaddressable cue name, or a duplicate.401 Missing or invalid API key.404 Scene not found.

Read a project's brand mark

The pinned brand mark — the corner "bug" — on one project: image, corner, size, opacity, and a MOTION FORMULA. Before this endpoint the mark was reachable only from the settings panel and the creation wizard, so a film built through the API came out unbranded even for a channel that has a logo configured. Every field is optional and only what you send changes: branding shares `projects.settings` with captions, audio and theme, so the write is a merge. `formula` is what makes the mark live. `none` is a static stamp; `tick` squashes it on every downbeat of the project's own measured grid; `ghost` rests it low and lifts it on an authored scene cue. The motion compiles against the same bars the composition uses, so it lands with the music rather than near it. Amplitudes are capped and ticks carry a cooldown — a mark cannot be made to strobe. An unknown slug is refused rather than silently rendering static.

Parameters

Response — 200

200 The effective branding, with render-time defaults filled in.401 Missing or invalid API key.404 Project not found.

Set a project's brand mark and its motion

The pinned brand mark — the corner "bug" — on one project: image, corner, size, opacity, and a MOTION FORMULA. Before this endpoint the mark was reachable only from the settings panel and the creation wizard, so a film built through the API came out unbranded even for a channel that has a logo configured. Every field is optional and only what you send changes: branding shares `projects.settings` with captions, audio and theme, so the write is a merge. `formula` is what makes the mark live. `none` is a static stamp; `tick` squashes it on every downbeat of the project's own measured grid; `ghost` rests it low and lifts it on an authored scene cue. The motion compiles against the same bars the composition uses, so it lands with the music rather than near it. Amplitudes are capped and ticks carry a cooldown — a mark cannot be made to strobe. An unknown slug is refused rather than silently rendering static.

Parameters

Request body

Response — 200

200 Branding updated; the effective values are returned.400 Invalid body, or an unknown motion formula.401 Missing or invalid API key.404 Project not found.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Set the transition on the cut before a scene

Set — or clear — the transition on ONE scene boundary. A seam is named by its INCOMING scene, which is how the timeline stores it and how the editor addresses it. On a chapter's first scene the seam is the CHAPTER JOIN, which only a geometric transition (render_mode `geometric`) can cross (400 otherwise); the project's first scene has no seam (409). This is the per-seam control. `POST /projects`'s `transitions` list only cycles slugs across every boundary at plan time, so before this endpoint there was no way to say "this cut, ink, 700ms" — or to change a transition after generation. Slugs are validated against the same curated set GET /catalogs/transitions offers, so an unknown slug is refused rather than written and rendered as a silent cross-dissolve. Omitting `duration_ms` takes the transition's own default, which is usually right: a textural transition needs materially longer than a crossfade before it reads at all.

Parameters

Request body

Response — 200

200 Seam updated; the effective transition is returned.400 Invalid body, or an unknown transition slug.401 Missing or invalid API key.404 Scene not found, or not placed on its chapter timeline.409 The scene is first in its chapter, so there is no boundary before it.

Read the project's grooves

A project's GROOVES are synthesized loops, one per scene, that play on the PROJECT's musical clock (its tempo map): bar n is bar n in every scene, so neighbouring grooves stay in phase across a join and a seam sound (PUT /scenes/{sceneId}/transition) lands on it. Each scene plays its own pick, else the project default. Patterns carry no tempo or key — the project grid wins. `render=true` also renders each playing scene's slice and returns its file, its hits (`trains`, every hit per voice in scene-local seconds) and named `marks` — what visuals sync to. Repeat `scene_id` to render only some scenes.

Parameters

Response — 200

200 The grooves, the grid, and what every scene plays.401 Missing or invalid API key.404 Project not found.

Set the project's grooves

A project's GROOVES are synthesized loops, one per scene, that play on the PROJECT's musical clock (its tempo map): bar n is bar n in every scene, so neighbouring grooves stay in phase across a join and a seam sound (PUT /scenes/{sceneId}/transition) lands on it. Each scene plays its own pick, else the project default. Patterns carry no tempo or key — the project grid wins. One atomic update, applied in order: add_presets, upsert, remove, default_id, scenes, gain_db, enabled. Patterns are validated (voice, steps grammar, ranges) and refused with a message the author can act on.

Parameters

Request body

Response — 200

200 Updated; the new state is returned.400 Invalid body or pattern, an unknown groove id, or a scene not in the project.401 Missing or invalid API key.404 Project not found.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Read the project's tempo

The project's musical grid (settings.tempo): bpm, meter, key, where bar 1 falls, and tempo sections. It is what grid-bound motion, sound cues, grooves and music loops are timed against. Falls back to the grid the film was generated at (`stored: false`); null when there is neither.

Parameters

Response — 200

200 The tempo.401 Missing or invalid API key.404 Project not found.

Change the project's tempo

The project's musical grid (settings.tempo): bpm, meter, key, where bar 1 falls, and tempo sections. It is what grid-bound motion, sound cues, grooves and music loops are timed against. Does what the editor's tempo chip does: every grid-bound sound cue moves to the same bar:beat on the new grid, and a music LOOP is re-conformed (time-stretched) to it. A full-length track keeps its own tempo; returning to a loop's own tempo restores its original file. Idempotent. A FLAT edit: a project with tempo ramps (a conductor map) has them flattened into steps (`flattened_ramps: true`); edit ramps with PATCH /projects/{id}/conductor. Free.

Parameters

Request body

Response — 200

200 Saved; the stored tempo and what moved.400 Invalid tempo (out of range, unknown field, or nothing to change).401 Missing or invalid API key.404 Project not found.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Read the project's conductor (tempo map)

The project's musical grid as a conductor: tempo points with curved ramps, signature changes, key changes, markers and an arrangement lane, anchored in musical position (q = quarter-notes from bar 1, or bar + beat) so seconds are derived and an edit at bar 5 does not slide bar 9. PATCH /tempo (set_tempo) stays for flat edits and flattens ramps. Falls back to the v1 tempo migrated, then the grid the film was generated at, then 120 bpm 4/4. Includes `edit_version`.

Parameters

Response — 200

200 The conductor.401 Missing or invalid API key.404 Project not found.

Replace the project's whole conductor

The project's musical grid as a conductor: tempo points with curved ramps, signature changes, key changes, markers and an arrangement lane, anchored in musical position (q = quarter-notes from bar 1, or bar + beat) so seconds are derived and an edit at bar 5 does not slide bar 9. PATCH /tempo (set_tempo) stays for flat edits and flattens ramps. The body `conductor` is the document GET returns (`version` may be left out); it is validated and canonicalised. Same response, `dry_run` and `expected_version` as PATCH.

Parameters

Request body

Response — 200

200 Replaced (or previewed).400 Invalid conductor.401 Missing or invalid API key.404 Project not found.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Edit the project's conductor by id-addressed ops

The project's musical grid as a conductor: tempo points with curved ramps, signature changes, key changes, markers and an arrangement lane, anchored in musical position (q = quarter-notes from bar 1, or bar + beat) so seconds are derived and an edit at bar 5 does not slide bar 9. PATCH /tempo (set_tempo) stays for flat edits and flattens ramps. Ops apply in order, all or nothing; items are addressed by id, so concurrent edits to different items merge. `dry_run: true` writes nothing and returns the diff in seconds (bars that move, music-span scenes, sound cues). A real write stores `settings.conductor` and the derived `settings.tempo` together; a grid change retimes bound sound cues and re-conforms music loops like PATCH /tempo. Scene windows are NOT re-fitted. Send `expected_version` for a strict compare-and-set (stale = 409 `conflict`). Free.

Parameters

Request body

Response — 200

200 Applied (or, with dry_run, previewed): the conductor, what changed and the diff.400 Invalid op (the message names its index), or the result is invalid (bpm range, ramp too steep).401 Missing or invalid API key.404 Project not found.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Status of audio-follows-tempo for the project's music

Audio follows tempo (conductor P2). With the conductor's `warp.mode` "on" (`set_warp` op, default off) each non-looping music bed is time-stretched (Rubber Band R3, pitch kept) so the song's beats land on the tempo map. It is baked once on the worker's CPU lane and hosted under a content-addressed key; the cue then plays that file (`assetUrl` = the bake, `warp` = source file, offset and key), so the editor preview, the share page and the export play the same audio. Warned past +-20% stretch, left as the song past +-50%. Re-baked when the map or the track changes; a stale bake is never played. Exports wait for running bakes and refuse (`audio_pending`, `audio_failed`) rather than play stale or un-conformed audio. Free. This read never starts a bake.

Parameters

Response — 200

200 Per-bed state.401 Missing or invalid API key.404 Project not found.

Ask for the music bakes the tempo map needs

Audio follows tempo (conductor P2). With the conductor's `warp.mode` "on" (`set_warp` op, default off) each non-looping music bed is time-stretched (Rubber Band R3, pitch kept) so the song's beats land on the tempo map. It is baked once on the worker's CPU lane and hosted under a content-addressed key; the cue then plays that file (`assetUrl` = the bake, `warp` = source file, offset and key), so the editor preview, the share page and the export play the same audio. Warned past +-20% stretch, left as the song past +-50%. Re-baked when the map or the track changes; a stale bake is never played. Exports wait for running bakes and refuse (`audio_pending`, `audio_failed`) rather than play stale or un-conformed audio. Free. Idempotent: the same map and song are a cache hit; poll until `pending` is false.

Parameters

Response — 200

200 Per-bed state after the request.401 Missing or invalid API key.404 Project not found.

Add an element to a scene

Append one element — motion design, an image, or a text box — to an existing composition. SPENDS CREDITS: the new line goes through the scene-generation path, which compiles, persists, and dispatches a resolve job. Asynchronous; poll the scene. Contrast PATCH on the same path, which edits existing elements for free.

Parameters

Request body

Response — 202

202 Element accepted and generating.400 Invalid request body or parameters.401 Missing or invalid API key.402 Insufficient credits.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Edit elements in a scene

Element-level edits on a scene, expressed as patches against its scene source. This is the same vocabulary and the same applier the editor canvas uses for a drag, resize, retime, recolour or restyle, so an API caller and a person on the canvas produce identical results. Read the scene first to get current line numbers. Spends no credits — an edit is a source rewrite plus a transpile, not a generation. Scene ids are globally unique, so the flat path is unambiguous. The response carries `claimed_by` when another actor holds a live claim on the scene (the write is not blocked).

Parameters

Request body

Response — 200

200 Patches applied; scene recompiled and persisted.400 Invalid request body, or no patch matched the source.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.409 Stale write: a line in expect_lines no longer matches, expected_version is behind, or the row changed while the edit was being recompiled. Nothing was written.422 The patched script failed to compile.

Create a theme

Author a private theme owned by your account — a palette (colours keyed by role) and an optional type pairing. Reference the returned `slug` as `themeSlug` when creating a project. Only the safe design fields are settable here; image-generation routing and prompt directives are managed by the system.

Request body

Response — 201

201 The created theme.400 Invalid body.401 Missing or invalid API key.

Describe a scene's gen:html sub-compositions

Return the visual-unit map of every resolved gen:html sub-composition in a scene — the same "what's inside this composition" structure the editor canvas exposes on double-click, but read statically from the hosted blob (no browser). Each unit carries its id/label, whether it is a timed `.clip` layer, and its animation lanes (properties + times); engine fills also return the parsed window.__DATA__ (their editable surface) with confidence "partial". Read-only. Scene ids are globally unique, so the flat path is unambiguous.

Parameters

Response — 200

200 The scene's gen:html unit maps.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.

Edit a gen:html sub-composition's inner units

Apply deterministic, LLM-free edits to inner units of a resolved gen:html sub-composition: delete_unit removes the unit's element subtree; hide_unit hides it in place. The hosted blob is rewritten IMMUTABLY (a new copy is hosted and the scene's resolution swaps to it) — the previous URL is returned so the edit can be reverted. Unit keys come from GET …/genhtml.

Parameters

Request body

Response — 200

200 The edit result.400 Invalid body.404 Scene or composition not found.422 Edit could not be applied (e.g. unit not found in the blob).

Everything known about a beat, before you author it

Return the authoring envelope for each of a scene's composition elements — what the pipeline's own composition author is told about the beat it is writing. Read this BEFORE authoring or rewriting a composition: without it, an author is guessing at numbers the system already holds. Per element: the brief; the director's numbered beats resolved to real seconds (each beat quotes a phrase of the narration, joined here to the word timeline); the canvas and the element's own window on the scene clock; the scene-relative VO word timeline; the musical grid re-based to the element's zero; the theme's resolved colour and type roles, image style and actual ground; the camera itinerary that will move over the composition; measured anchors; the previous and next scene; and the cast, generated imagery and user library available for verbatim reuse. Timing, theme resolution, text-fit geometry and camera authority belong to the pipeline. Author against the values returned here rather than hard-coding equivalents. Read-only and free — no credits, no writes, no generation.

Parameters

Response — 200

200 The beat's authoring context.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found, not accessible, or it has no script yet.503 The authoring service is temporarily unreachable (e.g. a worker redeploy). Nothing was spent; retry.

The vocabulary a composition is authored in

One record per attribute, CSS variable, declared global and callable primitive in the composition authoring contract. Each says WHEN its value appears — authored, injected by the worker at resolve, computed by a kernel at mount, or driven per frame off the paused timeline — and what literal NOT to write in its place. `role=knob` returns the author-facing vocabulary alone, which is what an author needs. `role=machinery` returns the rest: worker-stamped kernel version markers, the `-done` receipts a kernel writes, and published values such as the measured anchor table. None of those are authored, and writing a receipt by hand suppresses the pass it names. The response carries its own coverage report, including what it does not cover. Free, read-only, and not scene-scoped.

Parameters

Response — 200

200 The contract records plus a coverage report.401 Missing or invalid API key.403 Plan does not include API access.503 The authoring service is temporarily unreachable. Retry.

Would the pipeline accept this composition?

Check a composition against the REAL gates before landing it. Free — no hosting, no writes, no credits. Runs the actual chain at its live configuration: the same normalisation every generated candidate receives, the hard structural gates (exactly one closed <template>, a composition id, a registered timeline, and the seek-law bans on <canvas>, requestAnimationFrame, appends to document.body and getElementsBy*), the configurable gate stack, and the vocabulary checks from GET /authoring-contract. A refusal is reported in the gate's own words, with per-stage results. The most common refusal is driving animation from requestAnimationFrame or a wall clock: the renderer seeks a paused timeline and screenshots, so it never runs a frame loop and such a composition renders blank in the video while looking correct in a browser. Reports whether the composition is CONFORMANT, never whether it is any good. To SEE it, pass `check: true`: the response gains `check` with the rendered findings and a `contact_sheet` image of the whole scene over time.

Request body

Response — 200

200 The verdict: per-stage results, gate flags and contract findings.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.503 The authoring service is temporarily unreachable. Retry.

What is on screen in this scene?

What is actually on screen at each requested time, as JSON — no screenshots. Free; cached by composition content. Per visible element (named by data-tc-anchor, data-wire-id, id, or tag.class plus its text): box on the composition canvas, fraction in frame, clipping by an overflow:hidden ancestor (and which), text overflow, glyph px when the frame is shown 360 px wide, contrast against the CSS paint underneath (null over an image), what covers it and which text it overlaps. Plus a sampled visibility timeline, fonts that failed to load, tc-wire conformance when a wire spec is present, and grouped one-line `findings`.

Parameters

Request body

Response — 200

200 The report: per-element frames, visibility, findings.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found.429 Rate limited.503 The verification service is temporarily unreachable or busy. Retry.

What would this composition show?

What is actually on screen at each requested time, as JSON — no screenshots. Free; cached by composition content. Per visible element (named by data-tc-anchor, data-wire-id, id, or tag.class plus its text): box on the composition canvas, fraction in frame, clipping by an overflow:hidden ancestor (and which), text overflow, glyph px when the frame is shown 360 px wide, contrast against the CSS paint underneath (null over an image), what covers it and which text it overlaps. Plus a sampled visibility timeline, fonts that failed to load, tc-wire conformance when a wire spec is present, and grouped one-line `findings`. For a draft you hold: times are on its own clock.

Request body

Response — 200

200 The report: per-element frames, visibility, findings.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.429 Rate limited.503 The verification service is temporarily unreachable or busy. Retry.

Render real frames of this scene

Real pixel frames, exactly as the final MP4 shows them: the same document, on the same GPU renderer, through the same capture pipeline. Free. Returns `frames` (one PNG URL per time); `determinism` — each check time taken cold vs after seeking elsewhere and back (seek-order), and before vs after the scripts run a second time (double-mount), pass/fail with PSNR, changed-pixel share and a diff image; `kernels` — what the kernels compiled and every moment they could not resolve; the checker's static `findings`; and a one-line `summary`.

Parameters

Request body

Response — 200

200 Frames, determinism verdict, kernel reports, findings.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found.429 Rate limited.503 The preview renderer is cold, busy or unreachable. Retry.

Render real frames of a draft composition

Real pixel frames, exactly as the final MP4 shows them: the same document, on the same GPU renderer, through the same capture pipeline. Free. Returns `frames` (one PNG URL per time); `determinism` — each check time taken cold vs after seeking elsewhere and back (seek-order), and before vs after the scripts run a second time (double-mount), pass/fail with PSNR, changed-pixel share and a diff image; `kernels` — what the kernels compiled and every moment they could not resolve; the checker's static `findings`; and a one-line `summary`. For a draft you hold: times are on its own clock unless scene_id is given.

Request body

Response — 200

200 Frames, determinism verdict, kernel reports, findings.400 Invalid request body.401 Missing or invalid API key.403 Plan does not include API access.429 Rate limited.503 The preview renderer is cold, busy or unreachable. Retry.

Land a composition you authored

Put a composition the caller authored onto a scene's element — the other end of GET /scenes/{sceneId}/authoring-context. It goes through the SAME path a generated composition takes: the real validation gate stack at its live configuration, then namespacing, per-instance CSS scoping, theme-variable injection, asset-slot expansion and hosting. Authored work is not a second-class route. Timing, theme resolution, text-fit geometry and camera authority belong to the pipeline: author against the values the authoring context returns rather than hard-coding equivalents. A refusal answers 422 carrying the gate's own verdict, so `dry_run: true` is free and worth doing first. Expect refusals for a requestAnimationFrame or wall-clock drive (the renderer seeks a paused timeline and never runs one), a <canvas> in the DOM path, an unclosed <template>, no registered timeline, or nodes appended to document.body. Refuses a scene that is mid-generation rather than racing its write-back (409), and refuses if the scene changed while the composition was in flight (409) — re-read and retry. Free unless the HTML declares generated assets; any cost is reported. Advisory claims: the response carries `claimed_by` when another actor holds a live claim on the scene (POST /scenes/{sceneId}/claim). The write is never blocked by a claim.

Parameters

Request body

Response — 200

200 The composition was landed, or validated on a dry run.400 Invalid request, or the scene has no script to mount onto.401 Missing or invalid API key.403 Plan does not include API access.404 Scene not found or not accessible.409 The scene is mid-generation, or it changed while the composition was in flight. Nothing was written.422 Refused by the pipeline gates. The response carries the verdict under `validation`.503 The authoring service is temporarily unreachable. Nothing was written; retry.

Say you are working on a scene (advisory claim)

Take, or renew, an ADVISORY time-limited claim on a scene: a lock the editor shows and other writers see as `claimed_by` on their scene writes. It never blocks anyone, and other holders do not stop yours (they come back in `held_by_others`). `ttl_seconds` defaults to 90 (5..900); POST again as the heartbeat. The holder is your declared session (X-Typecut-Session / the MCP connection), else your API key. 503 `unavailable` until the scene_claims migration is applied. MCP: claim_scene.

Parameters

Request body

Response — 200

200 Claimed (or renewed).400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.503 Scene claims are not enabled on this deployment yet.

Renew a claim you still hold

Extends a live claim of yours. Unlike POST it never creates one: 404 when it lapsed (claim again).

Parameters

Request body

Response — 200

200 Renewed.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.503 Scene claims are not enabled on this deployment yet.

Release your claim on a scene

Idempotent: `released: false` when you held nothing live. MCP: release_scene.

Parameters

Response — 200

200 Released (or nothing to release).400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

List a scene's harvested frames

The frames of the scene's current composition_version and duration (`frames`), the previous version's frames while under 24 h old (`fallback_frames`), `thumbnail_version` (below composition_version means the published picture is stale), and `missing_t_ms`: the times still worth capturing (2 cut anchors, 6-12 uniform frames, gap fill until no gap exceeds max(duration/8, 1.5 s)). Any member may read.

Parameters

Response — 200

200 The frames.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Store harvested still frames of a scene

Multipart. Part `meta` (JSON): `{ composition_version, duration_ms, source: "agent"|"editor"|"worker", frames: [{ t_ms, width, height }] }`; then one `frames` file per entry, in order (webp, jpeg or png, sniffed by magic bytes; the declared size must match the image). Needs the editor role on the scene's project. The frames must belong to the scene's CURRENT composition_version and duration (409 `stale_version` / `duration_mismatch` with the current values otherwise). At most 16 frames per call and 16 stored per scene version, each at most 400 KB and 160..960 px wide with t_ms inside the duration (413 over the size caps). A frame at an occupied slot (same t_ms and width, or within 150 ms) is a `duplicate` unless its source outranks the stored one (worker > agent > editor), which replaces it. Stored publicly under media/<account>/frames/<scene>/<version>/. On success the scene's published thumbnail_url and filmstrip_url move forward to this version (never back to an older one). About 200 calls per hour per account.

Parameters

Response — 200

200 Per-frame outcome and what the scene's published pointer did.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.409 Conflict with a concurrent change.413 The body or a frame is over the size cap.415 A frame is not a webp, jpeg or png image.429 Rate limit reached. Retry after the seconds in the error.

List the live scene claims in a project

Every live claim (people in the editor and agents), longest-held first. Lapsed claims are not returned. Empty until the scene_claims migration is applied.

Parameters

Response — 200

200 The live claims.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

What happened to a project, and who did it

One described record per change, newest first, from `project_events` (every writer: the editor, API keys and the connector, agent runs, the Director, the pipeline). Before recording started, or while the table is empty or absent, the legacy ledgers (project_edits, changesets, editor_revisions) answer instead: `source`, `recording_since` and `notes` say which. Project-level changes (tempo / conductor, music cues, mix, groove, theme, captions, branding, voice, aspect ratio, ...) are described key by key in `changes[]`. Every member can list; `changes[]` is reviewer and above. An API key acts as its account. MCP: get_project_history.

Parameters

Response — 200

200 A page of described events.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.500 Unexpected server error.

One history event in full

The described changes, the structured before -> after rows, the version range, the old values the ledger kept, and pointers to where the rest lives (the editor_revisions row with the previous composition or script; harvested stills before and after). Reviewer and above; a viewer gets 403 and keeps the list. Raw scene source never comes back.

Parameters

Response — 200

200 The event.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.500 Unexpected server error.

Who is working on a project right now

Live scene claims (people and agents, with expiry), everyone who wrote in the last `minutes` (from the history ledger, with the legacy fallback), and the agent runs on this project (status, last tool, scenes touched). Presence (who has the editor open) is a browser-only Realtime channel and is NOT available server-side: the response says so. MCP: get_project_activity.

Parameters

Response — 200

200 Who is on the project.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.500 Unexpected server error.

Set how the music sits under the voice

Ducking mode (`bed` | `off`), the duck dials, sidechain `ducks` from any source, the aux `room`, and film-editor MOMENTS hung off scene edges (swell, out, in, hit). Applied in the editor, the share link and the export alike. `expected_version` makes it a compare-and-set.

Parameters

Request body

Response — 200

200 The mix after the change, with `edit_version`.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Get a workspace's default audio mix profile

The default audio profile (how music ducks under voice, voice/music/sfx bus levels) that projects created in this workspace start with. `profile` is null when none is set. A project created with `mix_from_project_id` uses that basis instead.

Parameters

Response — 200

200 The profile or null.401 Missing or invalid API key.404 Not found, or not accessible with this key.500 Unexpected server error.

Set a workspace's default audio mix profile

Send `{ profile: { mix, voMasterVolume?, musicMasterVolume?, sfxMasterVolume? } }` to set it (stored clamped; `mix.moments` is dropped), `{ from_project_id }` to copy a project's current profile, or `{ profile: null }` to clear. Applies only to projects created afterwards; existing projects are never changed.

Parameters

Request body

Response — 200

200 The stored profile (or null).400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.500 Unexpected server error.

Set, replace or clear the project's music bed

A catalog `trackId`, a BYO `url`, a `sequence` of beds, or `generate` (commission one). Sending none of them CLEARS the bed. `expected_version` makes the write a compare-and-set (not used by `generate`, which only commissions a track).

Parameters

Request body

Response — 200

200 The bed now set (null when cleared or commissioned), with `edit_version`.400 Invalid request body or parameters.401 Missing or invalid API key.402 Insufficient credits.404 Not found, or not accessible with this key.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Set the project's narration voice

Assigns a voice from GET /projects/{id}/voice. Does not re-voice anything already generated. `expected_version` makes it a compare-and-set.

Parameters

Request body

Response — 200

200 The voice now set, with `edit_version`.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

Declare the shared modules a project (or chapter) runs on

Module refs "id@version" in load order; `chapter_id` sets one chapter's own list; `modules: null` clears. `expected_version` makes it a compare-and-set.

Parameters

Request body

Response — 200

200 The runtime now stored, with `edit_version`.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

The source a project is meant to match

The video analysis recorded as the project's reference, with its state (status, duration, shots, size). `reference: null` when none is set.

Parameters

Response — 200

200 The reference and its analysis.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.

Record the source a project is meant to match

Points the project at a video analysis (`analysis_id`, analyze_video first) and/or an audio analysis (`audio_analysis_id`, analyze_audio first), with an optional `alignment` of replica scenes to spans of the source ([{scene_id, ref_t0, ref_t1}] in seconds; absent = proportional). The body replaces the whole reference; both ids null clears it. `expected_version` makes it a compare-and-set. Pictures of it: GET /projects/{id}/reference/frames.

Parameters

Request body

Response — 200

200 The reference now stored, with `edit_version`.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.409 expected_version is stale: the project settings changed since you read them. Nothing was written; re-read and reapply.

A picture of the project's reference at any time, width and crop

Same as GET /video-analyses/{analysisId}/frames, resolved through the project's reference (404 when it has none). Times are on the SOURCE clock.

Parameters

Response — 200

200 The frames.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.

What the project's reference says in a window

The reference's shots (kind, framing, on-screen text, motion, palette, keyframe url), its transcript and any sound events inside a window, as rows. Times are seconds on the SOURCE clock: `from`/`to`, or `scene_id` for the span the reference alignment gives that replica scene. No window = the whole source (shots cap at 200, words at 4000). Free.

Parameters

Response — 200

200 The facts.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.

Find shots of the project's reference

Shots whose on-screen `text` contains a string, or of a given `kind` / `framing`; or, with `similar_to` (a shot index), the nearest shots by picture (`measure` dino = composition and content, clip = meaning; cosine distance, smaller is closer). Needs the shot embeddings (they are filled in the background). Free.

Parameters

Response — 200

200 The shots.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.

Compare a scene with the project's reference

Renders a few frames of the scene and takes the reference frames at the aligned times, then returns how far apart they look: a distance vector (DINO = composition and content, CLIP = meaning; cosine distance, smaller is closer), never one score, plus the worst frames with both pictures. The scene must be aligned to the reference. Free.

Parameters

Request body

Response — 200

200 The comparison.400 Invalid request body or parameters.401 Missing or invalid API key.404 Not found, or not accessible with this key.503

List members

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Returns the account's own user first (role owner, isAccountOwner true), then members.

Response — 200

200 Members.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.

Invite a member

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Same as POST /members/invites: creates an email invite (7 days; one open invite per email; role cannot be owner). Nobody becomes a member until the invitee accepts. Typecut sends no email; hand over `accept_url`.

Request body

Response — 201

201 Invite created.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.409 An open invite for this email already exists.

Change a member role

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Only an owner may grant, change or remove an owner. The account's own user cannot be changed (400).

Parameters

Request body

Response — 200

200 Role changed.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Remove a member

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Only an owner may remove an owner. The account's own user cannot be removed (400).

Parameters

204 Member removed.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

List open invites

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Open invites (not accepted, not revoked), expired ones flagged. Never includes tokens.

Response — 200

200 Invites.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.

Create an invite

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Creates an invite and returns the raw token and accept link ONCE. Typecut stores only a sha256 of the token and sends no email. The invitee must be signed in with the invited, verified email.

Request body

Response — 201

201 Invite created.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.409 An open invite for this email already exists.

Revoke an invite

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). The invite link stops working immediately.

Parameters

204 Invite revoked.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Re-issue an invite link

Account-level, hand-made API keys only: workspace-, project- and budget-scoped keys and connector tokens get 403. A key is never a member; it acts as the account (owner authority). Rotates the token of an open invite (the old link stops working) and restarts the 7-day expiry. Returns the new link once.

Parameters

Response — 200

200 New link.400 Invalid request body or parameters.401 Missing or invalid API key.403 Plan does not include API access, or the action is not permitted.404 Not found, or not accessible with this key.

Create a scene

Create a scene in a chapter. A prompt-only body makes a draft composition scene (generation pending); a `media_url` body makes a resolved "uploaded" scene with its background already set. Shares scene-crud-service with the Director chat.

Request body

Response — 201