パイプライン

パイプライン API は、コードからストーリー → 動画（Story → Video）を実行します。1 行のストーリーを送信すると、パイプラインエンジンが脚本を書き、キャスト、小道具、ロケーションを作成し、ショットを計画します。続けて、キーフレームをレンダリングし、音声付きで動画化して、映画を結合します。各ステージは、あなたの承認を待って停止することも、自動で進むことも、監督とのチャットを開くこともできます。

パイプラインは Nodaro Cloud でのみ動作します。Community エディションと Business エディションでは 403 edition_required が返されます。セルフホスティング環境では、脚本生成（Generate Script）、画像生成（Generate Image）、動画生成（Generate Video）などのノードを使って、同じ手順をワークフローとして組み立てます。ルートにはベアラートークンが必要です。OAuth アプリのトークンには、以下に挙げるスコープが必要です。認証を参照してください。

エンドポイント

ステージとモード

パイプラインは、8 つのステージを順番に進みます。パスの :stage には、次のいずれかの名前が入ります。

作成時に選ぶ mode によって、パイプラインを誰が先に進めるかが決まります。

パイプラインを開始する

POST /v1/pipelines は、パイプラインを作成してクレジットを確保し、開始します。{ id } とともに 201 を返します。

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" }

各 format には、使える長さの範囲があります。

パイプラインの進行を確認する

GET /v1/pipelines/:id は、パイプラインの状態を返します。数秒おきにポーリングするか、GET /v1/pipelines/:id/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 は、queued、running、awaiting_approval、completed、failed、cancelled、forked のいずれかです。failure_reason は、failed になったパイプラインの理由を説明します。

パイプラインが completed になると、GET /v1/pipelines/:id/timeline は、レンダリングしたり編集アプリに渡したりできるデータとして、映画を返します。

{
  "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"
}

動画化ステージの実行中は、timeline に animateProgress（{ totalShots, shotsDone, percent }）も含まれます。外部の編集アプリでカットを仕上げる方法については、タイムラインを書き出すを参照してください。

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)
}

ステージを承認または却下する

manual モードと guided モードでは、各ステージが awaiting_approval で停止します。GET /v1/pipelines/:id/pending-approvals は、待機中のステージを一覧表示し、それぞれ { stage_name, output } です。ステージの全体は GET /v1/pipelines/:id/stages/:stage で読み取り、{ status, output, critic_feedback } が返されます。

• 承認する。POST /v1/pipelines/:id/stages/:stage/approve は { ok: true } を返し、パイプラインが先に進みます。先にステージの出力を変更するには、{ edits } を送信します。承認の前に出力に適用される JSON Patch です。
• 却下する。却下できるのは脚本だけです。{ feedback } を付けて POST /v1/pipelines/:id/stages/script/reject を呼び出すと、{ ok: true } が返され、エンジンはその内容を踏まえて脚本を書き直します。ほかのステージでは 400 stage_not_implemented が返されます。脚本を却下できるのは最大 2 回で、脚本のクリティックによってすでに修正されている場合は、それより少なくなります。

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.')

動画化ステージの中のチェックポイント

manual モードと guided モードでは、animate_audio_edit ステージが、独自の 2 つのチェックポイントで停止することがあります。

• dialogue_recheck。このステージは、セリフの実際の長さを計画と比較し、シーンのタイミングを調整します。シーンが目標の 10% 以内に収まらない場合、ステージはあなたの承認を待ちます。
• silent_cut_preview。このステージは、音楽なしのカットのプレビューを組み立て、音楽を生成して料金が発生する前に、あなたの承認を待ちます。

POST /v1/pipelines/:id/sub-gates/:gate/approve はステージを再開し、{ ok: true, gate, resumed_at } を返します。POST /v1/pipelines/:id/sub-gates/:gate/reject は、ステージとパイプラインを失敗させ、使われなかったクレジットを返還します。auto モードでは、ステージは停止せずに続行します。

シーン画像ステージでのマッチカットの不連続

scene_images ステージは、3 つ目のチェックポイントである match_cut_break_pending で停止することがあります。2 つのショットの間で計画したマッチカットが成立しない場合、auto を含むすべてのモードで、ここで停止します。ステージの出力の match_cut_break_pending に、該当するショットが列挙されます。

