# Cenas 3D

> Crie uma cena 3D de massinha editável com um prompt, revise-a, renderize-a em MP4 e use o resultado como guia de layout e movimento para um modelo de vídeo.

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

Uma **cena 3D** é uma cena de massinha animada e editável: geometria simples com movimento por quadros-chave, criada a partir de um prompt e de referências opcionais de imagem ou de vídeo. Por um assistente de IA, você a cria, a revisa com palavras ou operações exatas, a renderiza em MP4 e usa a renderização como guia de layout e de movimento para um modelo de vídeo. As ferramentas MCP fazem o mesmo trabalho que os nós [**Gerar cena 3D** (Generate 3D Scene)](https://nodaro.ai/docs/nodes/video/generate-3d-scene) e [**Editar cena 3D** (Edit 3D Scene)](https://nodaro.ai/docs/nodes/video/edit-3d-scene) no canvas.

## As ferramentas
| Ferramenta | O que faz |
| --- | --- |
| `generate_3d_scene` | Um prompt e referências opcionais viram uma cena editável |
| `edit_3d_scene` | Uma revisão da cena e uma instrução ou operações viram uma nova revisão |
| `render_3d_scene` | Uma revisão exata da cena vira um MP4, pelo mecanismo do **Renderizar vídeo** (Render Video) |
| `pro_3d_render` | Um único job que cria, revisa ou exporta uma cena e retorna o plano da cena, o MP4 e uma imagem fixa por tomada, nas implantações que têm o mecanismo dela |

Cada ferramenta precisa de `workflows:execute` e retorna um ID de job; leia o resultado com `get_job` ou `wait_for_job`. Um job de cena retorna `output_data.scenePlan`, e uma renderização retorna a URL de um vídeo. Os parâmetros estão na [referência de ferramentas](https://nodaro.ai/docs/mcp/tools/3d-scenes).

## O ciclo
### Gerar a cena
Chame `generate_3d_scene` com uma descrição da tomada, `duration_seconds`, `fps` e `aspect_ratio`. As referências são `{ id, url, kind, role }`: uma imagem ou um vídeo, usados para aparência, layout ou movimento.

### Revisar a cena
Leia `scenePlan` do job concluído. Chame `edit_3d_scene` com esse objeto como `scene_plan`, o `revisionId` dele como `expected_revision_id` e um `prompt` de edição ou `operations`. Liste em `locked_object_ids` os objetos que não podem mudar.

### Renderizar a cena
Chame `render_3d_scene` com o `scene_plan` resultante. Nenhum LLM é executado.

### Usar a renderização como guia
Passe o MP4 para [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video) em `reference_video_urls` e diga para que ele serve em `reference_video_captions`, na mesma posição. Continue passando também suas imagens de aparência como referências.

Uma renderização em massinha é um guia de layout, não um visual. Sem uma legenda, o modelo de vídeo pode copiar também a aparência cinza da massinha.

## O que a primeira versão consegue fazer
- **Geometria e movimento.** As cenas usam formas primitivas e animação determinística por quadros-chave.
- **As referências são aproximadas.** Uma cena reconstruída a partir de uma referência é uma aproximação dela.
- **Vídeos de referência inteiros.** Um vídeo de referência é usado por inteiro. Para usar um trecho, corte o clipe antes e passe a URL do trecho cortado; uma janela de tempo parcial é recusada antes de qualquer cobrança de autoria.
- **As operações não chamam nenhum LLM.** As edições com `operations` são aplicadas diretamente. A renderização também.

## Mecanismos
`generate_3d_scene` e `edit_3d_scene` aceitam um `engine`: `basic` (o padrão), `blender-cloud` ou `blender-local`. Um mecanismo avançado precisa estar disponível na implantação; um mecanismo indisponível é recusado e nunca é trocado por `basic`. Os mecanismos avançados usam um planejador fixo; por isso, deixe `llm_model` e `reasoning_effort` de fora nesses casos e defina o limite de correções deles com `max_repair_passes`.

Com um mecanismo avançado que consegue importá-los, `generate_3d_scene` também aceita `input_assets`: até oito modelos 3D existentes (GLB), cada um como `{ id, revisionId, assetId, label }`. Mantenha imagens e vídeos em `references`. As importações são recusadas antes de qualquer cobrança quando o mecanismo não consegue importar, e o servidor localiza os arquivos sozinho; por isso, nunca envie URLs nem hashes.

## Quanto custa uma renderização
Uma renderização é cobrada pelo tamanho do quadro no plano que você passa:

| Quadro | Créditos |
| --- | --- |
| Até 1920 pixels no lado maior | 55 |
| Acima disso, até 5,12 megapixels | 83 |
| Maior | 138 |

Defina `width` e `height` no plano da cena de propósito: uma cena de 2560 por 2560 custa 2,5 vezes uma de 1920 por 1080, enquanto uma de 1920 por 1920 custa o mesmo que uma de 1920 por 1080. [Renderizar vídeo](https://nodaro.ai/docs/nodes/video/render-video) traz a tabela completa.

## Ler o resultado de um mecanismo avançado
Uma cena criada por um mecanismo avançado informa o que ele supôs e fez. Todos estes campos são opcionais, e o mecanismo `basic` não informa nenhum deles.

| Campo | O que informa |
| --- | --- |
| `validation.warnings[]` com `SCENE_AUTHORING_ASSUMPTION` | As suposições do planejador |
| `metadata.summary` | A descrição, feita pelo próprio mecanismo, do que ele criou |
| `repairPasses` | As correções executadas; `0` quando a cena foi aceita de primeira |
| `admissionRetries` | Novas tentativas do planejador antes da montagem, que não gastam nenhuma passada de correção |
| `mechanicalPasses` | Correções que o mecanismo aplicou a partir da solução do próprio compilador, sem chamar o planejador, cada uma com um aviso `REMEDY_AUTO_APPLIED`. Elas são contadas separadamente de `repairPasses`, dentro de uma cota própria já incluída na cotação. |
| `restoredAssertions` | Verificações obrigatórias que o mecanismo restaurou depois que uma resposta alterou uma delas, cada uma com um aviso `ASSERTION_RESTORED` |

Uma exportação que só renderiza não cria nada; por isso, não informa resumo e deixa as contagens de fora.

### Quando uma cena concluída não foi aprovada
Um job concluído pode trazer `metadata.review`, o que significa que a cena foi entregue sem a aprovação da revisão visual. Verifique a presença de `metadata.review`, e não o status nem o número de avisos, e leia o `verdict` antes de dizer qualquer coisa ao usuário:

- **`refused`**: o limite de correções foi gasto, todas as verificações obrigatórias passaram, e a revisão ainda fez objeções. A cena vem com as objeções e um aviso `SCENE_REVIEW_REFUSED` por objeção.
- **`unavailable`**: a revisão não deu um veredito utilizável em `attempts` tentativas. `reason` é `provider` quando a revisão nunca chegou ao modelo dela e `unusable` quando a resposta não pôde ser usada. Ninguém avaliou a cena, e `validation.warnings[]` começa com `SCENE_REVIEW_UNAVAILABLE`. Não relate uma recusa para uma cena que ninguém revisou.

`validation.status` continua `passed` nos dois casos, e a lista de objeções pode estar vazia.

### Quando um job avançado falhou
Um job que falhou com `SCENE_QUALITY_FAILED` gastou o limite dele sem chegar a uma cena que pudesse garantir. Leia o `output_data` dele antes de executá-lo de novo:

- **Um rascunho foi montado.** O job com falha aponta para ele com `scenePlan`, `sceneRevisionId`, `deliveryId` e `posterAssetId`, e `validation.status` é `failed`. O rascunho é uma revisão comum: passe-o para `edit_3d_scene` ou `render_3d_scene`.
- **Nada foi compilado.** Não há `scenePlan`, mas o job ainda tem um `deliveryId`, e `validation.sourceRetained` informa se a receita foi mantida. Busque-a pela API REST com `GET /v1/3d-scene/deliveries/{deliveryId}` e depois o arquivo `source-json` dela. Ler a receita não custa créditos e exige suas próprias credenciais e acesso de edição ao workflow do job; não há ferramenta MCP para isso.

Executar o mesmo prompt de novo paga duas vezes pela mesma autoria.

## Renderização 3D Pro
[`pro_3d_render`](https://nodaro.ai/docs/mcp/tools/3d-scenes#pro_3d_render) é uma operação separada, não uma opção de `generate_3d_scene`. Um único job produz uma tomada pronta: a saída concluída traz `scenePlan` e `videoUrl`, com a revisão, um pôster, a validação e os detalhes do renderizador. A ferramenta só aparece em implantações com um mecanismo que a implementa; por isso, a presença dela na lista de ferramentas é a verificação de disponibilidade. Ela funciona como o nó [**Renderização 3D Pro** (3D Render Pro)](https://nodaro.ai/docs/nodes/video/pro-3d-render).

A saída também traz `shotStills`, uma imagem fixa por tomada da composição, na ordem das tomadas: `{ shotIndex, frame, assetId, url }`. `shotIndex` conta a partir de 0 e `frame` é o primeiro quadro da tomada; assim, cada imagem fixa se alinha com o MP4. Uma cena de uma única tomada tem exatamente uma, no quadro 0. Elas vêm da mesma execução, sem custo extra. Use a imagem fixa de uma tomada como referência de imagem quando gerar essa tomada com um modelo de vídeo.

A `url` de cada imagem fixa é um endereço autenticado na instalação, porque os arquivos de entrega são privados. Busque-a com suas próprias credenciais; não é um link público. Mesmo assim, você pode passá-la para `generate_image` ou `generate_video`: essa execução recebe uma permissão temporária para ler aquele único arquivo. A permissão dura minutos e não é armazenada; por isso, guarde a URL autenticada em tudo o que você salvar.

Use `generate_3d_scene`, `edit_3d_scene` e `render_3d_scene` para a previz em massinha, mais barata e editável. Para o formato exato da cena e os padrões atuais, peça ao assistente que chame `get_node_skill` com `generate-3d-scene` ou `edit-3d-scene`.

## Frequently asked questions

### O que é uma cena 3D no Nodaro?

Uma cena de massinha animada e editável, feita de geometria simples com movimento por quadros-chave, criada a partir de um prompt e de referências opcionais. Você a revisa com palavras ou operações exatas e a renderiza em MP4.

### Para que serve a renderização de uma cena 3D?

Como guia de layout e de movimento para um modelo de vídeo. Passe a renderização para generate_video como vídeo de referência, com uma legenda que diga que ela é um guia de layout, junto com as suas referências de aparência.

### Quanto custa renderizar uma cena 3D?

55 créditos para um quadro de até 1920 pixels no lado maior, 83 acima disso até 5,12 megapixels e 138 para um quadro maior. Uma cena de 2560 por 2560 custa 2,5 vezes uma de 1920 por 1080.

### Um job de cena terminou com um aviso de revisão. Ele está com problema?

Não, o job foi concluído e a cena pode ser usada. metadata.review informa que a revisão visual não a aprovou. O veredito refused significa que a revisão fez objeções; unavailable significa que ninguém avaliou a cena.

### Um job de cena falhou. Devo executá-lo de novo?

Leia a saída dele primeiro. Um job com falha de um mecanismo avançado ainda pode trazer um rascunho de cena que você pode editar ou renderizar, ou a receita da cena que foi recusada. Executar o mesmo prompt de novo paga duas vezes pela mesma autoria.