CueFrame

Start an async Director compose job: it authors an ensemble of full composition candidates, verifies each, and saves the winner to the project. Body must set EXACTLY ONE source (mutually exclusive): `briefId` — author FROM a persisted Brief (the PLANNED path: create_brief first; every Brief field is honored or the compose is refused loudly naming the field); `fromComposition: true` — author fr

Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Call describe_composition_ops without type for the compact operation list, then with a type for its exact JSON Schema. For negotiated component execution, read get_composition with componentExecutionVersions=["3","4"] and includeDependencies="true", then send componentExecutionVersions

Dry-run a full Composition object against the SAME pure, DB-free authoring guards saveComposition enforces, WITHOUT persisting it (no project needed). Checks: wire shape (Zod), primitive membership (unknown_primitive / custom_missing_sourcecode), required-param shape (invalid_primitive_params), clip↔track family (clip_source_track_mismatch), and reframe coverage (reframe_coverage_gap). Always re

Queue an MP4 render of a project's composition. Returns { id (renderId), status, warnings? } — `warnings[]` carries non-fatal advisories (omitted when none). The render themes from the project's brand kit (bind one via create_project / update_project with brandKitId — or PATCH /projects/:id over REST; without one the output is unbranded). Then call wait_job(kind="render", id=renderId, projectI

Queue durable still-frame evidence for layout/copy judgment. Returns immediately with {jobId, kind:'preview_frame', status}; then call wait_job(kind="preview_frame", id=jobId) to receive every presigned frame as an image. The immutable snapshot records geometry, layers, warnings, and whether the target was persisted, inline, or session scratch. A still cannot prove motion — use preview_clip or p

Queue a typed preview artifact for ONE org-installed component — ASYNC: returns a jobId immediately; then wait_job(kind="preview", id=jobId). The preview and production compositor consume the same content-addressed component bundle and verified artifact contract. `body.componentId` selects the component; pass `body.params` to render it with props (the mount's `params`); declared manifest slots a

Render a scoped, cheap MOTION preview — ONLY body.fromSec→body.toSec of the composition (max 60s) at preview quality (capped resolution, lighter encode) through the real render pipeline. THE way to judge motion — a cut, a transition, a component's animation — at full fidelity BEFORE paying for a full render (a still cannot show motion; a full render costs the export). ASYNC: returns a rend

Queue the durable server-side judge — it snapshots the exact authored target, samples eval beats, captures frames asynchronously, and grades editorial/spatial/brand/caption. Then wait_job(kind="verify", id=jobId) for per-criterion scores, weighted composite, worst-first critique, and checkpointId. `body.composition` is optional (absent ⇒ ACTIVE). Fix the lowest criterion via apply_composition

Ask the Director for editing advice on the project's CURRENT composition — it NEVER writes your composition (you stay the decider). Async: returns a consultJobId; then wait_job(kind="consult", id=consultJobId, projectId=...) surfaces the advisory envelope (assessment / proposals / principles / plan). `body.mode`: 'advise' = the planner agent (fast, ~30s-2min) returns a `plan` (framing/cuts/capti

Answer the checkpoint packet wait_job reported as awaiting_input (its {checkpointId} — read the packet FIRST with get_checkpoint and relay the stills + money triple to your human). ONE `body.decision` per gate: 'approve' (proceed; comments allowed — they record as taste without gating), 'revise' (the director revises per your `body.comments` [{anchor: {beatId}|{timecodeMs}, verdict: 'approve'|

Persist the video's INTENT as a Brief — the Director's rich input contract (spec: the storyboard skill's output lands here). Fields: goal (required), audience, platform, format, durationSec, tone, cta, locale (output language — all on-screen copy + captions), hook, caption, beats[] (each with an editorial intent and optional MOMENT PINNING {mediaId, startSec, endSec} — honored to-the-frame o

Read a brief by id — the persisted intent plus its current quote (compose + estimated render).

List briefs. DEFAULT shows human-authored briefs only; kind:"clip" shows the machine-minted clip briefs (suggest_briefs output), kind:"all" shows everything. Each carries its quote.

Read a checkpoint packet — the durable approval unit a held compose pauses at (wait_job reports awaiting_input with {checkpointId, stage, version}). Carries the stage artifact, presigned storyboard stills (REVIEW THE EVIDENCE, not raw JSON), critic verdicts, the money triple {thisStepUsd, jobSpendSoFarUsd, estimatedJourneyTotalUsd} to relay to your human, and the recorded decision once resolved.

List checkpoint packets newest-first (filter with composeJobId for one run's v1→vN gate history, or projectId). The version stack with per-version status + decisions IS the review history — nothing is deleted.

Edit a brief (partial). REFUSED with 409 while an ACTIVE compose job references it — finish, resume, or abandon the job first (the Director never has its input edited mid-run). Edits apply to the NEXT compose.

Delete a brief. Compose jobs already run from it are unaffected (they snapshot).

Select one candidate from a finished compose/consult ensemble as the project's saved composition (whole-candidate replace). Body REQUIRES both fields: { candidateIndex, selectStrategy: "agent-authoritative" } — candidateIndex from wait_job(kind="consult") proposals (mode=amend) or the compose winner report; selectStrategy is required and API keys must use 'agent-authoritative' (editor-merge/edit

Create and store a custom component for the tenant: a native scene that arranges its declared images and videos as tiles in 3D space. Returns the ComponentResponse (id + metadata) you can then reference from a composition. No project arg — components are tenant-scoped. SOURCE CONTRACT (version 4; the server instructions' Component Contract has the full rules and an example): send the complete so

Use projection:'component-library' for the unified source-free library page, returned as complete JSON with exact scoped definition/preset/recipe cards and pagination. Choose origin:'builtin' for the maintained builtins or origin:'library' for the authenticated serving home; use libraryKind, category, q, limit and after to filter/page. Preserve each card identity.scope and identity.revision, its s

Resolve a selected builtin component-library card using its exact collection, id and revision. Returns the canonical pinned document and source snapshots for a preset or recipe, or the exact source for a definition. Preserve documentSha256 and all identities; a missing revision refuses without falling back to another version or scope. Resolve before apply_template; do not invent wrapper source or

Insert a resolved builtin component package into an existing project. Pass template as the selected builtin id and body with projectId, the resolved documentSha256, insert:{startTime,idPrefix}, parameter values and explicit media bindings. Read get_composition first and retain expectedRevision, commandId, componentExecutionVersions:[3,4] and expectedBrandIdentity as required by the contract. Inser

Read an exact component source as complete JSON. Supply sourceVersionId from the selected catalog card to read that immutable revision, retaining sourceSnapshot with its complete versioned definition, manifest and template beside its exact pin and schema metadata. For an explicitly selected builtin, also supply builtinCollection:'native'|'curated-definitions' and its exact sourceVersionId; without

Fetch bounded authoring context for a media item: dimensions/thumbnail, compact face roster, transcript counts/sample, temporal grids, and fact readiness. The full transcript body is deliberately elided so this read cannot overflow MCP; follow with get_transcript for exact paginated word timings.

Read exact source-time transcript words in bounded utterance pages. Word start/end values are seconds from the source media start. Pass limit (20 recommended), then pagination.nextCursor as after; the formatter omits the unbounded fullText duplicate.

Prepare the perception artifact an authored edit needs BEFORE sighted review. Pass body.kind="subjectTrack" for face/active-speaker reframing, or body.kind="matte" for a true zPlane:"behind-subject" graphic. Pass body.intent {startSec,endSec} using SOURCE time (the media trim, not timeline time); it is required for mattes and strongly recommended for subject tracks so the prepared fact exactly mat

Read prepared subject tracks and behind-subject mattes for one media item. For an exact readiness check, pass kind + startSec + endSec together using the same SOURCE window sent to prepare_media; exact.state is pending | ready | failed | available | unavailable. If subjectTrack was prepared without intent, omit all three filters and check the whole-source subjectTrack in facts instead. Wait for th

List the media in your CueFrame library. Filter a real library with kind (video|audio|image|gif|asset|source|stock), source (upload|generated|import-url|stock), or tag — so you find YOUR footage, not e2e debris. Returns media item IDs and metadata; use an ID with get_media_context, suggest_briefs, or as a composition source.

Create a new project — the unit you compose and render into. compose / apply_composition / create_render / the preview family all require a projectId; this mints one. Pass name (required) plus optionally a format (aspectRatio/fps/resolution) and brandKitId. brandKitId binds a brand kit to the PROJECT (pass the kitId from create_brand_kit): colors/fonts/motion theme every render of this project a

Create a NEW composition (a new video) inside a project — a project is a workspace that holds many videos. Returns { compositionId, format, etag }. Pass an optional name and format (aspectRatio/fps/resolution); format defaults to the project's compositionFormat. The first composition becomes the project's active default. To author it, seed with apply_composition then compose({ fromComposition: t

READ BACK a composition as JSON — the edit itself: tracks, clips, card HTML, reframe segments, captions, markers, format. This is what create_render encodes, so it is also what you hand to validate_composition (which needs a full inline composition body), what you diff after an edit, and what you archive/share so someone else can re-render the SAME video. Read-only and free. Authoring stays op-b

List every composition (video) in a project, with its format and which one is active. Use a returned compositionId with create_render(compositionId=...) to render a specific video, or apply_composition to edit it.

Delete a composition (and its version history) from a project. REFUSES the ACTIVE composition (409) — make another one active first, or delete the project. Use list_compositions to see which is active.

List your projects — re-orient in an existing workspace instead of minting duplicates (steady-state entry, A9). Each row carries the id every other tool needs.

Derive a reframed SIBLING composition for a different aspect ratio (the agent-native Auto-Reframe / Magic-Resize). Pass projectId + body { fromCompositionId, targetFormat: { aspectRatio, fps?, resolution? } }. CueFrame copies the source composition's authored intent and content-aware-reframes every clip for the new aspect (point/face/active-speaker focus), then saves a new independent composition

Import a media item into your library from a public URL — the agent-friendly ingest path (single call, no upload protocol). Pass url (https) + filename (+ optional contentType). Returns { id, status:"importing" }. Processing is async: call wait_job(kind="media", id=mediaItemId), or register a webhook (create_webhook on media.completed — status: complete|failed rides the payload). Use the retur

Generate one first-class Library media item from a prompt. Choose generator: text-to-video | text-to-image | image-to-video | text-to-music | text-to-speech | text-to-sfx | auto. Put supported presentation controls in body.style and first/last/image references in body.refs. Returns { id, status:"generating", estimateUsd? }; returns 402 if the estimate exceeds the per-call ceiling. Async — call w

Ingest a LOCAL file — bytes you hold, when there is no public URL to hand import_media (prefer import_media whenever the bytes already sit at an https URL). TWO steps: (1) this tool reserves a media item and returns { id, uploadUrl, expiresAt } — a short-lived PUT URL. PUT the raw file bytes to uploadUrl over HTTPS with your declared Content-Type (≤ ~5 GB per PUT). (2) call finalize_upload({

Finalize a direct upload once you have PUT the bytes to the uploadUrl from create_upload. Confirms the bytes landed and starts ingest: image/asset become ready immediately (status "complete"); audio/video enter processing (status "processing"). Returns { id, status, processingPhase }. 400 if no bytes were uploaded (PUT first) or the item is not yours. Then call wait_job(kind="media", id=mediaItemI

Search licensed stock media to compose with across video, photo, sound effects, and GIFs. Pass query for ONE search, or queries[] (≤10) to run them all in a SINGLE call — strongly prefer the batch when you know several things you need. A batch returns results[], one per query in order, each with its own candidates; a query that fails carries an error and never discards the others. Optional kin

The fonts the RENDERER can actually draw — read this BEFORE authoring type, not after a refusal. Per family: the exact family name authoring accepts, the weight RANGES a shipped file declares (a static face has min===max; a variable face gives its axis range), the caption default weights, and whether the bytes are bundled or an aliased metric-compatible stand-in. Anything listed here passes vali

Search web font families by name/style — returns family names to use in composition/component params. Pass query (+ optional perPage ≤50). Read-only + free; surfaces the Google Fonts catalog (family + category + variants + css2 stylesheet URL). IMPORTANT: this searches the GOOGLE catalog, not what the render can actually draw. Only the faces vendored into the render page are guaranteed to rast

Import a stock candidate (candidateId from search_resources) into a project as an ORG-OWNED media item — provider/externalId/license provenance preserved, bytes deduped across orgs. Pass projectId + candidateId. Returns { id, status:"importing"|"ready" }; processing is async — call wait_job(kind="media", id=mediaItemId), then use the returned id as a composition source. Gated on the resource_i

Run AI clip-suggestion analysis on a long-form media item — the CLIPPING path (find the best short-form moments). Returns { status, alreadyRunning? }; then wait_job(kind="suggestions", id=mediaItemId) — its terminal lists each suggestion WITH its briefId. When the media belongs to a PROJECT, each finalized suggestion is promoted to a kind-'clip' BRIEF (its window pinned as a beat) — list_bri

Register a webhook so long-running jobs notify you instead of blocking on wait_job — the right pattern for fan-out/async agents. Pass url + events — ONE terminal event per job kind with status INSIDE the payload (render.completed, compose.completed, media.completed, suggest.completed) plus checkpoint.ready (a held compose paused for review). DELIVERY: a POST { event, timestamp, projectId?, dat

Re-run ownership verification on a PENDING webhook — one whose endpoint did not echo the challenge at create time (check its verification.reason: token_not_echoed / non_2xx_<code> / unreachable / ssrf_blocked). After you fix the receiver to reply 2xx echoing data.token, call this to re-send the signed webhook.verify challenge and flip it active IN PLACE (id + secret preserved — no delete/recre

The org's legible taste in ONE read: brand kits, registered critics (the machine-checkable standard both the Director's gates and score_composition enforce), their reference media (presigned thumbnails), and the recent checkpoint-decision log. Read this BEFORE composing for an org you haven't worked with — it is the house style.

List registered critics: criticId, label, tier (rules|rubric|evaluator), phase, floor, referenceMediaIds. Rubric text / rules / evaluator URLs are write-only — never echoed. Manage with register_critic (upsert) / delete_critic.

Delete a registered critic by its criticId. It stops running in the Director gates and score_composition immediately.

Register a custom eval into the compose critic panel — the critic contract is { rubric (or rules/evaluator), referenceMediaIds?, floor }. Three tiers: rules (declarative constraints — keep-out regions, required elements, max overlays, brand colors), rubric (a text criterion scored by the judge as an extra column), or evaluator (your HTTPS webhook — CueFrame POSTs the composition+stills+facts

Update a project's mutable fields (e.g. name, format, brandKitId). Pass projectId + the changed fields as `body`. Setting brandKitId binds/changes the project brand kit so every render of this project themes from it. Returns the updated ProjectResponse.

Permanently delete a project you created (cleanup). Removes its composition and render history. Irreversible — only call on a project you own and no longer need.

Permanently delete a media item from your library (cleanup). Irreversible. Compositions referencing it will fail to render — only delete media no composition still needs.

Update an authored component's complete version-4 source/metadata IN PLACE (same id) — the correct verb for the author→preview→fix loop (preview_component returns the admission or runtime error; fix the template here and re-preview, instead of creating a new component each iteration). Pass componentId + the changed fields as `body`. Same source contract as create_component: {version:4, compo

Move clips that pin a retired TSX (version 3) component to its native (version 4) successor: the `successorSourceVersionId` that get_composition's `needsUpgrade` (or a `component_source_retired` refusal) names. Pass projectId and, in `body`, optional `clip_ids` (omit them to move every clip that has a successor) and `composition_id` (the active composition when omitted). Saved inputs are kept. The

Update a webhook subscription (its url or event list). Pass webhookId + changed fields as `body`. The signing secret is NOT rotated here.

Delete a webhook subscription (stop receiving its deliveries). Irreversible — the signing secret is invalidated.

Cancel an in-flight render (stop a runaway/queued job). Needs projectId + renderId (from create_render). No-op if already terminal.

Cancel an in-flight compose job (stop a runaway/mis-priced ensemble). Needs projectId + composeJobId (from compose). The director cancel is confirmed before the row flips; any linked charge is released. No-op-reject (422) if already terminal.

Cancel a running async job (verify / preview / brand-kit-extract) returned by an enqueue call — abort a mis-priced job instead of waiting out its TTL. For box-backed jobs the warm box is reaped best-effort; cancel never meters. No-op-reject (422) if already terminal.

Cancel an in-flight NLE export (fcpxml/premiere). Needs projectId + exportId (from the export enqueue). No-op-reject (422) if already terminal.

Re-render an existing render job's FROZEN composition snapshot — it inherits that job's exact composition/intent/priority and queues a fresh renderJob; it does NOT re-read the project's current composition. So it only helps a TRANSIENT failure (the failed render's `retryable:true` / `category:"transient"` — a flaky pipeline/infra fault): re-attempting the same snapshot may succeed. For a DETER

ORIENT FIRST — show THIS key's account before you spend a metered call: the org it is bound to, the current plan, a per-feature entitlements map, and per-call cost ceilings. READ `balance`, NOT `included`. CueFrame is credit-funded: rendering (entitlements.exports), generation (generate), preview stills (compose_capture), the judge (compose_verify) and the Director (compose) have NO separate per

List the plan catalog (tiers, intervals, product ids, prices) BEFORE a checkout, so create_checkout requests a real {plan, interval} instead of guessing an id. No args — reads the platform catalog.

The A2 usage ledger: every metered billing event newest-first with attribution — featureId, amount, the project/job that produced it, and the event's LIST price in USD (a plan allowance may zero it on the invoice). Answer "what did project X cost this period?" with a query instead of summing your own quotes. Filter by projectId, jobId, and/or a [from, to) epoch-ms window. Requires the billing:re

Top up the CURRENT org's credit wallet. Body { plan: "credit_pack_10"|"credit_pack_30"|"credit_pack_100" } → returns { url }: a hosted Stripe checkout page to open in a browser and confirm payment. There are no subscription tiers — a pack is a one-off top-up, and it is also the only thing that raises the generation (premium_credits) allowance. Always a URL — an existing saved card is NEVER c

Create or UPSERT a brand kit (re-POSTing the same kitId updates it in place — this is also the brand-kit UPDATE path). Sets fonts/colors/logo. This is brand step 0 of the workflow: author the kit, then bind it to a PROJECT so colors/fonts/motion theme the output AUTOMATICALLY — pass its kitId as brandKitId to create_project, or attach it to an existing project via update_project (PATCH /projec

Queue brand-token extraction from a website URL — ASYNC: returns a jobId immediately; then wait_job(kind="brand_kit_extract", id=jobId) for the tokens (colors/fonts/title/description, fetched + regex-parsed from the site's HTML/CSS — NOT a screenshot/vision pass). It does NOT persist — review the tokens, then call create_brand_kit to save a kit. A blocked (private/SSRF), non-2xx, non-HTML, o

Discover the exact CompositionOp vocabulary accepted by apply_composition. Omit type for a compact list of operation names and descriptions; pass type for only that operation's JSON Schema. Read this before authoring edits or captions.

Create a new project from a catalog or org template. The server prepares media and verified mattes before the project is ready. Pass the returned jobId to wait_job(kind="template").

Wait for a long-running job and return the resolved result — a bounded long-poll. Includes template preparation (kind="template", id=jobId), media import, render, compose, consult, suggestions and preview. If still running, call wait_job again with the same arguments; work continues server-side.

Render ONE authored card on its own and SEE it, before placing it in a composition. Pass the same `html` (+ optional `tokens`) you would put in a {kind:"card"} clip; you get the still back as an image. Use this while writing a card — it is the fast loop for catching type that overflows the frame, a headline that collides with a logo, or tokens that did not resolve. Sized to the format you name,