# 3D scenes

> Parameters of the four 3D scene tools that author an editable clay scene from a prompt, revise it, render it to MP4, or produce a finished shot in one job.

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

The **3D scene tools** create editable, animated clay scenes with simple geometry and keyframed motion, revise them, and render them to video. A render then serves as a layout and motion guide for a video model. This page lists each tool's parameters; [3D scenes](https://nodaro.ai/docs/mcp/3d-scenes) explains the loop and how to read the results.

Every tool needs the `workflows:execute` permission and returns a job id. Read the result with `get_job` or `wait_for_job`.

## `generate_3d_scene`

Creates an editable, animated clay scene from a prompt and optional references. It does not make a photorealistic video. It works like the [Generate 3D Scene](https://nodaro.ai/docs/nodes/video/generate-3d-scene) node.

**Permission:** `workflows:execute`. **Credits:** as the Generate 3D Scene node, from 10 to 40.

| Parameter | Type | Notes |
| --- | --- | --- |
| `prompt` | string | **Required.** The shot, up to 8,000 characters. |
| `duration_seconds` | number | From 1 to 60. |
| `fps` | integer | From 15 to 60. |
| `aspect_ratio` | string | The frame shape. |
| `references` | array | Up to 8 references, at most one video, each `{ id, url, kind, role }`. `kind` is `image` or `video`. `role` is `appearance`, `layout` or `motion`: images guide the look and the layout, a video guides the layout and the motion. A video reference is used whole; trim it first to use a segment. |
| `input_assets` | array | Up to 8 existing 3D models (GLB), each `{ id, revisionId, assetId, label }`. Needs an advanced engine that can import them; otherwise the call is refused before any charge. Never send URLs. |
| `engine` | string | `basic` (default), `blender-cloud` or `blender-local`. An engine the deployment does not have is refused; it never falls back to `basic`. |
| `max_repair_passes` | integer | The correction budget of an advanced engine, from 0 to 2. |
| `llm_model`, `reasoning_effort` | string | The planner for the `basic` engine. Leave them out on an advanced engine, which uses a fixed planner. |
| `local_connection_id` | string | The paired desktop connection, for `blender-local`. |
| `accepted_scene_schema_versions` | array | The scene format versions your client accepts. |

**Returns:** a job id. The completed job's `output_data.scenePlan` is the scene, with its `revisionId`.

## `edit_3d_scene`

Revises a scene and keeps its earlier revision. Send either a prompt, which the planner applies, or operations, which apply directly without an LLM call. It works like the [Edit 3D Scene](https://nodaro.ai/docs/nodes/video/edit-3d-scene) node.

**Permission:** `workflows:execute`. **Credits:** as the Edit 3D Scene node, from 0 to 40.

| Parameter | Type | Notes |
| --- | --- | --- |
| `scene_plan` | object | **Required.** The whole `scenePlan` from a scene job. |
| `expected_revision_id` | string | **Required.** The plan's `revisionId`. The edit is refused if it does not match. |
| `prompt` | string | The change, in words, up to 8,000 characters. |
| `operations` | array | 1 to 100 exact changes: `set-object`, `add-object`, `remove-object`, `set-camera`, `set-lighting` or `set-background`. |
| `locked_object_ids` | array | Objects the edit must not change. |
| `selected_object_ids` | array | Objects the edit is about. |
| `references` | array | As on `generate_3d_scene`. |
| `replace_references` | boolean | Replaces the scene's image and video references with `references`. |
| `engine`, `max_repair_passes`, `llm_model`, `reasoning_effort`, `local_connection_id`, `accepted_scene_schema_versions` | | As on `generate_3d_scene`. |

**Returns:** a job id. The completed job's `output_data` holds the new `scenePlan` and a `changeSummary`. An MP4 alone is not an editable scene: to rebuild a scene from a video, use `generate_3d_scene` with the video as a reference.

## `render_3d_scene`

Renders an exact scene revision to MP4 with the Render Video engine. No LLM runs. The camera, the duration and the frame come from the scene plan.

**Permission:** `workflows:execute`. **Credits:** by the frame size in the plan: 50 up to 1920 pixels on the longest side, 75 above that up to 5.12 megapixels, and 125 for a larger frame.

| Parameter | Type | Notes |
| --- | --- | --- |
| `scene_plan` | object | **Required.** The scene plan to render. |

**Returns:** a job id. The result is a video URL. Set `width` and `height` in the 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 price table.

## `pro_3d_render`

Produces a finished 3D shot in one job: the completed job carries the scene plan, the MP4 and one still per shot. It appears in the tool list only on deployments that have an engine for it. It works like the [3D Render Pro](https://nodaro.ai/docs/nodes/video/pro-3d-render) node.

**Permission:** `workflows:execute`. **Credits:** quoted and charged in the same call. Authoring and each repair pass are paid work; a plain export of an existing scene costs no authoring.

| Parameter | Type | Notes |
| --- | --- | --- |
| `source` | object | **Required.** Exactly one of the three sources below. |
| `duration_seconds`, `fps` | number | From 1 to 60 seconds, and 15 to 60 fps. Leave them out for a scene source unless you mean to re-time it; a conflicting value is refused. |
| `aspect_ratio` | string | `16:9`, `9:16`, `1:1`, `4:5` or `21:9`. Leave it out for a scene source. |
| `max_repair_passes` | integer | The correction budget, from 0 to 2. Default `2`. Each pass is paid. |
| `engine` | string | `blender-cloud` or `blender-local`. |
| `quality`, `style` | string | `standard` and `clay`. |
| `client_request_id` | string | A retry token. Reuse it if you retry after a timeout, so the job is not started or charged twice. |

| `source.kind` | Fields | What it does |
| --- | --- | --- |
| `prompt` | `prompt`, and optional `references` and `input_assets` | Authors a new scene from a brief, then renders it. |
| `scene` | `revision_id`, optional `source_job_id` and optional `edit_prompt` | Renders an existing revision. Without `edit_prompt`, it is a plain export. With it, the scene is revised first, which costs authoring. `source_job_id` is required for `basic` scenes kept only in job history. |
| `local-export` | `export_id`, `connection_id` | Uses a finished export from a paired desktop app, where available. |

**Returns:** a job id. The completed job's `output_data` carries `scenePlan`, `videoUrl` and `shotStills`, one still per shot, each `{ shotIndex, frame, assetId, url }`. There is no model or reasoning parameter: the planner is fixed.

## Frequently asked questions

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

A render is priced by the frame size in the scene plan. 50 credits up to 1920 pixels on the longest side, 75 above that up to 5.12 megapixels, and 125 for a larger frame.

### Does editing a 3D scene always call an AI model?

No. An edit with operations, such as moving an object or changing the camera, applies them directly without an LLM call. An edit with a prompt asks the planner to make the change.

### What is the difference between render_3d_scene and pro_3d_render?

render_3d_scene exports an existing scene revision to MP4. pro_3d_render is one job that can author, revise or export a scene and returns the scene plan, the MP4 and one still per shot, on deployments that have its engine.