Cenas 3D

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.

Endpoints

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 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; o output_data.scenePlan do job concluído é a cena editável.

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

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

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

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

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

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

O source do corpo é exatamente um destes:

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

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

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.

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 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. Para mostrar uma cena na sua própria página, veja a incorporação da prévia 3D.

Erros