# Cenas 3D

> Gere, edite e renderize cenas 3D editáveis em massinha via REST, faça a cotação e execute a Renderização 3D Pro e leia revisões, arquivos e entregas.

Source: https://nodaro.ai/pt-BR/docs/developers/api/3d-scenes

A **API de cenas 3D** cria cenas animadas e editáveis em massinha a partir de um prompt e de referências opcionais de imagem ou de vídeo, edita essas cenas e as renderiza em MP4. O resultado de uma geração é um **plano de cena**, não um vídeo. Ele guarda os objetos, o movimento deles, a câmera e a iluminação, para que você confira o enquadramento, o movimento de câmera e a marcação antes de renderizar. Uma renderização é, então, uma referência de layout para um modelo de vídeo.

A **Renderização 3D Pro** (3D Render Pro) é uma operação separada que cria e renderiza uma tomada pronta em um único job pago, onde a implantação tem um mecanismo para isso. O mecanismo de criação básico funciona em todas as edições. Os mecanismos avançados e a Renderização 3D Pro dependem da implantação, então verifique primeiro os recursos dela. Os créditos só se aplicam no Nodaro Cloud. As rotas aceitam um token Bearer. Veja [Autenticação](https://nodaro.ai/docs/developers/api/authentication).

## Endpoints
| Método | Caminho | O que faz |
| --- | --- | --- |
| `GET` | `/v1/3d-scene/capabilities` | O que esta implantação aceita: o mecanismo básico, os mecanismos avançados e a Renderização 3D Pro. |
| `POST` | `/v1/3d-scene/generate` | Cria uma nova cena a partir de um prompt. Retorna `{ jobId }`. |
| `POST` | `/v1/3d-scene/edit` | Cria uma nova revisão de uma cena, a partir de uma instrução ou de operações. Retorna `{ jobId }`. |
| `POST` | `/v1/render-video/plan` | Renderiza uma revisão de cena em MP4. |
| `POST` | `/v1/pro-3d-render/quote` | Faz a cotação de uma execução da Renderização 3D Pro. Não reserva nada. |
| `POST` | `/v1/pro-3d-render` | Executa o job cotado da Renderização 3D Pro. |
| `POST` | `/v1/3d-scene/revisions/:revisionId/edits` | Salva edições determinísticas em uma cena armazenada, sem job. |
| `GET` | `/v1/3d-scene/revisions/:revisionId` | O manifesto da cena e os descritores dos arquivos de uma revisão armazenada. |
| `GET` | `/v1/3d-scene/revisions/:revisionId/assets/:assetId` | Um arquivo de reprodução de uma revisão, como um GLB ou a trilha da câmera. |
| `GET` | `/v1/3d-scene/revisions/:revisionId/source` | A fonte nativa editável de uma revisão, quando ela foi mantida. |
| `GET` | `/v1/3d-scene/deliveries/:jobId` | O que uma exportação entregou: a revisão de origem, os digests e os descritores. |
| `GET` | `/v1/3d-scene/deliveries/:jobId/assets/:assetId` | Os bytes de um arquivo entregue. |

`POST /v1/generate-3d-scene` e `POST /v1/edit-3d-scene` são aliases das rotas de geração e de edição, com as mesmas verificações e os mesmos créditos. `POST /v1/render-video` também aceita `planType` e `plan`. Esses aliases permitem que o executor genérico de nós do SDK chegue às mesmas rotas.

## Verificar o que a implantação aceita
`GET /v1/3d-scene/capabilities` informa o suporte ao mecanismo básico e um bloco `advanced`, que é `null` quando nenhum mecanismo avançado está disponível. Um bloco `pro` diz se a Renderização 3D Pro está `available` e lista os mecanismos, os perfis de qualidade, os estilos, as proporções e o teto de correções que você pode oferecer. Monte os seus controles a partir dele, não do vocabulário completo.

Um mecanismo solicitado que a implantação não consegue atender responde `503 SCENE_CAPABILITY_UNAVAILABLE` antes de qualquer verificação de créditos. O Nodaro nunca volta para a criação básica por conta própria. `GET /v1/nodes` também omite o nó Renderização 3D Pro onde ele não está disponível e anuncia o recurso `scene3d-embed-v1` no nó de geração quando a [incorporação interativa da prévia 3D](https://nodaro.ai/docs/developers/embed/scene3d) está disponível.

## Gerar uma cena
`POST /v1/3d-scene/generate` cria uma nova cena e retorna `{ jobId }`. Consulte o job periodicamente com a [API de jobs](https://nodaro.ai/docs/developers/api/jobs); o `output_data.scenePlan` do job concluído é a cena editável.

**curl**

```bash
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" }
]
}'
```

**TypeScript SDK**

```ts

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 }],
})
```

**CLI**

```bash
nodaro nodes run generate-3d-scene --params-file scene.json --watch --json
```

<TypeTable
type={{
prompt: { type: 'string', description: 'Os objetos, o movimento deles, o posicionamento e o movimento da câmera, e o tempo.', required: true },
references: { type: 'array', description: 'Até 8 referências, no máximo 1 delas um vídeo: { id, url, kind, role, objectId? }. kind é image ou video; role é appearance, layout ou motion.' },
inputAssets: { type: 'array', description: 'Até 8 arquivos GLB armazenados: { id, revisionId, assetId, label? }. Exige um mecanismo avançado com suporte a importação.' },
durationSeconds: { type: 'number', description: 'A duração da cena, de 1 a 60 segundos.', default: '4' },
fps: { type: 'number', description: 'Quadros por segundo, de 15 a 60.', default: '24' },
aspectRatio: { type: "'16:9' | '9:16' | '1:1' | '4:5'", description: 'O quadro.', default: '16:9' },
engine: { type: "'basic' | 'blender-cloud' | 'blender-local'", description: 'O mecanismo de criação. Os mecanismos avançados precisam estar disponíveis na implantação.', default: 'basic' },
llmModel: { type: 'string', description: 'Só no mecanismo básico: o modelo de linguagem que escreve a cena. Define o nível de créditos.' },
reasoningEffort: { type: 'string', description: 'Só no mecanismo básico: quanto tempo o modelo pensa. Um esforço alto pode aumentar o nível.' },
acceptedSceneSchemaVersions: { type: 'number[]', description: 'As versões de plano de cena que o seu cliente consegue ler, por exemplo [1, 2].' },
maxRepairPasses: { type: 'number', description: 'Mecanismos avançados: quantas passadas de correção a execução pode gastar.' },
}}
/>

- **As referências são aproximadas.** Uma imagem não revela a geometria que não mostra, e um vídeo é lido como um guia de movimento e de layout. Confira a prévia antes de renderizar.
- **Só clipes inteiros.** Uma referência em vídeo é analisada por completo. Para usar parte de um clipe, corte o clipe antes com o [**Cortar vídeo** (Trim Video)](https://nodaro.ai/docs/nodes/video/trim-video); uma janela de tempo parcial é recusada antes de qualquer crédito ser gasto.
- **Geometria armazenada.** `inputAssets` escolhe revisões exatas de arquivos GLB que você já tem. O próprio servidor verifica o seu acesso e o digest do arquivo, então não envie URLs nem hashes, e mantenha imagens e vídeos em `references`. O mecanismo básico recusa geometria importada antes de cobrar.
- **Coordenadas.** As cenas usam metros, com Y apontando para cima, rotações em radianos e quadros contados a partir de zero.

## Editar uma cena
`POST /v1/3d-scene/edit` recebe o `scenePlan`, o `revisionId` dele como `expectedRevisionId` e um `prompt` (uma instrução como “move the pillar back one meter”) ou `operations`. Uma edição bem-sucedida produz uma nova revisão cujo `parentRevisionId` é a antiga; o plano que você enviou continua igual. Uma revisão divergente é recusada. O job concluído retorna `scenePlan` e `changeSummary`.

**curl**

```bash
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 } }] }
```

**TypeScript SDK**

```ts
const edited = await client.nodes.runAndWait('edit-3d-scene', {
scenePlan: scene.scenePlan,
expectedRevisionId: scene.scenePlan.revisionId,
operations: [{ op: 'set-camera', changes: { focalLengthMm: 50 } }],
})
```

| Operação | Campos | O que muda |
| --- | --- | --- |
| `set-object` | `objectId`, `changes` | Qualquer campo de um objeto, exceto o ID. Para mudar uma pose com quadros-chave, inclua as mudanças nos quadros-chave dela. |
| `add-object` | `object` | Adiciona um objeto. |
| `remove-object` | `objectId` | Remove um objeto. |
| `set-camera` | `changes` | A câmera, por exemplo a distância focal. |
| `set-lighting` | `changes` | A iluminação. |
| `set-background` | `color` | A cor de fundo. |

Envie `lockedObjectIds` para manter objetos inalterados durante uma edição por instrução. As novas `references` se mesclam às existentes pelo ID; o mesmo ID substitui uma referência, e o total precisa ficar dentro dos limites da geração. A cena editada inteira é validada, então uma edição não pode deixar um pai ou uma referência órfãos.

As operações não chamam nenhum modelo de linguagem e custam 0 créditos. Uma edição por instrução usa os mesmos níveis da criação. Guarde a revisão anterior para desfazer ou comparar.

### Salvar edições em uma cena armazenada
Para uma cena armazenada na versão 2, `POST /v1/3d-scene/revisions/:revisionId/edits` salva edições determinísticas (transformações, cores de materiais, visibilidade e deslocamentos da câmera) sem job e sem cobrança de modelo de linguagem. Envie `newRevisionId`, o `expectedContentHash` da revisão base, as `operations` e, opcionalmente, `lockedObjectIds`. A rota retorna `{ scenePlan, changeSummary }`.

Um digest desatualizado ou um ID de revisão em conflito responde `409`. Quando uma requisição falha no caminho, tente de novo com o mesmo `newRevisionId` e o mesmo corpo. A rota exige acesso de edição à cena, e os tokens de app OAuth precisam de `workflows:write`. A nova revisão é salva separadamente. Selecione-a você mesmo no seu workflow, depois de verificar que ninguém mudou a revisão ativa nesse meio-tempo.

## Renderizar uma cena em MP4
`POST /v1/render-video/plan` com `{ "planType": "3d-scene", "plan": scenePlan }` renderiza uma revisão exata. A câmera, o tamanho do quadro, a taxa de quadros e a duração vêm do plano; nenhum modelo de linguagem é chamado, e o prompt não é lido de novo. O job concluído retorna `videoUrl`, `thumbnailUrl`, `sceneRevisionId` e `renderer: "scene3d/three"`.

**curl**

```bash
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) }"
```

**TypeScript SDK**

```ts
const clip = await client.nodes.runAndWait('render-video', {
planType: '3d-scene',
plan: edited.scenePlan,
})
```

O preço de uma renderização depende de `width` e `height` do próprio plano:

| Quadro | Preço no Nodaro Cloud | Exemplos |
| --- | --- | --- |
| Lado mais longo com 1920 px ou menos, qualquer formato | 55 créditos | 1920x1080, 1080x1920, 1920x1920 |
| Mais de 1920 px, até 5,12 megapixels | 83 créditos | 2560x1440, 1440x2560 |
| Mais de 1920 px, acima de 5,12 megapixels | 138 créditos | 2048x2560, 2560x2560 |

Todas as proporções que a rota de geração oferece são renderizadas em 1920 px ou menos, então uma cena que você não redimensionou sempre custa o preço básico. Os níveis maiores só se aplicam quando você mesmo define `width` e `height` maiores no plano. Os identificadores de custo de modelo são `render-video`, `render-video:3d-large` e `render-video:3d-xlarge`.

## Usar uma renderização como referência de vídeo
Uma renderização em massinha traz o layout: onde ficam os elementos, o que está na frente do quê, o enquadramento, o movimento de câmera e o tempo. Ela também traz uma aparência, a de massinha cinza sem textura, e um modelo de vídeo copia essa aparência, a menos que seja instruído a não fazer isso. Duas regras mantêm o layout e descartam a massinha:

1. **Sempre delimite a referência.** Envie o MP4 em `referenceVideoUrls[N]` no [**Gerar vídeo** (Generate Video)](https://nodaro.ai/docs/nodes/video/generate-video), com uma legenda em `referenceVideoCaptions[N]` que diga o que copiar e o que ignorar. Em um workflow, o Nodaro adiciona essa legenda por você. O texto dela é: “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. **Dê a cada figura de aparência real a própria referência de personagem.** Uma figura sem referência continua um substituto de massinha. Deixe dois espaços de referência livres para um local ou uma imagem de estilo.

Envie também as imagens de aparência originais e nunca use a renderização como quadro inicial: um quadro inicial fixa a aparência, e nenhuma legenda chega até ele.

## Executar a Renderização 3D Pro
A Renderização 3D Pro cria uma cena e a exporta em um único job durável, em um mecanismo de build hospedado. Uma execução termina com a composição exata e com o MP4. O preço é definido pela implantação, então a cotação é a referência.

### Cotação
`POST /v1/pro-3d-render/quote` retorna `{ quoteId, expiresAt, maxCredits, breakdown, pricingVersion, capabilitiesVersion, normalizedInputHash }`. A rota não reserva nada. `maxCredits` é um teto, não uma cobrança.

### Execução
`POST /v1/pro-3d-render` recebe o mesmo corpo mais o `quoteId` e um cabeçalho `Idempotency-Key` de 8 a 255 caracteres. A rota retorna `{ jobId }`. Um corpo alterado depois da cotação, ou uma cotação expirada, é recusado antes de qualquer reserva. Reutilize a mesma chave quando tentar de novo uma requisição que excedeu o tempo limite, para que uma intenção nunca vire duas execuções pagas.

**curl**

```bash
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
```

**TypeScript SDK**

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

O `source` do corpo é exatamente um destes:

| `source` | O que acontece |
| --- | --- |
| `{ kind: "prompt", prompt, references?, inputAssets? }` | Cria uma nova cena e depois a renderiza. |
| `{ kind: "scene", revisionId, sourceJobId }` | Só renderiza essa revisão exata, sem cobrança de criação nem de build. `sourceJobId` é obrigatório para cenas do mecanismo básico guardadas só no histórico de jobs. |
| `{ kind: "scene", revisionId, sourceJobId, editPrompt }` | Revisa a cena primeiro e depois a renderiza. Omita `editPrompt` para uma exportação simples: uma string vazia é uma requisição diferente. |
| `{ kind: "local-export", exportId, connectionId }` | Usa uma exportação concluída de um app de desktop pareado, onde isso está disponível. |

| Campo | O que faz |
| --- | --- |
| `engine` | `blender-cloud` (o padrão) ou `blender-local`, onde há um desktop pareado. |
| `localConnectionId` | O desktop pareado, para `blender-local`. |
| `quality`, `style` | Um perfil de qualidade e o estilo, `clay`. |
| `maxRepairPasses` | De 0 a 2; o padrão é 2. Cada passada é um trabalho pago. |
| `durationSeconds`, `fps`, `aspectRatio` | O tempo e o quadro. `aspectRatio` inclui `21:9`. |
| `acceptedSceneSchemaVersions` | As versões de plano de cena que o seu cliente consegue ler. |
| `workflowId`, `nodeId`, `forcePrivate` | O contexto de execução de sempre. |

Não há campo de modelo: o planejador é fixo. Para uma origem `scene`, omita os campos de tempo para manter os da própria cena; enviá-los muda o tempo da cena, e um valor incompatível é recusado. Uma origem de prompt produz uma cena da versão 2, então um cliente que não aceita a versão 2 é recusado sem custo.

### O que uma execução concluída retorna
| Campo | O que contém |
| --- | --- |
| `videoUrl`, `scenePlan`, `sceneRevisionId` | O MP4, a composição exata a partir da qual ele foi renderizado e o ID dessa revisão. Exporte a revisão de novo mais tarde, só com renderização. |
| `posterAssetId`, `shotStills` | O pôster e uma imagem fixa por tomada, como `{ shotIndex, frame, assetId, url }`, em ordem de tomada, sem custo extra. |
| `validation` | `{ status, reportAssetId, warnings }`. |
| `renderer`, `metadata` | O renderizador e `{ width, height, fps, frames, duration }`. |
| `metadata.summary`, `repairPasses`, `admissionRetries`, `mechanicalPasses`, `restoredAssertions` | Uma execução que criou a cena informa o que fez: um resumo curto, as correções que executou e outras passadas. Uma exportação só de renderização omite esses campos. |
| `metadata.review` | Presente só quando a cena passou em todas as verificações obrigatórias, mas foi entregue sem a aprovação do revisor visual. |

A `url` de cada imagem fixa é um endpoint autenticado na implantação, não um link público: busque-a com o seu próprio token. Mesmo assim, você pode enviá-la como referência de imagem para uma geração, e o Nodaro concede a essa execução uma leitura de curta duração desse único arquivo.

Verifique a presença do próprio `metadata.review` e depois leia o `verdict` dele. `refused` significa que o revisor ainda fez objeções depois que o orçamento de correções foi gasto, e `objections` lista o que ele encontrou. `unavailable` significa que a revisão não deu nenhuma resposta utilizável, então ninguém avaliou a cena. Nos dois casos, `validation.status` continua `passed`, porque as verificações obrigatórias passaram. Os códigos de aviso são abertos; trate um código que você não conhece como informativo. Veja [Renderização 3D Pro](https://nodaro.ai/docs/nodes/video/pro-3d-render) para todos os campos e códigos de aviso.

### Quando uma execução falha
Os erros no envio são recusas: `503 SCENE_CAPABILITY_UNAVAILABLE`, `503 price_not_configured` (o operador não definiu um preço; nada foi reservado) e `400 validation_error`. As falhas durante a execução ficam no job, e a mensagem de erro começa com o código:

| Código | Tentar de novo? | Significado |
| --- | --- | --- |
| `SCENE_PROVIDER_UNAVAILABLE` | Sim, depois de alguns minutos | O modelo do planejador estava indisponível ou sobrecarregado. |
| `SCENE_PLANNING_TIMEOUT` | Sim | O planejamento demorou demais. Tente de novo, ou encurte o briefing e as referências. |
| `SCENE_PLANNER_OUTPUT_INVALID` | Não sem mudanças | Não foi possível montar o plano. Simplifique o briefing ou use menos referências. |
| `SCENE_QUALITY_FAILED` | Leia o rascunho primeiro | Uma verificação obrigatória falhou, ou a receita foi recusada, depois que o orçamento de correções foi gasto. |
| `SCENE_RESOURCE_LIMIT`, `SCENE_EXPORT_UNSUPPORTED`, `SCENE_REVISION_CONFLICT`, `SCENE_BUILD_TIMEOUT`, `SCENE_RENDER_FAILED` | Depende | Não foi possível terminar o build ou a renderização. |

Um job com falha em um mecanismo avançado ainda pode trazer o que montou. Quando uma passada montou uma cena, `output_data` guarda o rascunho: `scenePlan`, `sceneRevisionId`, `deliveryId`, `posterAssetId` e `validation` com `status: "failed"`. O rascunho é uma revisão comum que você pode editar ou renderizar. Quando nenhuma passada compilou, não há rascunho, mas `validation.sourceRetained` diz se a receita recusada foi mantida. Leia a receita no descritor `source-json` da entrega, com acesso de edição, sem custo. Executar o mesmo prompt de novo, em vez disso, paga pela mesma criação duas vezes.

Em uma execução de workflow, um nó com falha que guardou um resultado também o traz em `nodeStates[nodeId].output`. Verifique o campo, não o status, e nunca interprete um `output` presente como sucesso.

## Versões de cena e arquivos armazenados
Um plano de cena é uma união de duas versões. Leia `schemaVersion` antes de qualquer campo específico de uma versão.

| Versão | O que armazena | Produzida por |
| --- | --- | --- |
| 1 | Formas primitivas, grupos e quadros-chave esparsos para os objetos e a câmera. | O mecanismo básico. |
| 2 | Entidades com nome, geometria GLB armazenada, uma câmera amostrada em todos os quadros e tomadas contíguas. | Os mecanismos avançados e a Renderização 3D Pro. |

Um plano da versão 2 lista cada arquivo por um `assetId` opaco, pelo tamanho em bytes e pelo digest SHA-256; ele nunca contém uma chave de armazenamento nem uma URL de download. A versão 2 aceita geometria de massinha com animação rígida; arquivos com textura, com skinning ou com morphing são recusados. Os limites dela são 100 entidades, 2.000 nós de malha, 200.000 triângulos, 32 tomadas e 64 MiB de arquivos de reprodução. Veja [Formato do plano de cena](https://nodaro.ai/docs/developers/embed/scene3d-format) para o formato completo.

As revisões armazenadas têm rotas próprias. Elas precisam de um token Bearer, respondem com `Cache-Control: no-store` e retornam `404` para uma revisão excluída ou inacessível:

- `GET /v1/3d-scene/revisions/:revisionId` retorna o manifesto e os descritores dos arquivos. Os arquivos de reprodução exigem acesso de visualização ao workflow da revisão; a fonte nativa exige acesso de edição. As revisões pessoais são só do dono.
- `GET /v1/3d-scene/deliveries/:jobId` retorna o que uma exportação entregou: `sourceKind`, o `sceneRevisionId` exato, os digests da origem e os descritores (o pôster, o relatório de validação e um `shot-still` por tomada). `…/assets/:assetId` retorna os bytes, com suporte a intervalos (range). As leituras exigem acesso à entrega e ao workflow de origem, e não custam nada.

No SDK, `client.scene3d.getDelivery`, `deliveryAssetBytes`, `retainedRecipe`, `assetBytes`, `sourceBytes` e `applyEdits` encapsulam essas rotas.

## Uso pelo MCP
Os assistentes de IA usam `generate_3d_scene`, `edit_3d_scene` e `render_3d_scene` com o escopo `workflows:execute`, e `pro_3d_render` onde a implantação puder atendê-la. Veja [Cenas 3D pelo MCP](https://nodaro.ai/docs/mcp/3d-scenes). Para mostrar uma cena na sua própria página, veja a [incorporação da prévia 3D](https://nodaro.ai/docs/developers/embed/scene3d).

## Erros
| Status | Código | Significado |
| --- | --- | --- |
| `400` | `validation_error` | O corpo é inválido, por exemplo uma lista de referências acima dos limites, um mecanismo desconhecido, um `quoteId` ausente, um `Idempotency-Key` ausente ou inválido, ou uma versão de esquema que o seu cliente não aceita. |
| `401` | `unauthorized` | O token está ausente, é inválido ou foi revogado. |
| `402` | `insufficient_credits` | Só no Nodaro Cloud. A conta não cobre a reserva. |
| `404` | `not_found` | A revisão ou a entrega não existe, ou você não consegue acessá-la. |
| `409` | — | A revisão ou o digest de conteúdo de uma edição não corresponde mais. Leia a cena de novo. |
| `503` | `SCENE_CAPABILITY_UNAVAILABLE` | O mecanismo, o suporte a importação ou a Renderização 3D Pro não está disponível nesta implantação. |
| `503` | `price_not_configured` | Nenhum preço em créditos está definido para a Renderização 3D Pro nesta implantação. Nada foi reservado. |

## Frequently asked questions

### O que a API de cenas 3D produz?

Um plano de cena editável, não um vídeo. O plano guarda os objetos, o movimento deles, a câmera e a iluminação. Edite o plano quantas vezes quiser e depois renderize-o em MP4 com POST /v1/render-video/plan.

### Quanto custa uma cena 3D?

No Nodaro Cloud, criar uma cena custa 11, 33 ou 44 créditos, conforme o nível do modelo de linguagem, mais o preço da Análise de vídeo quando você envia uma referência em vídeo. Renderizar custa 55 créditos até 1920 px no lado mais longo, 83 até 5,12 megapixels e 138 acima disso.

### As edições determinísticas são gratuitas?

Sim. As edições enviadas como operações, como mover um objeto ou trocar a lente, não chamam nenhum modelo de linguagem e custam 0 créditos. As edições por instrução, escritas como prompt, custam o mesmo que a criação.

### Como uso uma renderização em massinha como referência de vídeo?

Envie o MP4 em referenceVideoUrls no Gerar vídeo, com uma legenda em referenceVideoCaptions que diga para copiar o layout e a câmera e ignorar a aparência de massinha cinza. Envie também as suas imagens de aparência e uma referência de personagem para cada figura que precisa parecer real.

### Qual é a diferença entre a Renderização 3D Pro e o Gerar cena 3D?

O Gerar cena 3D faz uma prévia em massinha barata e editável, e uma renderização separada a transforma em MP4. A Renderização 3D Pro cria e renderiza uma tomada pronta em um único job pago, onde a implantação tem um mecanismo para isso.
