3D scenes

The 3D scenes API creates editable, animated clay scenes from a prompt and optional image or video references, edits them, and renders them to MP4. The result of a generation is a scene plan, not a video. It holds the objects, their motion, the camera and the lighting, so you can check the framing, the camera move and the blocking before you render. A render is then a layout reference for a video model.

3D Render Pro is a separate operation that authors and renders a finished shot in one paid job, where the deployment has an engine for it. The Basic authoring engine works on every edition; Advanced engines and 3D Render Pro depend on the deployment, so check its capabilities first. Credits apply on Nodaro Cloud only. The routes take a bearer token. See Authentication.

Endpoints

POST /v1/generate-3d-scene and POST /v1/edit-3d-scene are aliases of the generate and edit routes, with the same checks and credits. POST /v1/render-video also accepts planType and plan. These aliases let the generic node runner of the SDK reach the same routes.

Check what the deployment supports

GET /v1/3d-scene/capabilities reports Basic support and an advanced block, which is null when no Advanced engine is available. A pro block says whether 3D Render Pro is available, and lists the engines, quality profiles, styles, aspect ratios and repair ceiling you may offer. Build your controls from it, not from the full vocabulary.

An engine you request that the deployment cannot serve answers 503 SCENE_CAPABILITY_UNAVAILABLE before any credit check. Nodaro never falls back to Basic authoring on its own. GET /v1/nodes also omits the 3D Render Pro node where it is unavailable, and advertises the scene3d-embed-v1 capability on the generate node when the interactive 3D preview embed is available.

Generate a scene

POST /v1/3d-scene/generate authors a new scene and returns { jobId }. Poll the job with the Jobs API; the completed job's output_data.scenePlan is the editable scene.

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

• References are approximate. An image does not reveal geometry it does not show, and a video is read as a guide for movement and layout. Check the preview before you render.
• Whole clips only. A video reference is analyzed in full. To use part of a clip, trim it first with Trim Video; a partial time window is refused before any credit is spent.
• Stored geometry. inputAssets picks exact revisions of GLB files you already have. The server checks your access and the file's digest itself, so do not send URLs or hashes, and keep images and videos in references. Basic refuses imported geometry before charging.
• Coordinates. Scenes use meters, with Y pointing up, rotations in radians and frames counted from zero.

Edit a scene

POST /v1/3d-scene/edit takes the scenePlan, its revisionId as expectedRevisionId, and either a prompt (an instruction such as "move the pillar back one meter") or operations. A successful edit produces a new revision whose parentRevisionId is the old one; the plan you sent stays unchanged. A revision mismatch is refused. The completed job returns scenePlan and 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 } }],
})

Send lockedObjectIds to keep objects unchanged during an instruction edit. New references merge with the existing ones by id; the same id replaces a reference, and the total must stay within the generation limits. The whole edited scene is validated, so an edit cannot leave an orphaned parent or reference.

Operations call no language model and cost 0 credits. An instruction edit uses the same tiers as authoring. Keep the previous revision to undo or compare.

Save edits to a stored scene

For a stored version-2 scene, POST /v1/3d-scene/revisions/:revisionId/edits saves deterministic edits (transforms, material colors, visibility and camera offsets) without a job and without a language-model charge. Send newRevisionId, the base revision's expectedContentHash, the operations and, optionally, lockedObjectIds. The route returns { scenePlan, changeSummary }.

A stale digest or a conflicting revision id answers 409. When a request fails in transit, retry with the same newRevisionId and the same body. The route needs edit access to the scene, and OAuth app tokens need workflows:write. The new revision is saved on its own; select it in your workflow yourself, after checking that nobody changed the active revision meanwhile.

Render a scene to MP4

POST /v1/render-video/plan with { "planType": "3d-scene", "plan": scenePlan } renders one exact revision. The camera, the frame size, the frame rate and the duration come from the plan; no language model is called and the prompt is not read again. The completed job returns videoUrl, thumbnailUrl, sceneRevisionId and 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,
})

A render is priced by the plan's own width and height:

Every aspect ratio the generate route offers renders at 1920 px or less, so a scene you did not resize always costs the base price. The larger tiers apply only when you set a larger width and height on the plan yourself. The model-cost identifiers are render-video, render-video:3d-large and render-video:3d-xlarge.

