3D シーン

3D シーン API は、プロンプトと、任意の画像や動画のリファレンスから、編集できるアニメーション付きのクレイ調シーンを作成し、それを編集して、MP4 にレンダリングします。生成の結果は、動画ではなくシーンプランです。シーンプランにはオブジェクト、その動き、カメラ、ライティングが含まれているので、レンダリングの前に、フレーミング、カメラの動き、ブロッキングを確認できます。その後のレンダリングは、動画モデルのためのレイアウトリファレンスになります。

3D レンダリング Pro は別の操作で、デプロイメントに対応するエンジンがある場合に、完成したショットの作成とレンダリングを 1 つの有料ジョブで行います。ベーシックのシーン作成エンジンはすべてのエディションで動作しますが、アドバンスエンジンと 3D レンダリング Pro はデプロイメントによって異なるため、先にデプロイメントが対応している機能を確認してください。クレジットがかかるのは、Nodaro Cloud だけです。これらのルートは、ベアラートークンを受け付けます。認証を参照してください。

エンドポイント

POST /v1/generate-3d-scene と POST /v1/edit-3d-scene は、生成と編集のルートのエイリアスで、チェックとクレジットも同じです。POST /v1/render-video も、planType と plan を受け付けます。これらのエイリアスにより、SDK の汎用ノードランナーから同じルートを呼び出せます。

デプロイメントの対応状況を確認する

GET /v1/3d-scene/capabilities は、ベーシックへの対応状況と、advanced ブロックを返します。advanced ブロックは、アドバンスエンジンを利用できない場合は null です。pro ブロックは、3D レンダリング Pro が available かどうかを示し、提供できるエンジン、品質プロファイル、スタイル、アスペクト比、修正パスの上限を一覧にします。コントロールは、指定できる値の全体からではなく、このレスポンスをもとに組み立ててください。

デプロイメントが提供できないエンジンを指定すると、クレジットのチェックの前に 503 SCENE_CAPABILITY_UNAVAILABLE が返されます。Nodaro が勝手にベーシックのシーン作成に切り替えることはありません。また、3D レンダリング Pro を利用できない環境では、GET /v1/nodes の結果にそのノードが含まれません。インタラクティブな 3D プレビューの埋め込みを利用できる場合は、生成ノードに scene3d-embed-v1 機能が示されます。

シーンを生成する

POST /v1/3d-scene/generate は新しいシーンを作成し、{ jobId } を返します。ジョブはジョブ API でポーリングします。完了したジョブの output_data.scenePlan が、編集できるシーンです。

curl -X POST https://app.nodaro.ai/v1/3d-scene/generate \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red suitcase rolls behind a central pillar and reappears. Dolly right over four seconds.",
    "durationSeconds": 4,
    "fps": 24,
    "aspectRatio": "16:9",
    "references": [
      { "id": "suitcase-appearance", "kind": "image", "role": "appearance", "url": "https://cdn.nodaro.ai/uploads/suitcase.png" }
    ]
  }'

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

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

const scene = await client.nodes.runAndWait('generate-3d-scene', {
  prompt: 'A red suitcase rolls behind a central pillar and reappears. Dolly right over four seconds.',
  durationSeconds: 4,
  fps: 24,
  aspectRatio: '16:9',
  references: [{ id: 'suitcase-appearance', kind: 'image', role: 'appearance', url: appearanceImageUrl }],
})

nodaro nodes run generate-3d-scene --params-file scene.json --watch --json

• リファレンスはおおよその再現です：画像は、写っていない形状までは伝えません。動画は、動きとレイアウトのガイドとして読み取られます。レンダリングの前に、プレビューを確認してください。
• クリップ全体のみ：動画リファレンスは、全体が分析されます。クリップの一部を使うには、先に 動画のトリミング（Trim Video）でトリミングします。一部の時間範囲を指定すると、クレジットが使われる前に拒否されます。
• 保存済みのジオメトリ：inputAssets は、すでに持っている GLB ファイルの、特定のリビジョンを指定します。アクセス権とファイルのダイジェストはサーバー自身が確認するので、URL やハッシュは送らないでください。画像と動画は、references に入れます。ベーシックは、インポートしたジオメトリを課金の前に拒否します。
• 座標：シーンの単位はメートルで、Y 軸が上向きです。回転はラジアンで、フレームは 0 から数えます。

シーンを編集する

POST /v1/3d-scene/edit は、scenePlan、その revisionId を指定した expectedRevisionId、そして prompt（「move the pillar back one meter」のような指示）か operations のどちらかを受け取ります。編集が成功すると、古いリビジョンを parentRevisionId に持つ新しいリビジョンが作られます。送ったプランは変更されません。リビジョンが一致しない場合は拒否されます。完了したジョブは、scenePlan と changeSummary を返します。

curl -X POST https://app.nodaro.ai/v1/3d-scene/edit \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @edit.json

# edit.json:
# { "scenePlan": { ... }, "expectedRevisionId": "rev_7c2e...",
#   "operations": [{ "op": "set-camera", "changes": { "focalLengthMm": 50 } }] }

