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 and Edit 3D Scene nodes on the canvas.

The tools

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.

The loop

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:

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

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