# 3D scenes

> Create an editable 3D clay scene from a prompt, revise it, render it to MP4 and use the render as a layout and motion guide for a video model.

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

A **3D scene** is an editable, animated clay scene: simple geometry with keyframed motion, authored from a prompt and optional image or video references. From an AI assistant you create it, revise it with words or exact operations, render it to MP4, and use the render as a layout and motion guide for a video model. The MCP tools do the same work as the [Generate 3D Scene](https://nodaro.ai/docs/nodes/video/generate-3d-scene) and [Edit 3D Scene](https://nodaro.ai/docs/nodes/video/edit-3d-scene) nodes on the canvas.

## The tools

| Tool | What it does |
| --- | --- |
| `generate_3d_scene` | A prompt and optional references become an editable scene |
| `edit_3d_scene` | A scene revision and an instruction or operations become a new revision |
| `render_3d_scene` | An exact scene revision becomes an MP4, through the Render Video engine |
| `pro_3d_render` | One job that authors, revises or exports a scene and returns the scene plan, the MP4 and one still per shot, on deployments that have its engine |

Each tool needs `workflows:execute` and returns a job id; read the result with `get_job` or `wait_for_job`. A scene job returns `output_data.scenePlan`, and a render returns a video URL. The parameters are in the [tools reference](https://nodaro.ai/docs/mcp/tools/3d-scenes).

## The loop

### Generate the scene

Call `generate_3d_scene` with a description of the shot, `duration_seconds`, `fps` and `aspect_ratio`. References are `{ id, url, kind, role }`: an image or a video, used for appearance, layout or motion.

### Revise it

Read `scenePlan` from the completed job. Call `edit_3d_scene` with that object as `scene_plan`, its `revisionId` as `expected_revision_id`, and either an edit `prompt` or `operations`. List objects that must not change in `locked_object_ids`.

### Render it

Call `render_3d_scene` with the resulting `scene_plan`. No LLM runs.

### Use the render as a guide

Pass the MP4 to [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video) in `reference_video_urls`, and say what it is for in `reference_video_captions` at the same position. Keep passing your appearance images as references too.

A clay render is a layout guide, not a look. Without a caption, the video model may also copy the grey clay appearance.

## What the first version can do

- **Geometry and motion.** Scenes use primitive shapes and deterministic keyframed animation.
- **References are approximate.** A scene rebuilt from a reference is an approximation of it.
- **Whole video references.** A video reference is used whole. To use a segment, trim the clip first and pass the trimmed URL; a partial time window is refused before any authoring is charged.
- **Operations are free of LLM calls.** Edits with `operations` apply directly. So does the render.

## Engines

`generate_3d_scene` and `edit_3d_scene` accept an `engine`: `basic` (the default), `blender-cloud` or `blender-local`. An advanced engine must be available on the deployment; an unavailable one is refused and never falls back to `basic`. The advanced engines use a fixed planner, so leave `llm_model` and `reasoning_effort` out there, and set their correction budget with `max_repair_passes`.

With an advanced engine that can import them, `generate_3d_scene` also takes `input_assets`: up to eight existing 3D models (GLB), each `{ id, revisionId, assetId, label }`. Keep images and videos in `references`. Imports are refused before any charge when the engine cannot import, and the server resolves the files itself, so never send URLs or hashes.

## What a render costs

A render is priced by the frame size in the plan you pass:

| Frame | Credits |
| --- | --- |
| Up to 1920 pixels on the longest side | 50 |
| Above that, up to 5.12 megapixels | 75 |
| Larger | 125 |

Set `width` and `height` in the scene plan on purpose: a 2560 by 2560 scene costs 2.5 times a 1920 by 1080 one, while 1920 by 1920 costs the same as 1920 by 1080. [Render Video](https://nodaro.ai/docs/nodes/video/render-video) has the full table.

## Read an advanced engine's result

A scene authored by an advanced engine reports what it assumed and did. All of these fields are optional, and the `basic` engine reports none of them.

| Field | What it reports |
| --- | --- |
| `validation.warnings[]` with `SCENE_AUTHORING_ASSUMPTION` | The planner's assumptions |
| `metadata.summary` | The engine's own description of what it authored |
| `repairPasses` | Repairs that ran; `0` when the scene was accepted the first time |
| `admissionRetries` | Planner retries before the build, which spend no repair pass |
| `mechanicalPasses` | Repairs the engine applied from the compiler's own fix, without a planner call, each with a `REMEDY_AUTO_APPLIED` warning. They are counted apart from `repairPasses`, on their own quoted allowance. |
| `restoredAssertions` | Required checks the engine put back after an answer changed one, each with an `ASSERTION_RESTORED` warning |

A render-only export authors nothing, so it reports no summary and leaves the counts out.

### When a completed scene was not approved

A completed job can carry `metadata.review`, which means the scene was delivered without the visual review's approval. Check for the presence of `metadata.review`, not the status or the warning count, and read its `verdict` before you tell the user anything:

- **`refused`**: the repair budget was spent, every required check passed, and the review still objected. The scene comes with the objections and one `SCENE_REVIEW_REFUSED` warning per objection.
- **`unavailable`**: the review gave no usable verdict in `attempts` tries. `reason` is `provider` when the review never reached its model and `unusable` when the answer was unusable. Nobody judged the scene, and `validation.warnings[]` starts with `SCENE_REVIEW_UNAVAILABLE`. Do not report a refusal for a scene that nobody reviewed.

`validation.status` is still `passed` in both cases, and the objection list may be empty.

### When an advanced job failed

A job that failed with `SCENE_QUALITY_FAILED` spent its budget without a scene it could stand behind. Read its `output_data` before you run it again:

- **A draft was built.** The failed job points to it with `scenePlan`, `sceneRevisionId`, `deliveryId` and `posterAssetId`, and `validation.status` is `failed`. The draft is an ordinary revision: pass it to `edit_3d_scene` or `render_3d_scene`.
- **Nothing compiled.** There is no `scenePlan`, but the job still has a `deliveryId`, and `validation.sourceRetained` says whether the recipe was kept. Fetch it from the REST API with `GET /v1/3d-scene/deliveries/{deliveryId}`, then its `source-json` asset. Reading it costs no credits and needs your own credentials and edit access to the job's workflow; there is no MCP tool for it.

Running the identical prompt again pays for the same authoring twice.

## 3D Render Pro

[`pro_3d_render`](https://nodaro.ai/docs/mcp/tools/3d-scenes#pro_3d_render) is a separate operation, not an option of `generate_3d_scene`. One job produces a finished shot: its completed output carries both `scenePlan` and `videoUrl`, with the revision, a poster, the validation and the renderer details. The tool appears only on deployments with an engine that implements it, so its presence in the tool list is the availability check. It works like the [3D Render Pro](https://nodaro.ai/docs/nodes/video/pro-3d-render) node.

The output also carries `shotStills`, one still per shot of the composition, in shot order: `{ shotIndex, frame, assetId, url }`. `shotIndex` counts from 0 and `frame` is the shot's first frame, so a still lines up with the MP4. A single-shot scene has exactly one, at frame 0. They come from the same run at no extra cost. Use a shot's still as the image reference when you generate that shot with a video model.

Each still's `url` is an authenticated address on the install, because delivery files are private. Fetch it with your own credentials; it is not a public link. You can still pass it to `generate_image` or `generate_video`: that run gets a short-lived permission to read that one file. The permission lasts minutes and is not stored, so keep the authenticated URL in anything you save.

Use `generate_3d_scene`, `edit_3d_scene` and `render_3d_scene` for the cheaper, editable clay previz. For the exact scene format and the current defaults, ask the assistant to call `get_node_skill` with `generate-3d-scene` or `edit-3d-scene`.

## Frequently asked questions

### What is a 3D scene in Nodaro?

An editable, animated clay scene made of simple geometry with keyframed motion, authored from a prompt and optional references. You revise it with words or exact operations and render it to MP4.

### What is a 3D scene render good for?

As a layout and motion guide for a video model. Pass the render to generate_video as a reference video, with a caption that says it is a layout guide, together with your appearance references.

### How much does a 3D scene render cost?

50 credits for a frame up to 1920 pixels on its longest side, 75 above that up to 5.12 megapixels, and 125 for a larger frame. A 2560 by 2560 scene costs 2.5 times a 1920 by 1080 one.

### A scene job completed with a review warning. Is it broken?

No, the job completed and the scene is usable. metadata.review says the visual review did not approve it. The verdict refused means the review objected; unavailable means nobody judged the scene.

### A scene job failed. Should I run it again?

Read its output first. A failed job from an advanced engine can still carry a draft scene you can edit or render, or the recipe it was refused for. Running the same prompt again pays for the same authoring twice.