Saving and executing linked frames and clips

Workflow nodes marked studio-dependent-frames-v1, or carrying a keyframeId or sequenceBinding, require the Studio production generation API. The canvas can display their graph, but it cannot choose an accepted image from the latest visible result. Attempts return sequence_execution_required before that node starts a media job or reserves credits.

The same check applies to workflow execution, nested workflows, direct canvas media requests and the browser executor. Direct requests with workflowId and nodeId verify the stored node after checking access to its workflow; omitting a capability from the request does not remove that stored requirement.

Use the production’s manual generation actions for these nodes. They resolve the reviewed inputs and record the submitted pins. Ordinary image and video nodes retain their existing generation behavior.

Dependency-aware productions also require compatible saves. Generic workflow updates, delta updates and direct database writes cannot replace their graph or settings, even if the replacement removes the dependency marker. They return production_capability_required; the HTTP API reports this as a 409 conflict. Stored completion receipts remain protected after the last planned frame is removed. Ordinary workflows and metadata-only edits retain their existing path.

The production API validates semantic edits against the current document and saves with its loaded workflow version. A concurrent edit forces a fresh read and retry; a strict revision request is refused when that revision has moved. The compatible database functions are server-only and do not grant clients a raw JSON replacement path. The server integration must authorize the target and validate the document before calling them.

The save_editor_state operation accepts an editor graph and its expectedVersion. The server verifies that revision inside the save loop, including after a concurrent writer wins. A stale snapshot returns HTTP 409 even if the caller omitted the outer strict flag. This operation edits ordinary scene/settings state while preserving frame plans, reviews, bindings, linked jobs/results, protected trash, completion receipts and sharing. It rejects a draft whose indexed scenes cannot be reconstructed. Unknown stored settings remain preserved by the server.

These boundaries do not by themselves enable the full dependent-frame feature. Compatible editor controls, cloning/import handling and deployment capability checks must also be available.

Compatible semantic saves preserve existing 3D previsualization alongside linked frames: scene plans, revision history and blockout renders remain separate from final clip results. Copying a scene keeps completed blockouts but drops its pending 3D jobs. Recipe exports retain blockout authoring inputs without scene/media results.

Compatible saves also preserve scene descriptions, per-prompt cast overrides and reference captions. A role can remain description-only; assigning an actor later keeps the scene’s words and any prompt-specific overrides. Renaming a role moves those overrides with it. Reference captions travel with copied settings and are recorded when a clip is submitted, so later edits do not rewrite its history.

Reading and reviewing frames

GET /v1/studio/productions/capabilities reports supported plan versions and per-operation support for reading, editing, generating and accepting keyframes, and generating linked clips. Source-video frame references have a separate flag. The response depends on the installed host’s compatible writer, immutable job metadata and retained-image support. It performs no capture or generation. Automatic acceptance and unattended generation are not supported.

GET /v1/studio/productions/:id includes the same capabilities beside its production object. Dependency productions expose requiredCapabilities, keyframes, sequences, and each linked shot’s sequenceBinding. Each frame has separate preview and accepted result keys/URLs, its current plan revision, result count and pending markers. The final frame remains visible even when it has no outgoing clip. pending.keyframes counts in-flight frame jobs. Shots also expose pending still/clip jobs before their first result exists.

A full owner read includes authored plans, recorded review decisions, image history and provenance. A summary omits image history. Other readers’ frame projections omit plans, private source references, review details, owner identities and pending frame jobs. Recorded acceptance is historical state; generation still verifies current revisions and retained inputs before use.

The SDK exposes these routes through client.studio. Generation and review are separate calls: generateKeyframe submits the planned frame, reconcile records finished jobs, and acceptKeyframe applies an explicit review. Description-only cast references do not require a generated portrait. Adding a portrait later does not change an existing description reference into image conditioning.