# Cenas 3D

> Parâmetros das quatro ferramentas de cena 3D, que criam e revisam uma cena de massinha editável, a renderizam em MP4 ou entregam uma tomada pronta num job.

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

As **ferramentas de cena 3D** criam cenas de massinha editáveis e animadas, com geometria simples e movimento por quadros-chave, revisam essas cenas e as renderizam em vídeo. A renderização então serve de guia de layout e de movimento para um modelo de vídeo. Esta página lista os parâmetros de cada ferramenta; [Cenas 3D](https://nodaro.ai/docs/mcp/3d-scenes) explica o ciclo de trabalho e como ler os resultados.

Todas as ferramentas precisam da permissão `workflows:execute` e retornam um ID de job. Leia o resultado com `get_job` ou `wait_for_job`.

## `generate_3d_scene`
Cria uma cena de massinha editável e animada a partir de um prompt e de referências opcionais. Ela não faz um vídeo fotorrealista. Funciona como o nó [**Gerar cena 3D** (Generate 3D Scene)](https://nodaro.ai/docs/nodes/video/generate-3d-scene).

**Permissão:** `workflows:execute`. **Créditos:** como o nó Gerar cena 3D, de 11 a 44.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `prompt` | string | **Obrigatório.** A tomada, com até 8.000 caracteres. |
| `duration_seconds` | number | De 1 a 60. |
| `fps` | integer | De 15 a 60. |
| `aspect_ratio` | string | O formato do quadro. |
| `references` | array | Até 8 referências, no máximo um vídeo, cada uma `{ id, url, kind, role }`. `kind` é `image` ou `video`. `role` é `appearance`, `layout` ou `motion`: as imagens orientam a aparência e o layout, e um vídeo orienta o layout e o movimento. Uma referência de vídeo é usada inteira; corte-a antes para usar só um trecho. Um `objectId` opcional indica o objeto da cena que a referência mostra, como o protagonista. |
| `input_assets` | array | Até 8 modelos 3D existentes (GLB), cada um `{ id, revisionId, assetId, label }`. Exige um mecanismo avançado capaz de importá-los; caso contrário, a chamada é recusada antes de qualquer cobrança. Nunca envie URLs. |
| `engine` | string | `basic` (padrão), `blender-cloud` ou `blender-local`. Um mecanismo que a implantação não tem é recusado; a chamada nunca volta para `basic`. |
| `max_repair_passes` | integer | O limite de correções de um mecanismo avançado, de 0 a 2. |
| `llm_model`, `reasoning_effort` | string | O planejador do mecanismo `basic`. Omita-os num mecanismo avançado, que usa um planejador fixo. |
| `local_connection_id` | string | A conexão de desktop pareada, para `blender-local`. |
| `accepted_scene_schema_versions` | array | As versões do formato de cena que o seu cliente aceita. |

**Retorna:** um ID de job. O `output_data.scenePlan` do job concluído é a cena, com o `revisionId` dela.

## `edit_3d_scene`
Revisa uma cena e mantém a revisão anterior dela. Envie um prompt, que o planejador aplica, ou operações, que são aplicadas diretamente, sem chamar um LLM. Funciona como o nó [**Editar cena 3D** (Edit 3D Scene)](https://nodaro.ai/docs/nodes/video/edit-3d-scene).

**Permissão:** `workflows:execute`. **Créditos:** como o nó Editar cena 3D, de 0 a 44.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `scene_plan` | object | **Obrigatório.** O `scenePlan` inteiro de um job de cena. |
| `expected_revision_id` | string | **Obrigatório.** O `revisionId` do plano. A edição é recusada se ele não corresponder. |
| `prompt` | string | A alteração, em palavras, com até 8.000 caracteres. |
| `operations` | array | De 1 a 100 alterações exatas: `set-object`, `add-object`, `remove-object`, `set-camera`, `set-lighting` ou `set-background`. |
| `locked_object_ids` | array | Objetos que a edição não pode alterar. |
| `selected_object_ids` | array | Objetos de que a edição trata. |
| `references` | array | Como em `generate_3d_scene`. |
| `replace_references` | boolean | Substitui as referências de imagem e de vídeo da cena por `references`. |
| `engine`, `max_repair_passes`, `llm_model`, `reasoning_effort`, `local_connection_id`, `accepted_scene_schema_versions` | | Como em `generate_3d_scene`. |

**Retorna:** um ID de job. O `output_data` do job concluído contém o novo `scenePlan` e um `changeSummary`. Um MP4 sozinho não é uma cena editável: para reconstruir uma cena a partir de um vídeo, use `generate_3d_scene` com o vídeo como referência.

## `render_3d_scene`
Renderiza uma revisão exata de uma cena em MP4 com o mecanismo do **Renderizar vídeo** (Render Video). Nenhum LLM é executado. A câmera, a duração e o quadro vêm do plano da cena.

**Permissão:** `workflows:execute`. **Créditos:** conforme o tamanho do quadro no plano: 55 até 1920 pixels no lado maior, 83 acima disso até 5,12 megapixels e 138 para um quadro maior.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `scene_plan` | object | **Obrigatório.** O plano da cena a renderizar. |

**Retorna:** um ID de job. O resultado é uma URL de vídeo. Defina `width` e `height` no plano de forma deliberada: uma cena de 2560 por 2560 custa 2,5 vezes uma de 1920 por 1080, enquanto 1920 por 1920 custa o mesmo que 1920 por 1080. [Renderizar vídeo](https://nodaro.ai/docs/nodes/video/render-video) tem a tabela de preços completa.

## `pro_3d_render`
Produz uma tomada 3D pronta num único job: o job concluído traz o plano da cena, o MP4 e uma imagem fixa por tomada. Só aparece na lista de ferramentas nas implantações que têm um mecanismo para ela. Funciona como o nó [**Renderização 3D Pro** (3D Render Pro)](https://nodaro.ai/docs/nodes/video/pro-3d-render).

**Permissão:** `workflows:execute`. **Créditos:** cotados e cobrados na mesma chamada. A criação e cada passada de correção são trabalhos pagos; uma simples exportação de uma cena existente não tem custo de criação. **Somente no Nodaro Cloud.**

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `source` | object | **Obrigatório.** Exatamente uma das três origens abaixo. |
| `duration_seconds`, `fps` | number | De 1 a 60 segundos e de 15 a 60 fps. Omita-os para uma origem de cena, a menos que queira mudar o timing dela; um valor conflitante é recusado. |
| `aspect_ratio` | string | `16:9`, `9:16`, `1:1`, `4:5` ou `21:9`. Omita-o para uma origem de cena. |
| `max_repair_passes` | integer | O limite de correções, de 0 a 2. Padrão: `2`. Cada passada é paga. |
| `engine` | string | `blender-cloud` ou `blender-local`. |
| `quality`, `style` | string | `standard` e `clay`. |
| `client_request_id` | string | Um token de nova tentativa: de 8 a 128 caracteres entre letras, dígitos e `_ - . :`. Reutilize-o se repetir uma chamada que expirou, para que o job não seja iniciado nem cobrado duas vezes. |

| `source.kind` | Campos | O que faz |
| --- | --- | --- |
| `prompt` | `prompt` e, opcionalmente, `references` e `input_assets` | Cria uma nova cena a partir de um briefing e depois a renderiza. |
| `scene` | `revision_id`, `source_job_id` opcional e `edit_prompt` opcional | Renderiza uma revisão existente. Sem `edit_prompt`, é uma simples exportação. Com ele, a cena é revisada antes, o que tem custo de criação. `source_job_id` é obrigatório para cenas `basic` guardadas só no histórico de jobs. |
| `local-export` | `export_id`, `connection_id` | Usa uma exportação pronta de um app de desktop pareado, onde houver. |

**Retorna:** um ID de job. O `output_data` do job concluído traz `scenePlan`, `videoUrl` e `shotStills`, uma imagem fixa por tomada, cada uma `{ shotIndex, frame, assetId, url }`. Não há parâmetro de modelo nem de raciocínio: o planejador é fixo.

## Frequently asked questions

### Quanto custa renderizar uma cena 3D?

Uma renderização é cobrada pelo tamanho do quadro no plano da cena. São 55 créditos até 1920 pixels no lado maior, 83 acima disso até 5,12 megapixels e 138 para um quadro maior.

### Editar uma cena 3D sempre chama um modelo de IA?

Não. Uma edição com operações, como mover um objeto ou mudar a câmera, aplica essas operações diretamente, sem chamar um LLM. Uma edição com prompt pede ao planejador que faça a alteração.

### Qual é a diferença entre render_3d_scene e pro_3d_render?

render_3d_scene exporta uma revisão existente de uma cena para MP4. pro_3d_render é um único job que pode criar, revisar ou exportar uma cena e retorna o plano da cena, o MP4 e uma imagem fixa por tomada, nas implantações que têm o mecanismo dele.