const edited = await client.nodes.runAndWait('edit-3d-scene', {
  scenePlan: scene.scenePlan,
  expectedRevisionId: scene.scenePlan.revisionId,
  operations: [{ op: 'set-camera', changes: { focalLengthMm: 50 } }],
})

指示による編集でオブジェクトを変更させたくない場合は、lockedObjectIds を送ります。新しい references は、ID をもとに既存のリファレンスと統合されます。同じ ID のリファレンスは置き換えられ、合計は生成時の上限を超えてはいけません。編集後のシーン全体が検証されるため、編集によって、孤立した親やリファレンスが残ることはありません。

操作は言語モデルを呼び出さず、0 クレジットです。指示による編集には、シーンの作成と同じティアが適用されます。元に戻したり比較したりできるように、以前のリビジョンを保持しておいてください。

保存済みのシーンに編集を保存する

バージョン 2 の保存済みのシーンでは、POST /v1/3d-scene/revisions/:revisionId/edits を使うと、ジョブを使わず、言語モデルの料金もかけずに、決定論的な編集（トランスフォーム、マテリアルの色、表示／非表示、カメラのオフセット）を保存できます。newRevisionId、ベースのリビジョンの expectedContentHash、operations、そして任意で lockedObjectIds を送ります。このルートは { scenePlan, changeSummary } を返します。

ダイジェストが古い場合や、リビジョン ID が競合する場合は、409 が返されます。リクエストが通信の途中で失敗した場合は、同じ newRevisionId と同じボディで再試行してください。このルートにはシーンの編集権限が必要で、OAuth アプリのトークンには workflows:write が必要です。新しいリビジョンは保存されるだけで、選択はされません。その間に誰もアクティブなリビジョンを変更していないことを確認してから、ワークフローで新しいリビジョンを自分で選択してください。

シーンを MP4 にレンダリングする

{ "planType": "3d-scene", "plan": scenePlan } を指定した POST /v1/render-video/plan は、特定の 1 つのリビジョンをレンダリングします。カメラ、フレームサイズ、フレームレート、長さはプランから取得されます。言語モデルは呼び出されず、プロンプトが読み直されることもありません。完了したジョブは、videoUrl、thumbnailUrl、sceneRevisionId、renderer: "scene3d/three" を返します。

curl -X POST https://app.nodaro.ai/v1/render-video/plan \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"planType\": \"3d-scene\", \"plan\": $(cat scene-plan.json) }"

const clip = await client.nodes.runAndWait('render-video', {
  planType: '3d-scene',
  plan: edited.scenePlan,
})

レンダリングの料金は、プラン自体の width と height で決まります。

生成ルートで選べるアスペクト比は、どれも 1920 ピクセル以下でレンダリングされます。そのため、サイズを変更していないシーンは、常に基本料金です。上位の料金区分が適用されるのは、プランに自分で大きな width と height を設定した場合だけです。モデル料金の識別子は、render-video、render-video:3d-large、render-video:3d-xlarge です。

レンダリングを動画リファレンスとして使う

クレイ調のレンダリングは、レイアウトを伝えます。被写体の位置、ものの前後関係、フレーミング、カメラの動き、タイミングです。同時に、テクスチャーのないグレーのクレイという見た目も持っており、動画モデルは、そうしないよう指示されない限り、その見た目を真似します。次の 2 つのルールを守れば、レイアウトを残し、クレイの見た目を取り除けます。

1. リファレンスの用途を必ず限定する：動画生成（Generate Video）の referenceVideoUrls[N] に MP4 を渡し、referenceVideoCaptions[N] に、何を合わせて何を無視するかを書いたキャプションを付けます。ワークフローでは、Nodaro がこのキャプションを自動で追加します。その文言は次のとおりです。「LAYOUT reference only — match its subject positions and blocking, its foreground occlusion, its framing, its camera angle, its camera motion and its timing. Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look. Take the look from the prompt and from the other references」
2. 本物らしく見せる人物には、それぞれ専用のキャラクターリファレンスを付ける：キャラクターリファレンスのない人物は、クレイの代役のままです。ロケーションやスタイルの画像のために、リファレンスの枠を 2 つ空けておいてください。

元の見た目用の画像も送ってください。また、レンダリングは決して開始フレームとして使わないでください。開始フレームは見た目を決めてしまい、キャプションもそこには届きません。

3D レンダリング Pro を実行する

3D レンダリング Pro は、ホスト型のビルドエンジン上で、シーンの作成とエクスポートを 1 つの永続的なジョブで行います。1 回の実行で、正確なコンポジションと MP4 の両方がそろって完了します。料金はデプロイメントが設定するため、見積もりが基準になります。

curl -X POST https://app.nodaro.ai/v1/pro-3d-render/quote \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @pro.json

curl -X POST https://app.nodaro.ai/v1/pro-3d-render \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Idempotency-Key: suitcase-shot-0001" \
  -H "Content-Type: application/json" \
  -d @pro-with-quote.json

