Cenas 3D

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) e Editar cena 3D (Edit 3D Scene) no canvas.

As ferramentas

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.

O ciclo

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:

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

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

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.