Pipelines

The Pipelines API runs Story → Video from code. You send a one-line story. The pipeline engine writes a script, creates the cast, props and places, and plans the shots. It then renders keyframes, animates them with sound and merges the film. Each stage can stop for your approval, run by itself, or open a chat with the director.

Pipelines run on Nodaro Cloud only; Community and Business editions answer 403 edition_required. On a self-hosted install, build the same steps as a workflow with nodes such as Generate Script, Generate Image and Generate Video. The routes take a bearer token; OAuth app tokens need the scopes listed below. See Authentication.

Endpoints

Stages and modes

A pipeline walks eight stages in order. :stage in a path is one of these names.

The mode you choose at creation decides who moves the pipeline forward:

Start a pipeline

POST /v1/pipelines creates the pipeline, reserves its credits and starts it. It answers 201 with { id }.

curl -X POST https://app.nodaro.ai/v1/pipelines \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "root_node_id": "0e6b2f7c-4a1d-4c8e-9b3f-5d7a2c1e8f4b",
    "story_prompt": "A lighthouse keeper must restart the light before the storm hits.",
    "format": "short_film",
    "target_duration_seconds": 60,
    "mode": "auto",
    "output_resolution": "720p"
  }'

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const { id } = await client.pipelines.create({
  root_node_id: crypto.randomUUID(),
  story_prompt: 'A lighthouse keeper must restart the light before the storm hits.',
  format: 'short_film',
  target_duration_seconds: 60,
  mode: 'auto',
})

{ "id": "c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c" }

Each format allows a range of lengths:

Follow a pipeline

GET /v1/pipelines/:id returns the pipeline's state. Poll it every few seconds, or open GET /v1/pipelines/:id/events to receive the changes as server-sent events.

{
  "id": "c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c",
  "status": "running",
  "current_stage": "scene_images",
  "mode": "auto",
  "spent_credits": 412,
  "reserved_credits": 1180,
  "upfront_credit_estimate": 1650,
  "failure_reason": null,
  "current_progress_message": "Rendering keyframe 5 of 9",
  "branched_from_pipeline_id": null,
  "branched_from_stage": null
}

status is queued, running, awaiting_approval, completed, failed, cancelled or forked. failure_reason explains a failed pipeline.

When the pipeline is completed, GET /v1/pipelines/:id/timeline returns the film as data you can render or hand to an editor:

{
  "fps": 24,
  "width": 1280,
  "height": 720,
  "scenes": [
    { "compositeUrl": "https://cdn.nodaro.ai/pipelines/scene-1.mp4", "durationSeconds": 8.5 },
    { "compositeUrl": "https://cdn.nodaro.ai/pipelines/scene-2.mp4", "durationSeconds": 11 }
  ],
  "musicUrl": "https://cdn.nodaro.ai/pipelines/score.mp3",
  "narrationUrl": "https://cdn.nodaro.ai/pipelines/narration.mp3"
}

While the animate stage runs, the timeline also carries animateProgress: { totalShots, shotsDone, percent }. To finish the cut in an external editor, see Export a timeline.

curl https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c \
  -H "Authorization: Bearer $NODARO_API_KEY"

curl https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/timeline \
  -H "Authorization: Bearer $NODARO_API_KEY"

const pipeline = await client.pipelines.get(id)
console.log(pipeline.status, pipeline.current_stage)

const timeline = await client.pipelines.getTimeline(id)
for (const scene of timeline.scenes) {
  console.log(scene.compositeUrl, scene.durationSeconds)
}

Approve or reject a stage

In manual and guided mode, each stage stops at awaiting_approval. GET /v1/pipelines/:id/pending-approvals lists the stages waiting, each { stage_name, output }. Read a stage in full with GET /v1/pipelines/:id/stages/:stage, which returns { status, output, critic_feedback }.

• Approve. POST /v1/pipelines/:id/stages/:stage/approve returns { ok: true } and the pipeline moves on. To change the stage's output first, send { edits }: a JSON Patch applied to the output before approval.
• Reject. Only the script can be rejected. POST /v1/pipelines/:id/stages/script/reject with { feedback } returns { ok: true }, and the engine writes the script again with your note in mind. Another stage answers 400 stage_not_implemented. You can reject the script at most twice, and fewer times if the automatic script reviewer has already revised it.

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/stages/script/approve \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "edits": [{ "op": "replace", "path": "/title", "value": "The Last Light" }] }'

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/stages/script/reject \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "feedback": "Make the story darker and more suspenseful." }'

const approvals = await client.pipelines.pendingApprovals(id)
const { output } = await client.pipelines.getStage(id, 'script')

await client.pipelines.approveStage(id, 'script', [
  { op: 'replace', path: '/title', value: 'The Last Light' },
])
// or
await client.pipelines.rejectStage(id, 'script', 'Make the story darker and more suspenseful.')

Checkpoints inside the animate stage

In manual and guided mode, the animate_audio_edit stage can stop at two checkpoints of its own:

• dialogue_recheck. The stage compares the real length of the dialogue with the plan and adjusts the scene timing. When a scene cannot stay within 10% of its target, the stage waits for your approval.
• silent_cut_preview. The stage assembles a preview of the cut without music and waits for your approval before it generates, and pays for, the music.

POST /v1/pipelines/:id/sub-gates/:gate/approve resumes the stage and returns { ok: true, gate, resumed_at }. POST /v1/pipelines/:id/sub-gates/:gate/reject fails the stage and the pipeline, and refunds the unspent credits. In auto mode, the stage continues without stopping.