const caps = await client.scene3d.capabilities()
if (caps.pro?.available) {
  const params = {
    source: {
      kind: 'prompt' as const,
      prompt: 'A red suitcase rolls behind a central pillar and reappears',
      references: [{ id: 'look', kind: 'image' as const, role: 'appearance' as const, url: appearanceImageUrl }],
    },
    durationSeconds: 30,
    fps: 24,
    aspectRatio: '21:9',
    maxRepairPasses: 2,
    acceptedSceneSchemaVersions: [2],
  }
  const quote = await client.scene3d.quotePro(params)
  console.log(quote.maxCredits, quote.breakdown)
  const shot = await client.scene3d.renderProAndWait({ ...params, quoteId: quote.quoteId })
  console.log(shot.videoUrl, shot.sceneRevisionId)
}

ボディの source は、次のいずれか 1 つです。

モデルのフィールドはありません。プランナーは固定です。scene ソースでは、シーン自身のタイミングを保つために、タイミングのフィールドを省略します。指定するとシーンのタイミングが変更され、合わない値は拒否されます。プロンプトのソースはバージョン 2 のシーンを作るため、バージョン 2 を受け付けないクライアントは、料金がかかる前に拒否されます。

完了した実行が返すもの

各静止画の url は、公開リンクではなく、デプロイメント上の認証が必要なエンドポイントです。自分のトークンを使って取得してください。それでも、この URL は生成の画像リファレンスとして渡せます。その場合、Nodaro はその実行に、そのファイル 1 つだけを読み取れる短時間の権限を与えます。

metadata.review があるかどうかを確認してから、その verdict を読んでください。refused は、修正パスの上限を使い切った後もレビューが異議を示していたことを意味し、objections に指摘された内容が一覧になります。unavailable は、レビューが使える回答を返さず、誰もシーンを評価していないことを意味します。どちらの場合も、必須のチェックには合格しているため、validation.status は passed のままです。警告コードの種類は固定されていないので、知らないコードは情報として扱ってください。すべてのフィールドと警告コードについては、3D レンダリング Pro を参照してください。

実行が失敗した場合

送信時のエラーは、拒否です。503 SCENE_CAPABILITY_UNAVAILABLE、503 price_not_configured（管理者が料金を設定していません。何も確保されていません）、400 validation_error があります。実行中の失敗はジョブに記録され、エラーメッセージはコードから始まります。

失敗したアドバンスエンジンのジョブにも、構築したものが残っている場合があります。パスでシーンが構築された場合、output_data に下書きが入ります。scenePlan、sceneRevisionId、deliveryId、posterAssetId、そして status: "failed" の validation です。下書きは通常のリビジョンなので、編集やレンダリングができます。何もコンパイルされなかった場合、下書きはありませんが、拒否されたレシピが保持されたかどうかを validation.sourceRetained が示します。レシピは、編集権限があれば、納品の source-json 記述子から無料で読み取れます。同じプロンプトをもう一度実行すると、同じシーン作成の料金を 2 回払うことになります。

ワークフローの実行では、結果を保持した失敗ノードは、その結果を nodeStates[nodeId].output にも持ちます。ステータスではなくフィールドの有無を確認し、output があるからといって成功とみなさないでください。

シーンのバージョンと保存済みのアセット

シーンプランは、2 つのバージョンのユニオン型です。バージョン固有のフィールドを読む前に、schemaVersion を確認してください。

バージョン 2 のプランは、各アセットを、不透明な assetId、バイト長、SHA-256 ダイジェストで列挙します。ストレージのキーやダウンロード URL が含まれることはありません。バージョン 2 が受け付けるのは、剛体アニメーションのクレイのジオメトリです。テクスチャー付き、スキニング付き、モーフィング付きのアセットは拒否されます。上限は、エンティティ 100 個、メッシュノード 2,000 個、三角形 200,000 個、ショット 32 個、再生用アセット 64 MiB です。完全な形式は、シーンプランの形式を参照してください。

保存済みのリビジョンには、専用のルートがあります。これらのルートはベアラートークンを必要とし、Cache-Control: no-store で応答します。削除されたリビジョンやアクセスできないリビジョンには、404 を返します。

• GET /v1/3d-scene/revisions/:revisionId は、マニフェストとアセット記述子を返します。再生用アセットにはリビジョンのワークフローの閲覧権限が、ネイティブのソースには編集権限が必要です。個人のリビジョンには、所有者しかアクセスできません。
• GET /v1/3d-scene/deliveries/:jobId は、エクスポートが納品したものを返します。sourceKind、正確な sceneRevisionId、ソースのダイジェスト、記述子（ポスター、検証レポート、ショットごとに 1 つの shot-still）です。…/assets/:assetId はバイトデータを返し、Range リクエストに対応しています。読み取りには、納品とソースのワークフローの両方へのアクセス権が必要で、料金はかかりません。

SDK では、client.scene3d.getDelivery、deliveryAssetBytes、retainedRecipe、assetBytes、sourceBytes、applyEdits が、これらのルートをラップしています。

MCP から使う

AI アシスタントは、workflows:execute スコープで generate_3d_scene、edit_3d_scene、render_3d_scene を使い、デプロイメントが対応している場合は pro_3d_render も使います。MCP での 3D シーンを参照してください。自分のページにシーンを表示するには、3D プレビューの埋め込みを参照してください。

エラー