## Builder guide {#build}

A Bitebox story is one graph of nodes and wires. The Canvas and your assistant edit the same graph, so anything the assistant builds you can open, change and play in the Canvas.

### A good order of work {#build-steps}

1. `workspace_context` to learn the grant, the node types and the publish format.
1. `project_list`, or `project_create { "title": "<title>" }`. A new project starts with a blank file. `file_create { "projectId": "<projectId>", "path": "Episode 2.json" }` adds another blank file; pass its `path` to the document tools.
1. `document_get` for the head revision and the nodes.
1. Build in `document_apply` batches, passing each new `revisionId` on.
1. To use your own clip as a scene, import it with `media_import_url`, then call `scene_add` with the `src` it answers. Pass `"start": true` for the opening clip. Do not add an **Import** node for this: an Import node is the Canvas upload slot. It does not play and cannot be the start. Leave out `x` and `y`, and each new scene goes one column right of the scene it follows (`from`), or into the next free column. `choice_add` puts its card one column right of its clip. No new card covers another.
1. `document_get` with a `nodeId` to read a node's real input and output ids before wiring it.
1. Mark the first playable node with `document_set_start`, and the final node with `document_set_end` if the story needs one.
1. `document_validate` for problems (errors stop play, warnings do not). It counts wires and references; pass `nodeId` to list the ones on one node, or `include` to list them all. Then `document_arrange` to tidy the layout. Arrange leaves room for each card's real height, and a 9:16 clip makes a tall card. Collapse workflow (`document_collapse_workflow`) hides one or more nodes on the canvas. Playback and generation stay the same.
1. `preview_url` or `playthrough_simulate` to play it.
1. To check a story that keeps score, such as a counter for wrong answers, send `playthrough_simulate` a `moves` list: the picks one viewer makes, in order. Each move is `end` (the clip plays to its end), `choose` with a `routeId`, or `claim` with a `triggerId` and an `optionId` (a choice on an overlay). The answer's `playthrough` lists each scene shown, where play stopped and the viewer state it ends in, for example `"penalty.count": 2`. A move the scene on screen does not offer is refused with `move-not-offered`, and the refusal lists the moves that scene offers. Moves need the `simulate-moves` flag; without it, a call with moves is refused with `feature-disabled`.
1. `watch_through_start` to play every path on the preview in a real browser on the server. It takes minutes; read the report with `watch_through_get`, about once a minute, since each call also moves the watch-through on. Each path says whether it reached its ending, which choices showed and when, and any error. It drives clips joined by plays-on routes and Choice Overlay choices; any other path says "not driven" and why. If your assistant subscribed to `watch_through.completed` ([events](#events)), it gets `pass` or `fail` when the watch-through ends. Then it reads the report. A watch-through that does not start within 30 minutes ends, and the message says `fail`. Then publish.

### Hear when a job finishes {#events}

An assistant can ask Bitebox to tell it when a job finishes, so it does not have to keep checking. This uses the MCP Events extension, by webhook only: Bitebox sends a signed message to a web address your assistant gives it.

1. `events/list` names the events: `generate.completed`, `generate.failed`, `watch_through.completed` and `publish.status.changed`.
1. `events/subscribe` with the event `name`, `arguments` with the `projectId` (and, if you want only one job, its `runId`, `jobId` or `pendingId`), and `delivery` with `mode: "webhook"`, an `https` `url` and a `secret`. Your assistant makes the secret: `whsec_` and the base64 of 24 to 64 random bytes. Bitebox never makes one and never shows it again.
1. Before the subscription starts, Bitebox sends `{"type": "verification", "challenge": "<text>"}` to the address. Answer `200` with `{"challenge": "<the same text>"}`.
1. Each event arrives as a signed POST with the Standard Webhooks headers `webhook-id`, `webhook-timestamp` and `webhook-signature`, and `X-MCP-Subscription-Id`. Check the signature on the raw body before you read it. `webhook-id` is the event's `eventId`. Answer `2xx` once you have stored it.
1. Call `events/subscribe` again with the same values before `refreshBefore` to keep it. `truncated: true` means some events were lost; read the job with `generate_status`, `watch_through_get` or `publish_status`. Those reads still work without a subscription.
1. `events/unsubscribe` with the same `name`, `arguments` and `delivery.url` stops it.

`publish.status.changed` arrives when a publish request is published, canceled or expires, usually within two minutes. It carries the `projectId`, the `pendingId` and the `status`. A published request also carries `url`, the public page link that `publish_status` shows, and `publicationId`. A request that is replaced by a newer ask arrives as `canceled`. Nothing arrives while the request is still waiting for the creator.

`generate.completed` arrives when a run's file is on its node or in the project's media, even if your assistant never calls `generate_status` again. It carries the `projectId`, the `runId` and `status: "completed"`. A result on a node also carries the `nodeId` and the `revisionId` that holds it. A file on no node carries its id in `mediaIds`, the same id `media_list` shows. `generate.failed` arrives when a run fails or is canceled. A run on a node that fails while nobody checks it is the one exception: it arrives only after `generate_status` takes the run's running mark off the node. Each run sends one event.

A subscription needs the same access as its read. A project outside your agent token answers "Not found.", the same as a project that does not exist. If Bitebox cannot reach your address, it tries again for about 15 minutes, then sends `{"type": "gap"}` before the next event. When the agent token is revoked, Bitebox sends `{"type": "terminated"}` and stops.

### Tell your media apart {#media-names}

`media_list` answers a `name` for each file: the name it was uploaded with, the file name in its import URL, or the generate run id that made it. A file with no name answers null, for example one stored before names existed. An assistant can name or rename a file with `media_complete`. The MCP does not describe what a clip shows. An assistant can read frames from the file's `src`, which is free, or run a `media_review` audit, which costs credits.

### Watch an agent work {#watch}

Keep the project open in the Canvas. Each change appears as the assistant makes it, and a line at the top of the Canvas counts the changes. The count goes up for the whole task. The line changes to "made" after 30 seconds with no change.

**Revert changes** undoes the whole task in one step, generated results included. Before it runs, a confirm box lists each node the task added or edited. The revert is a new save, so the task stays in Earlier versions. A task is every change the assistant makes with no gap over 5 minutes, and a generate that is still running keeps the task open. A new task starts if you edit the File yourself, run a model yourself, or another assistant writes to it, so Revert goes back only as far as the last of those. To go back further, use Earlier versions. An assistant can also set `agentRun` on `document_apply` to group its changes itself.

Revert does not undo credits or stored files:

- A result already on a node comes off the node. The run stays charged. Earlier versions can bring the result back, and `generate_status` with the run's id still answers its `src`.
- A result still on its way when you revert does not land on the node. The run finishes and stays charged. When the run finishes, the file joins the project's media, so `media_list` shows it even if your assistant never checks the run again. `generate_status` answers `node.reverted: true` with the file's `src`. A text run answers `reverted: true` with its text.

### Compare and name versions {#versions}

`document_revision_get` reads one earlier version, and `document_diff` lists the nodes, properties and wires that changed between two versions.

`document_checkpoint_set` names a version, as Earlier versions does in the editor. It adds and removes no version. A name or note already on a version can be yours, so your assistant cannot change or clear it. It asks you to do that in Earlier versions.

### Copy nodes from another File {#paste}

`document_paste_nodes` copies nodes into a File, as Copy and Paste do in the editor. The source can be the same File, another File, or another project your grant covers. The copies get new ids and keep the wires between them. Wires to nodes you did not copy are cleared. The source does not change.

Some nodes cannot be copied yet: a node with tags, and a Choice Overlay. The tool refuses them and writes nothing. Copy them in the editor, or build them with `document_apply`.

### Replace a whole File {#replace}

`document_replace` swaps a File's whole document, as Import JSON and Apply JSON do in the editor. Prefer `document_apply` for an edit. Pass the head from `document_get` as `expectedRevisionId`.

- It adds a new version. The old version stays, and `document_restore` brings it back.
- A stale head returns a conflict and writes nothing. It never merges.
- It refuses what `document_apply` refuses: a loop that the story cannot play, a new wire between nodes that can't connect, and a node type that is switched off for you. It also refuses to remove a series bible.
- A refused wire is named in the answer. A wire that was already marked invalid in the File can stay, so you can still edit that File.
- Fields the catalog does not know stay in the File.

### Restore an earlier version {#restore}

Use `document_revisions` to find an earlier revision. Send it to `document_restore` with the current head as `expectedRevisionId`.
The restore creates a new revision and keeps the old history. A stale head returns a conflict.
Pass the same `idempotencyKey` when retrying after a lost response.

Keep the Canvas open during the restore. It shows the restored version without a reload.
Open Projects → Earlier versions to inspect the restore's connection label, time, revision and run.
These facts remain after reload. The run banner on the Canvas does not remain after you reopen the project, so read the run in Earlier versions.
If the Canvas misses the live update, it catches up on its next check of the latest revision and still opens the run banner. A run that ended before that check shows what it made instead of showing the agent as still editing. Your latest revision selection stays selected when history refreshes.
Older revisions without recorded attribution keep their original unknown identity.

### Wiring nodes {#wiring}

Two nodes join when you connect an output of one to an input of the other. Read both nodes' endpoint ids with `document_get`; never guess an id from a label. A wire that closes a loop in the story is refused: going back to an earlier scene is a choice at play time, not a wire. Choices and overlay options are lists on a node: add the item first, then read the node again for its new port.

A Video's branches are a list too. `node_configure` with `add-branch` adds one, and `remove-branch` with `itemId` (the exit id from `document_get`) removes one. A Branch with no trigger wired is an error in `document_validate`, so remove a Branch you do not use. `remove-branch` disconnects the Branch's own wires first; a Target Overlay or Choice Overlay it owned stays on the Canvas without an owner, so wire it to another exit or delete it. The other branches keep their ids and wires. The Video's Storyline exit stays: `remove-branch` refuses to remove the only one.

A clip's Storyline output (`exit:exit.<id>.autoplay`) holds one destination: a new wire from it replaces the old one. To give a clip its next scene and several overlays, keep the next scene on the Storyline output and run `node_configure` `add-branch` once per overlay. Connect each new `exit:<id>` output to one overlay's `owner` input. The player shows every overlay on the clip. A Storyline output connected to a `pulse-in` input is refused, because that input takes only a Pulse. A story saved before 2026-11-06 may still hold that wire as `next` with `nextEndpoint: "pulse-in"`; it stops the story there, so disconnect it or connect the Storyline to a `story-in` input.

An `owner` input holds one owner, and a new owner replaces the old one. A wire that cannot own the node is refused and leaves the owner in place. That includes a File output, and a Storyline from a Set, a Conditional or another node that is not a clip. A Timestamp or Choice Overlay takes only a clip's Branch, so run `node_configure` `add-branch` on the clip and connect the new `exit:<id>` output instead. Moving a valid wire with `document_repair_reference` follows the same rule. A move that stays invalid leaves the working wires on that input, and a move never clears the other wires on its own output. In a project saved at spec 0.3 or 0.4, a new owner also removes the old owner's Branch, because those files cannot hold an empty one.

A connect whose output type the input does not take is refused, and nothing is saved. A move with `document_repair_reference` onto such an input is refused too, and the wire stays where it was. The refusal names the type the output gives and the types the input takes, so connect a matching output or pick another input. A connect the types allow but the nodes do not is refused the same way, with "These nodes can't connect. No wire was saved." In the editor, the same wire stays on the Canvas, marked invalid, so the author can see it. Any other connect answer names the wire the document saves. When the answer says the wire is invalid, `document_get` shows that same wire, on the input you named, marked invalid.

### Clean up text between nodes {#transform-text}

Put a **Transform Text** node between a text source (Prompt, Text or Generate Text) and the input that reads it. Set `operation` with `document_apply` (`patch-node-content`) and the fields that operation uses:

| `operation` | Fields |
| --- | --- |
| `case` | `to`: `upper`, `lower`, `sentence` or `title` |
| `trim` | none: removes spaces at the ends and makes each run of spaces one space |
| `shorten` | `max`, `unit` (`characters` or `words`), `ellipsis` (true or false). It never cuts inside a word. |
| `replace` | `find`, `replaceWith`, `usePattern` (read `find` as a pattern; `$1` inserts group 1), `ignoreCase` |
| `extract` | `pattern` and `group` (0 is the whole match), or leave `pattern` empty and set `jsonPath`, such as `answer.title` |
| `slice` | `start` and `end` character positions |

The result is ready as soon as you save; there is no Run and no charge. Patterns use RE2 syntax, so look-around and back-references are refused. A pattern holds at most 200 characters: a longer one is refused and the message names the limit. The node reads at most 20,000 characters of input.

Transform Text does not read an Adjudicator's outputs (its options, Labels or Prompts) yet, directly or through a Router: that wire is refused with `transform-text-adjudicator-source`. Wire the Adjudicator to the generate tile or Parallel Choices directly.

### Build one text from pieces {#combine-text}

A **Combine Text** node fills a template from up to four text sources wired to its inputs A to D. Set `template` with `document_apply` (`patch-node-content`): `{a}` to `{d}` insert the inputs, and a doubled brace writes one brace (two opening braces give `{`, two closing braces give `}`). The default is `{a} {b}`. With `separatorWhenEmpty` set to `collapse` (the default), an input with no words is dropped with the comma or space next to it, so `{a}, {b}` with nothing on B gives only A. Set it to `keep` to write the template as it is. A template holds at most 4,000 characters; a longer one is refused. Wire the output into a generate tile's prompt, Generate Text or another text node. There is no Run and no charge. Combine Text does not read an Adjudicator's outputs yet, directly or through a Router: that wire is refused with `combine-text-adjudicator-source`.

### Generate from frames {#generate-frames}

Wire an image to **First frame** to animate that image. Wan 2.5 Fast, Happy Horse and legacy Video Gen accept one first frame. Their **Last frame** input is unsupported. A connected last frame stops the run before a quote or credit hold, including connections saved in older documents.

Omni 1.1 Flash and Kling 3 accept a first frame and an optional last frame. A last frame needs a first frame. Gen 4.5 accepts one first frame; a connected last frame stops the run before a quote or credit hold. Kling 3 also takes its output shape from the first frame, so its Aspect ratio applies only to prompt-only runs. A first frame does not change the price. For Wan 2.5 Fast and Happy Horse, the first frame sets the output shape. The inspector hides Aspect ratio while that frame is connected. Older saved aspect settings stay in the document and apply only to prompt-only runs.

Wan prompts allow 1,500 characters; Happy Horse allows 2,500. Overlong prompts stop the run without changing saved text.

| First-frame tile | Image limits |
| --- | --- |
| Wan 2.5 Fast | Each side is 240–8,000px; at most 25 MiB. |
| Happy Horse | Each side is at least 300px; aspect is 1:2.5 to 2.5:1; at most 20 MB. |
| Legacy Video Gen | Exactly 768x512px (3:2 landscape). |

The server reads bounded media headers to check these limits. If it cannot measure an image, it refuses the run without a credit hold. Upload a JPEG, PNG or WebP frame.

Legacy Video Gen makes a 768x512 (3:2 landscape) video from a first frame. It has no 9:16 or other aspect option. A first frame of any other size, including a 9:16 still, stops the run before a quote or credit hold. The server never crops, resizes or stretches the image, so wire an image that is already 768x512. Saved Video Gen nodes keep their wires, and prompt-only runs do not change.

### Generate Text {#generate-text}

Generate Text writes words from a Prompt, an optional System Prompt, and up to four images or four videos. Set `model` to one of these ids. Each model has its own flat price per run.

| Model | `model` id | Takes video |
| --- | --- | --- |
| Gemini 2.5 Flash | `google/gemini-2.5-flash` | Yes |
| Gemini 3.8 Flash | `google/gemini-3.8-flash` | Yes |
| Claude Sonnet 5 | `anthropic/claude-sonnet-5` | No |
| Claude Opus 5.5 | `anthropic/claude-opus-5.5` | No |
| GPT-6 Sol | `openai/gpt-6-sol` | No |
| Seed 2.1 Turbo | `bytedance-seed/seed-2-1-turbo` | No |

- `maxTokens` is **Output length**: the longest answer the model may write, from 256 to 8,192 tokens. The default is 2,048. The server moves a value outside that range to the nearest limit. The price stays the same.
- `reasoning` is on or off.
- A video on a model that can't take video stops the run before a credit hold. The message names the model.

Example: set GPT-6 Sol, Reasoning on and a 4,096-token answer on a placed Generate Text node, then run it. The run reads the node's settings and its wired Prompt.

```json
{ "tool": "document_apply", "arguments": { "projectId": "<project>", "commands": [
  { "type": "patch-node-content", "patch": { "nodeId": "gen.text", "expectedDefinitionId": "generate-text", "edits": [
    { "operation": "set", "path": "/props/model", "value": "openai/gpt-6-sol" },
    { "operation": "set", "path": "/props/reasoning", "value": true },
    { "operation": "set", "path": "/props/maxTokens", "value": 4096 }
  ] } }
] } }
{ "tool": "generate_run", "arguments": { "projectId": "<project>", "runs": [{ "nodeId": "gen.text" }] } }
```

### Put a sound on a clip {#audio-nodes}
**Add Audio** puts up to two sounds on a clip; **Extract Audio** gives a clip's sound as its own file. Wire the clip into **Clip** (`input`) and the sounds into **Sound** (`sound`) and **Sound 2** (`sound-2`). On Add Audio set `mode` (`replace` or `mix`), `mixLevelDb` (−60 to 6, the clip's own sound in `mix`) and `offsetMs` (0 to 60 000, when the wired sounds start) with `patch-node-content`. The result is as long as the clip.
Bake either node with `node_run`, then poll `node_run_status` with the `runId` until `done`. An unwired Clip answers `node-input-missing` naming Clip. Extract Audio on a clip with no sound track ends the run `failed` with `code: "no-audio-stream"`. Add Audio with no sound wired is an identity: the clip passes through and nothing is written.
### Media addresses {#media-rule}

A video or image source must be a full `https://` address or a path from the site root that the player can load. A path relative to the story file plays a black frame. Upload or import media through the media tools so it is hosted.

### Make it for phones (9:16) {#format}

- Bitebox plays portrait 9:16. Set generate tiles to 9:16 unless you want another shape; 16:9 shows small on a phone.
- Keep the bottom quarter of every frame clear of faces and key action. Choice buttons sit there.
- Group characters in the centre, and put sign or screen text in the middle third.

### Prompting tips {#prompting}

- Keep readable words out of generated pictures where you can. Models garble text.
- For dialogue, name one speaker and one quoted line, ask for it in the first two seconds, and say who keeps their mouth closed.
- Describe only what is there. Naming something to exclude it (“no badge”) tends to add it.
- The reference image sets the composition. Position people and props in the still, not in the video prompt.
- Each model has its own rules. `generate_models` returns them as `promptingRules`; have your assistant read them before writing a prompt.
- With a first frame, Seedance 2.5 follows that image's shape, including saved Seedance 2.5 Image nodes. Omit `aspect_ratio` or use `"auto"` in requests. A fixed aspect is refused before any quote or spend.
- H3, H3 Max, and H3 Max Turbo also follow the input image's shape. Their aspect setting applies to text-only runs.
- Stable Audio 2.5 offers 4, 6, or 8 quality steps. Canvas resolves old unsupported selections to a supported default. Direct requests refuse them before spending.
- Flux 3 keeps Auto duration and sends explicit seconds as numbers. MiniMax Music 3 needs lyrics, or `[instrumental]` on its own line.
- ElevenLabs Speech (`elevenlabs-speech`) speaks a wired Prompt. Voice model is ElevenLabs v4, HeyGen Voice Turbo, or HeyGen Voice standard. Keep the same Voice for a character. Changing Voice model does not rewrite a saved voice.
- Reference clips must fit the model's length limit. MiniMax H3 Reference takes 2 to 15 seconds a clip and 15 seconds in total. Seedance 2.0 Reference takes 2 to 15 seconds in total. Seedance 2.5 Reference takes 1.8 to 30.2 seconds a clip and 30.2 seconds in total. Wan 3 takes 15 seconds or less in total. A clip outside the limit is refused before any quote, even by a fraction of a second. See [reference clip length](/docs/mcp/troubleshooting#clip-length).
- Auto Subtitle and Styled Subtitles read the video's speech. They do not use a prompt.
- For a clip that passes through set stills, use Flux 3 Max Keyframes (`flux-3-max-keyframes`). Pass up to 9 stills in story order as `imageUrls` with `referenceMedia` `image`. The first lands on the first frame, the last on the final frame, and the rest are spaced evenly between. For a single start frame (and an optional end frame), use Flux 3 Max (`flux-3-max`) with `imageUrl` and `endImageUrl`; an end frame alone is refused.
- To redo a clip's sound (cut unprompted music, keep dialogue, add synced SFX), use Mirelo SFX 2.0 (`mirelo-sfx-2-0`): wire the Video, optionally a Prompt, then run. Duration follows the clip (the baked edit file when one is wired), up to 10 minutes. A clip shorter than 1 second is refused before any quote. The baked mix replaces the clip's original track. The player shows the wired clip's picture, muted, while the mix plays. If the mix cannot play, the clip plays with its own audio. The mix is tied to the clip file sent at Run. A later rewire plays that new clip's own audio. Prompt text is experimental guidance Mirelo may not always follow. For a sound effect from text only, use Mirelo SFX (`mirelo-sfx-2-0-text`). That tile mixes as a bed and does not mute a clip. Duration there is up to 10 minutes.

### Connect video frames {#video-frames}

Wan 3 and Flux 3 can animate a first frame or connect first and last frames.
Connect a first frame before you connect a last frame.
For Flux 3 with both frames, choose a duration from 5 to 20 seconds. Auto is refused before charging.
Grok Imagine accepts a first frame. A last-frame wire is refused before charging, including wires saved in existing stories.

### Keep a character or scene with Wan 3 {#wan-3-references}

Wan 3 also takes up to 9 references: stills of a character or a scene, or video clips.
Pass them as `imageUrls` with `referenceMedia` `image` or `video`.
In the prompt, name them by medium and order, for example "the woman in Image 1 walks past Video 1".
References do not combine with a first or last frame. A run with both is refused before charging.
Clips total 15 seconds or less, and the price adds each clip's length to the output length.
Wan 3 does not take sound references. A sound reference is refused before charging.
On a reference run, Expand prompt and Think first start off.
### Edit or continue a clip with Flux 3 {#flux-3-clip}

Wire a clip into Flux 3's **Video** input to change it or to carry it on. The **Clip** setting picks the job:

- **Edit** re-renders the clip from your prompt. Say what to change; the rest stays as it was. The result keeps the clip's length, so the price follows the clip: $0.03 per second of clip. Edit has no other settings.
- **Continue** makes new footage that starts where the clip ends. Describe what happens next. Duration, aspect ratio, quality and audio apply. The price is the new footage's length at $0.41 per second (720p) or $0.53 (1080p). Duration starts at 5 seconds; Auto is priced at the 20-second maximum.

The clip must be under 15 seconds; Edit also needs at least 0.7 seconds. A clip outside that is refused before any quote, and the message names the clip, Flux 3 and the limit. Draft does not work with a wired clip, and a clip with a first or last frame is refused. Over MCP, set `/props/generate/input/clip_mode` to `"edit"` or `"continue"`; with no value, the run edits.

### Draft, then Finish {#draft-finish}

Seedance 2.5, Seedance 2.5 Reference and Flux 3 have a **Draft** setting. A draft take runs the prompt at preview quality for less, so you can check the motion before you pay for the full render. The card and the receipt say Draft. When you like a draft, **Finish** re-renders that same take at full quality (1080p). Finish shows its price first, and the finished clip becomes the node's result. The draft stays in the take history.

Your assistant does the same with `generate_finish`:

1. Run the draft: `generate_run { "projectId": "<projectId>", "runs": [{ "nodeId": "<node>" }] }` with the node's `/props/generate/input/draft` set to `true`. Record the `runId` and the receipt's cost from `generate_status`; the receipt carries `draft: true`.
1. Quote the Finish: `generate_finish { "projectId": "<projectId>", "nodeId": "<node>", "quoteOnly": true }`. The price is the tile's full-quality row at 1080p for the draft's own length. A draft made with a video reference also bills that video: 0.6 × (input + output seconds).
1. Finish it: the same call without `quoteOnly`. Poll the new `runId` with `generate_status` and record its cost.

A Finish runs the draft's own length; a different duration is refused. A run that is not a finished draft take on that tile is refused with `not-a-draft-take`, and nothing is quoted or spent. `node_run` does not finish drafts.

A draft on Seedance 2.5 or Seedance 2.5 Reference can be finished for 14 days. After that, Finish is refused with `draft-expired` and nothing is spent.

### Keep a character or edit a clip with Happy Horse {#happy-horse-references}

Happy Horse also takes up to 9 reference stills of a character or a thing.
Pass them as `imageUrls` with `referenceMedia` `image`.
In the prompt, name them in order as character1, character2.

To edit a clip, wire it to **Video** (`videoUrl`) and say the change in the prompt.
You can add up to 5 reference stills to an edit. Name them as @Image1, @Image2.
The edit keeps the clip's length and shape, so it has no duration or aspect setting.
**Sound** set to Auto makes new sound; Keep original keeps the clip's own sound.
The clip must be 3 to 15 seconds. A clip outside that is refused before charging.
The price counts each second of the clip twice, because the provider bills the clip you send and the clip you get back.

A first frame does not combine with references or a clip. Video and sound references are refused. Both are refused before charging.

### Make or edit a clip with Kling 4 {#kling-4}

Kling 4 makes clips of 3 to 30 seconds at 720p or 1080p. It picks how to run from what you wire:

- A prompt alone makes a new clip.
- A **First frame**, with or without a **Last frame**, animates between them. The first frame sets the shape, so Aspect ratio is hidden.
- A last frame alone, or up to 8 reference stills, makes a clip that keeps those subjects. Pass stills as `imageUrls` with `referenceMedia` `image`, and name them in the prompt in order as @Image1, @Image2. Stills combine with first and last frames.
- A clip on **Video** (`videoUrl`) runs an edit. Name it in the prompt as @Video1. You can add up to 8 reference stills. The edit keeps the clip's length, so it has no duration or aspect setting. The clip must be 3 to 30 seconds.

The edit price counts each second of the clip twice, because the provider bills the clip you send and the clip you get back.

A first or last frame does not combine with a clip. Video and sound references are refused. Both are refused before charging.

## Existing Veo 3.1 nodes

Veo 3.1 is retired and is no longer offered for new authoring.
Existing nodes keep their settings, connected inputs and generated videos.
Those videos still play. A new generation attempt shows a retirement message before any credits are held.
Choose another video model to generate a new clip. Keep the saved Veo 3.1 node until you have replaced its role in your story.

## Existing H3 Max Director nodes

H3 Max Director is retired and is no longer offered for new authoring.
Existing nodes keep their settings, connected inputs and generated videos.
Those videos still play. New generation attempts show a retirement message before any credits are held.
Existing generation requests can still be checked or cancelled. If the video finished but could not be saved, retry the same run to save it. Recovery checks the owner and model, uses the saved output, and does not start another job. A run waiting for confirmation keeps its waiting or reconciliation status. If the provider names that run later, checking it resumes normally.
Choose another video model to generate a new clip. Keep the saved Director node until you have replaced its role in your story.

---
Source commit: 9ccaa86d41d7 · Build date: 2026-11-17T03:27:39.423Z
