# 3D シーン

> プロンプトから編集できるクレイ調の 3D シーンを作り、修正して MP4 にレンダリングします。レンダリングした動画は、動画モデルのレイアウトと動きのガイドとして使えます。

Source: https://nodaro.ai/ja/docs/mcp/3d-scenes

**3D シーン**は、編集できるアニメーション付きのクレイ調シーンです。単純な形状とキーフレームによる動きで構成され、プロンプトと、任意の画像や動画のリファレンスから作成されます。AI アシスタントからシーンを作成し、言葉による指示か正確な操作で修正して、MP4 にレンダリングします。レンダリングした動画は、動画モデルのレイアウトと動きのガイドとして使います。MCP ツールは、キャンバス上の [**3D シーン生成**（Generate 3D Scene）](https://nodaro.ai/docs/nodes/video/generate-3d-scene)ノードと [**3D シーン編集**（Edit 3D Scene）](https://nodaro.ai/docs/nodes/video/edit-3d-scene)ノードと同じ処理を行います。

## ツール
| ツール | 機能 |
| --- | --- |
| `generate_3d_scene` | プロンプトと任意のリファレンスから、編集できるシーンを作ります |
| `edit_3d_scene` | シーンのリビジョンと、指示または操作から、新しいリビジョンを作ります |
| `render_3d_scene` | 指定したシーンのリビジョンを、**動画レンダリング**（Render Video）のエンジンで MP4 にします |
| `pro_3d_render` | シーンの作成、修正、エクスポートのいずれかを 1 つのジョブで行い、シーンプラン、MP4、ショットごとの静止画 1 枚を返します。このエンジンがあるデプロイメントでのみ使えます |

どのツールにも `workflows:execute` が必要で、ツールはジョブ ID を返します。結果は `get_job` または `wait_for_job` で読み取ります。シーンのジョブは `output_data.scenePlan` を返し、レンダリングは動画の URL を返します。パラメーターは[ツールリファレンス](https://nodaro.ai/docs/mcp/tools/3d-scenes)に記載されています。

## 作業の流れ
### シーンを生成する
ショットの説明、`duration_seconds`、`fps`、`aspect_ratio` を指定して、`generate_3d_scene` を呼び出します。リファレンスは `{ id, url, kind, role }` の形式で、見た目、レイアウト、動きのいずれかに使う画像または動画です。

### 修正する
完了したジョブから `scenePlan` を読み取ります。そのオブジェクトを `scene_plan` に、その `revisionId` を `expected_revision_id` に指定し、編集の `prompt` か `operations` のどちらかを付けて、`edit_3d_scene` を呼び出します。変えてはいけないオブジェクトは、`locked_object_ids` に列挙します。

### レンダリングする
得られた `scene_plan` を指定して、`render_3d_scene` を呼び出します。LLM は実行されません。

### レンダリングをガイドとして使う
MP4 を `reference_video_urls` に入れて [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video) に渡し、同じ位置の `reference_video_captions` に、その用途を書きます。見た目の画像も、引き続きリファレンスとして渡してください。

クレイ調のレンダリングは、レイアウトのガイドであって、見た目の手本ではありません。キャプションがないと、動画モデルがグレーのクレイの見た目まで真似てしまうことがあります。

## 最初のバージョンでできること
- **形状と動き**：シーンは、プリミティブな形状と、決定論的なキーフレームアニメーションを使います。
- **リファレンスはおおよその再現になります**。リファレンスをもとに作ったシーンは、元のリファレンスの近似です。
- **動画リファレンスは全体を使用**：動画リファレンスは、クリップ全体が使われます。一部だけを使うには、先にクリップをトリミングし、トリミングした URL を渡します。一部の時間範囲を指定すると、シーン作成の料金が発生する前に拒否されます。
- **操作では LLM を呼び出しません**。`operations` による編集は、そのまま適用されます。レンダリングも同様です。

## エンジン
`generate_3d_scene` と `edit_3d_scene` は `engine` を受け付けます。値は、`basic`（デフォルト）、`blender-cloud`、`blender-local` のいずれかです。アドバンスエンジンは、デプロイメントで利用できる必要があります。利用できないエンジンを指定すると拒否され、`basic` に切り替わることはありません。アドバンスエンジンは固定のプランナーを使うため、`llm_model` と `reasoning_effort` は指定せず、修正の上限は `max_repair_passes` で設定します。

インポートに対応したアドバンスエンジンでは、`generate_3d_scene` は `input_assets` も受け付けます。既存の 3D モデル（GLB）を最大 8 個まで指定でき、それぞれ `{ id, revisionId, assetId, label }` の形式です。画像と動画は、引き続き `references` に入れます。エンジンがインポートに対応していない場合、インポートは料金が発生する前に拒否されます。また、ファイルはサーバー自身が解決するため、URL やハッシュは送らないでください。

## レンダリングの料金
レンダリングの料金は、渡したプランのフレームサイズで決まります。

| フレーム | クレジット |
| --- | --- |
| 長辺が 1920 ピクセルまで | 50 |
| それを超え、5.12 メガピクセルまで | 75 |
| それより大きい | 125 |

シーンプランの `width` と `height` は、意図して設定してください。2560×2560 のシーンは 1920×1080 のシーンの 2.5 倍の料金ですが、1920×1920 は 1920×1080 と同じ料金です。完全な表は、[動画レンダリング](https://nodaro.ai/docs/nodes/video/render-video)にあります。

## アドバンスエンジンの結果を読む
アドバンスエンジンが作成したシーンは、エンジンが置いた前提と、実行した処理を報告します。以下のフィールドはすべて任意で、`basic` エンジンはどれも報告しません。

| フィールド | 報告される内容 |
| --- | --- |
| `SCENE_AUTHORING_ASSUMPTION` の付いた `validation.warnings[]` | プランナーが置いた前提 |
| `metadata.summary` | 作成したものについての、エンジン自身による説明 |
| `repairPasses` | 実行された修正。最初の試行でシーンが受け入れられた場合は `0` |
| `admissionRetries` | ビルド前のプランナーの再試行。修正パスは消費しません |
| `mechanicalPasses` | プランナーを呼び出さずに、コンパイラー自身の修正案からエンジンが適用した修正。それぞれに `REMEDY_AUTO_APPLIED` 警告が付きます。`repairPasses` とは別に、見積もりに含まれた専用の枠で数えられます。 |
| `restoredAssertions` | 応答によって変更された必須のチェックを、エンジンが元に戻したもの。それぞれに `ASSERTION_RESTORED` 警告が付きます |

レンダリングのみのエクスポートは何も作成しないため、概要は報告されず、各回数も含まれません。

### 完了したシーンが承認されなかった場合
完了したジョブに `metadata.review` が含まれることがあります。これは、シーンがビジュアルレビューの承認なしに納品されたことを意味します。ステータスや警告の数ではなく、`metadata.review` があるかどうかを確認し、ユーザーに何かを伝える前に、その `verdict` を読んでください。

- **`refused`**：修正パスの上限を使い切り、必須のチェックにはすべて合格しましたが、それでもレビューが異議を示しました。シーンには、異議の内容と、異議 1 つにつき 1 つの `SCENE_REVIEW_REFUSED` 警告が付きます。
- **`unavailable`**：レビューが、`attempts` 回の試行で使える判定を返しませんでした。`reason` は、レビューがモデルに届かなかった場合は `provider`、応答が使えなかった場合は `unusable` です。シーンは誰にも評価されておらず、`validation.warnings[]` は `SCENE_REVIEW_UNAVAILABLE` から始まります。誰もレビューしていないシーンについて、拒否されたと報告しないでください。

どちらの場合も `validation.status` は `passed` のままで、異議のリストが空のこともあります。

### アドバンスエンジンのジョブが失敗した場合
`SCENE_QUALITY_FAILED` で失敗したジョブは、品質を保証できるシーンを作れないまま、上限を使い切っています。もう一度実行する前に、その `output_data` を読んでください。

- **下書きが構築された場合**：失敗したジョブは、`scenePlan`、`sceneRevisionId`、`deliveryId`、`posterAssetId` で下書きを示し、`validation.status` は `failed` です。下書きは通常のリビジョンなので、`edit_3d_scene` や `render_3d_scene` に渡せます。
- **何もコンパイルされなかった場合**：`scenePlan` はありませんが、ジョブには `deliveryId` があり、`validation.sourceRetained` が、レシピが保持されたかどうかを示します。REST API の `GET /v1/3d-scene/deliveries/{deliveryId}` で取得し、続けてその `source-json` アセットを取得します。読み取りにクレジットはかかりませんが、あなた自身の認証情報と、ジョブのワークフローの編集権限が必要です。これを行う MCP ツールはありません。

まったく同じプロンプトをもう一度実行すると、同じシーン作成の料金を 2 回払うことになります。

## 3D レンダリング Pro
[`pro_3d_render`](https://nodaro.ai/docs/mcp/tools/3d-scenes#pro_3d_render) は、`generate_3d_scene` のオプションではなく、別の操作です。1 つのジョブで、完成したショットを作ります。完了した出力には `scenePlan` と `videoUrl` の両方が含まれ、リビジョン、ポスター、検証結果、レンダラーの詳細も付きます。このツールは、それを実装したエンジンがあるデプロイメントにしか表示されません。そのため、ツールの一覧にあるかどうかで、利用できるかを確認できます。[**3D レンダリング Pro**（3D Render Pro）](https://nodaro.ai/docs/nodes/video/pro-3d-render)ノードと同じように動作します。

出力には `shotStills` も含まれます。これは、コンポジションのショットごとに 1 枚の静止画を、ショットの順に並べたもので、形式は `{ shotIndex, frame, assetId, url }` です。`shotIndex` は 0 から数え、`frame` はショットの最初のフレームなので、静止画は MP4 と位置がそろいます。ショットが 1 つだけのシーンでは、フレーム 0 の静止画がちょうど 1 枚です。静止画は同じ実行から作られ、追加料金はかかりません。動画モデルでそのショットを生成するときは、そのショットの静止画を画像リファレンスとして使います。

納品ファイルは非公開なので、各静止画の `url` は、インストール環境上の、認証が必要なアドレスです。取得するには、あなた自身の認証情報を使います。公開リンクではありません。それでも、この URL は `generate_image` や `generate_video` に渡せます。その実行には、そのファイル 1 つだけを読み取れる短時間の権限が与えられます。この権限は数分間だけ有効で、保存されないため、何かを保存するときは、認証が必要な URL のほうを残してください。

安価で編集できるクレイ調のプリビズには、`generate_3d_scene`、`edit_3d_scene`、`render_3d_scene` を使います。シーンの正確な形式と現在のデフォルト値を知るには、`generate-3d-scene` または `edit-3d-scene` を指定して `get_node_skill` を呼び出すよう、アシスタントに頼んでください。

## Frequently asked questions

### Nodaro の 3D シーンとは何ですか？

単純な形状とキーフレームによる動きで構成された、編集できるアニメーション付きのクレイ調シーンです。プロンプトと、任意のリファレンスから作成されます。言葉による指示か正確な操作で修正し、MP4 にレンダリングします。

### 3D シーンのレンダリングは何に使えますか？

動画モデルのレイアウトと動きのガイドとして使えます。レンダリングをリファレンス動画として generate_video に渡します。その際、レイアウトのガイドであることを示すキャプションを付け、見た目のリファレンスも一緒に渡します。

### 3D シーンのレンダリングには何クレジットかかりますか？

長辺が 1920 ピクセルまでのフレームは 50 クレジット、それを超えて 5.12 メガピクセルまでは 75 クレジット、それより大きいフレームは 125 クレジットです。2560×2560 のシーンは、1920×1080 のシーンの 2.5 倍の料金です。

### シーンのジョブが、レビューの警告付きで完了しました。壊れているのですか？

いいえ。ジョブは完了しており、シーンは使えます。metadata.review は、ビジュアルレビューがシーンを承認しなかったことを示します。判定が refused の場合はレビューが異議を示したこと、unavailable の場合は誰もシーンを評価していないことを意味します。

### シーンのジョブが失敗しました。もう一度実行すべきですか？

先に出力を確認してください。アドバンスエンジンの失敗したジョブにも、編集やレンダリングができる下書きのシーンや、拒否されたレシピが残っていることがあります。同じプロンプトをもう一度実行すると、同じシーン作成の料金を 2 回払うことになります。