Match-cut breaks in the scene images stage

The scene_images stage can stop at a third checkpoint, match_cut_break_pending. It stops there in every mode, auto included, when a planned match cut between two shots does not hold. The stage output lists the shots in match_cut_break_pending.

The sub-gate routes above do not clear it. They answer 400 invalid_sub_gate, and the error message names the route that does. Accept each break with POST /v1/pipelines/:id/entities/:sceneId/helpers/accept_match_cut_break and { "shotId": "<shot id>" }. sceneId is the id of the scene that holds the shot, not its metadata.scene_id. GET /v1/pipelines/:id/entities?type=scene lists the scenes, each with its shots in metadata.scene_node_data.shots.

Accepting a break needs the pipelines:approve scope and costs no credits. The call returns { ok: true, pendingRemaining }, the number of breaks still waiting. When the last one is accepted, the stage continues. An accepted break stays accepted when the scene_images stage runs again. Running the shot_list stage again plans the scenes anew and clears every acceptance, so a break that comes back must be accepted again.

Chat with the director

In guided mode, a stage waiting for approval has a chat. Send a message of up to 8,000 characters with POST /v1/pipelines/:id/stages/:stage/chat and { message }. The director answers in one sentence and may propose a change.

{
  "turnId": "f1a3c5e7-9b2d-4f6a-8c1e-3d5b7f9a2c4e",
  "role": "assistant",
  "content": "I moved the keeper's reason for staying into scene 2 and tightened the ending.",
  "proposed_change": {
    "change_type": "edit_artifact",
    "json_patch": [{ "op": "replace", "path": "/scenes/1/description", "value": "The keeper finds his late wife's log and decides to stay." }]
  }
}

proposed_change is null, an edit_artifact with a json_patch, or a suggest_branch with from_stage and a reason.

To accept a proposal, call POST /v1/pipelines/:id/stages/:stage/chat/turns/:turnId/apply. It returns { applied: true, attemptId, newOutput } and approves the stage. When the change breaks the plan, for example by removing a character a scene still uses, it returns { applied: false, error } and the director adds a turn that explains what to fix. A proposal that is not valid, or a stage that is no longer waiting, answers 409. GET /v1/pipelines/:id/stages/:stage/chat returns { turns }, the whole conversation.

A guided pipeline reserves extra credits for the chat when it starts. Unused credits are refunded.

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/stages/script/chat \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Make the keeper'\''s motivation clearer in scene 2." }'

const reply = await client.pipelines.chatStage(id, 'script', "Make the keeper's motivation clearer in scene 2.")
if (reply.proposed_change) {
  const result = await client.pipelines.applyChatProposal(id, 'script', reply.turnId)
  if (!result.applied) console.log(result.error.code)
}

Branch a finished pipeline

POST /v1/pipelines/:id/branch re-runs a completed pipeline from one stage, as a new pipeline. The stages before fromStage are copied as approved, fromStage starts running, and the stages after it are created fresh. The original pipeline stays completed.

The branch copies the characters, objects and locations into the new pipeline but reuses their image files, so no file is duplicated. It starts with an empty chat.

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/branch \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fromStage": "scene_images" }'

const branch = await client.pipelines.branch(id, { fromStage: 'scene_images' })
console.log(branch.pipelineId, branch.clonedStages)

The route answers 201 with { pipelineId, clonedStages, clonedEntities }: the new pipeline's id, the stages copied as approved, and the number of characters, objects and locations copied. fromStage is any stage name from the table above.

Cancel or fork a pipeline

• Cancel. POST /v1/pipelines/:id/cancel stops a running pipeline, refunds the credits reserved for work that has not run, and returns { ok: true }. A pipeline that has already completed, failed or been cancelled answers 409 already_terminal, and nothing changes.
• Fork. POST /v1/pipelines/:id/fork takes the canvas away from the pipeline. Every node it created becomes an ordinary node you can edit, the unspent credits are refunded, and the status becomes forked. A fork cannot be undone. To continue with the engine, start a new pipeline.

Availability

A deployment can offer or withhold the film pipeline like a node. Its availability id is film-pipeline, listed in the surface profile's nodes.allow or nodes.deny. See Editions and surface profiles.

Where the pipeline is not offered to you, these routes answer 403 node_not_available, before anything is reserved or charged:

• POST /v1/pipelines.
• Every POST under /v1/pipelines/:id/ that starts or continues work. That is branch, fork, stage approve, edit, reject and chat, applying a chat proposal, scene and shot regenerations, retries, and the entity, sub-gate and scene-helper actions.

The reads (GET), switching a run to manual (PATCH /v1/pipelines/:id) and POST /v1/pipelines/:id/cancel stay open. So you can still follow and stop a pipeline that you started before.

A pipeline that is already running when the feature is withheld does not start its next stage, also in auto mode. It ends failed with failure_reason: "node_not_available", and its unspent reservation is refunded. A pipeline paused at an approval gate stays paused.

Credits

The pipeline reserves its estimated cost when it starts; upfront_credit_estimate shows it. spent_credits and reserved_credits show where the run stands. A cancelled or failed pipeline refunds what it did not spend, and max_cost_credits caps the total. See Credits.

Use it from MCP and the SDK

The SDK wraps every route as client.pipelines.*. The CLI has no pipeline commands. AI assistants use these MCP tools:

See Film Director for the guided way to direct a film from an assistant.

Errors