Use a render as a video reference

A clay render carries the layout: where the subjects are, what is in front of what, the framing, the camera move and the timing. It also carries a look, untextured grey clay, and a video model copies that look unless told not to. Two rules keep the layout and drop the clay:

1. Always scope the reference. Pass the MP4 in referenceVideoUrls[N] on Generate Video, with a caption in referenceVideoCaptions[N] that says what to match and what to ignore. In a workflow, Nodaro adds this caption for you. Its wording is: "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. Give every real-looking figure its own character reference. A figure without one stays a clay proxy. Keep two reference slots free for a location or a style image.

Also send the original appearance images, and never use the render as the start frame: a start frame fixes the look, and no caption reaches it.

Run 3D Render Pro

3D Render Pro authors a scene and exports it in one durable job, on a hosted build engine. One run settles with both the exact composition and the MP4. Its price is set by the deployment, so the quote is the authority.

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)
}

The body's source is exactly one of:

There is no model field: the planner is fixed. For a scene source, omit the timing fields to keep the scene's own; sending them re-times the scene, and an incompatible value is refused. A prompt source produces a version-2 scene, so a client that does not accept version 2 is refused for free.

What a finished run returns

Each still's url is an authenticated endpoint on the deployment, not a public link: fetch it with your own token. You can still pass it as an image reference to a generation, and Nodaro grants that run a short-lived read of that one file.

Test for metadata.review itself, then read its verdict. refused means the reviewer still objected after the repair budget was spent, and objections lists what it found. unavailable means the review gave no usable answer, so nobody judged the scene. In both cases validation.status is still passed, because the mandatory checks did pass. Warning codes are open-ended; treat a code you do not know as information. See 3D Render Pro for every field and warning code.

When a run fails

Errors on the submission are refusals: 503 SCENE_CAPABILITY_UNAVAILABLE, 503 price_not_configured (the operator has not set a price; nothing was reserved) and 400 validation_error. Failures during the run are on the job, and the error message starts with the code:

A failed Advanced job can still carry what it built. When a pass built a scene, output_data holds the draft: scenePlan, sceneRevisionId, deliveryId, posterAssetId, and validation with status: "failed". The draft is an ordinary revision you can edit or render. When no pass compiled, there is no draft, but validation.sourceRetained says whether the refused recipe was kept; read it from the delivery's source-json descriptor with edit access, for free. Re-running the same prompt instead pays for the same authoring twice.

In a workflow run, a failed node that kept a result also carries it in nodeStates[nodeId].output. Check for the field, not the status, and never read a present output as success.

Scene versions and stored assets

A scene plan is a union of two versions. Read schemaVersion before any version-specific field.

A version-2 plan lists each asset by an opaque assetId, its byte length and its SHA-256 digest; it never contains a storage key or a download URL. Version 2 accepts clay geometry with rigid animation; textured, skinned and morphing assets are refused. Its limits are 100 entities, 2,000 mesh nodes, 200,000 triangles, 32 shots and 64 MiB of playback assets. See Scene plan format for the full format.

Stored revisions have their own routes. They need a bearer token, answer with Cache-Control: no-store, and return 404 for a deleted or unreachable revision:

• GET /v1/3d-scene/revisions/:revisionId returns the manifest and the asset descriptors. Playback assets need view access to the revision's workflow; the native source needs edit access. Personal revisions are owner-only.
• GET /v1/3d-scene/deliveries/:jobId returns what an export delivered: sourceKind, the exact sceneRevisionId, the source digests and the descriptors (the poster, the validation report and one shot-still per shot). …/assets/:assetId returns the bytes, with range support. Reads need access to both the delivery and the source workflow, and they cost nothing.

In the SDK, client.scene3d.getDelivery, deliveryAssetBytes, retainedRecipe, assetBytes, sourceBytes and applyEdits wrap these routes.

Use it from MCP

AI assistants use generate_3d_scene, edit_3d_scene and render_3d_scene with the workflows:execute scope, and pro_3d_render where the deployment can serve it. See 3D scenes over MCP. To show a scene in your own page, see the 3D preview embed.

Errors