上のサブゲートのルートでは、このチェックポイントを解除できません。これらのルートは 400 invalid_sub_gate を返し、エラーメッセージには、解除に使うルートが示されます。不連続は 1 件ずつ、{ "shotId": "<shot id>" } を付けて POST /v1/pipelines/:id/entities/:sceneId/helpers/accept_match_cut_break で承認します。sceneId は、そのショットを含むシーンの id で、metadata.scene_id ではありません。GET /v1/pipelines/:id/entities?type=scene はシーンを一覧表示し、各シーンのショットは metadata.scene_node_data.shots に含まれます。

不連続を承認するには pipelines:approve スコープが必要で、クレジットはかかりません。この呼び出しは { ok: true, pendingRemaining } を返します。pendingRemaining は、まだ待機中の不連続の数です。最後の 1 件を承認すると、ステージが続行します。

監督とチャットする

guided モードでは、承認待ちのステージにチャットがあります。POST /v1/pipelines/:id/stages/:stage/chat に { message } を付けて、最大 8,000 文字のメッセージを送信します。監督は 1 文で答え、変更を提案することもあります。

{
  "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 は、null、json_patch を持つ edit_artifact、または from_stage と reason を持つ suggest_branch のいずれかです。

提案を受け入れるには、POST /v1/pipelines/:id/stages/:stage/chat/turns/:turnId/apply を呼び出します。{ applied: true, attemptId, newOutput } を返し、ステージを承認します。変更が構成案を壊す場合、たとえば、シーンでまだ使われているキャラクターを削除してしまう場合は、{ applied: false, error } が返され、監督が何を直せばよいかを説明するターンを追加します。有効ではない提案や、すでに待機中ではなくなったステージには、409 が返されます。GET /v1/pipelines/:id/stages/:stage/chat は、会話全体である { turns } を返します。

ガイド付きのパイプラインは、開始時にチャット用として 40 クレジットを追加で確保します。使わなかった分は返還されます。

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)
}

完成したパイプラインを分岐する

POST /v1/pipelines/:id/branch は、completed になったパイプラインを 1 つのステージから再実行し、新しいパイプラインにします。fromStage より前のステージは承認済みとしてコピーされ、fromStage は実行を開始し、それ以降のステージは新しく作成されます。元のパイプラインは completed のままです。

分岐は、キャラクター、オブジェクト、ロケーションを新しいパイプラインにコピーしますが、画像ファイルは再利用するため、ファイルが重複することはありません。チャットは空の状態で始まります。

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)

このルートは、{ pipelineId, clonedStages, clonedEntities } とともに 201 を返します。新しいパイプラインの id、承認済みとしてコピーされたステージ、コピーされたキャラクター、オブジェクト、ロケーションの数です。fromStage には、上の表にあるどのステージ名でも指定できます。

パイプラインをキャンセルまたはフォークする

• キャンセルする。POST /v1/pipelines/:id/cancel は、実行中のパイプラインを停止し、まだ実行されていない作業分の確保済みクレジットを返還して、{ ok: true } を返します。すでに完了、失敗、キャンセルのいずれかの状態になったパイプラインでは 409 already_terminal が返され、何も変わりません。
• フォークする。POST /v1/pipelines/:id/fork は、キャンバスをパイプラインの管理から外します。パイプラインが作成したすべてのノードは、編集できる通常のノードになり、使われなかったクレジットが返還され、status は forked になります。フォークは元に戻せません。引き続きエンジンを使うには、新しいパイプラインを開始してください。

クレジット

パイプラインは、開始時に見積もり額を確保します。upfront_credit_estimate に表示されます。spent_credits と reserved_credits は、実行の現在の状況を示します。キャンセルまたは失敗したパイプラインは、使わなかった分を返還し、max_cost_credits が合計の上限になります。クレジットを参照してください。

MCP と SDK から使う

SDK は、すべてのルートを client.pipelines.* としてラップしています。CLI にはパイプラインのコマンドはありません。AI アシスタントは、次の MCP ツールを使います。

アシスタントから映画をガイド付きで監督する方法については、Film Director を参照してください。

エラー