Objetos
API REST de objetos: crie e arquive adereços e produtos, gere e aprove a imagem principal e gere variações de material e ângulo e clipes de movimento.
A API de objetos automatiza tudo o que o Estúdio de objetos/adereços faz com adereços e produtos. Você cria um objeto, gera imagens principais candidatas, aprova uma delas e adiciona variações de ângulo, de material e de estado, além de clipes de movimento. Os nós de imagem e de vídeo então reutilizam o objeto, e assim a mesma lanterna, o mesmo carro ou a mesma cadeira têm a mesma aparência em todas as tomadas.
As rotas funcionam em todas as edições e recebem um bearer token: um token de API pessoal (ndr_…), um token de app OAuth (ndr_app_…) ou o seu token de sessão na Community edition. Toda rota se restringe aos dados de quem faz a chamada. Veja Autenticação.
Endpoints
| Método | Caminho | O que faz |
|---|---|---|
GET | /v1/objects | Lista os seus objetos. |
GET | /v1/objects/:id | Retorna um objeto com as tarefas dele em andamento. |
POST | /v1/objects | Cria um objeto, ou atualiza um objeto quando o corpo tem um id. |
DELETE | /v1/objects/:id | Arquiva um objeto. Ele pode ser restaurado. |
DELETE | /v1/objects/:id?permanent=true | Exclui de vez um objeto arquivado e os arquivos dele. |
POST | /v1/objects/:id/restore | Restaura um objeto arquivado. |
POST | /v1/generate-object | Gera imagens principais candidatas. |
POST | /v1/generate-object-asset | Gera uma variação de ângulo, de material, de estado ou personalizada. |
POST | /v1/generate-object-motion | Anima a imagem principal em um clipe de movimento. |
POST | /v1/objects/:id/approve-main-image | Aprova uma candidata como imagem principal e escreve a descrição do objeto. |
POST | /v1/objects/:id/llm-caption | Escreve a descrição de novo a partir da imagem principal atual. |
O que um objeto guarda
| Campo | O que guarda |
|---|---|
id, name, description | O identificador, o nome de exibição e as notas de identidade. |
category | furniture, vehicle, weapon, food, clothing, electronics, nature, tool, animal ou other. |
style | realistic, anime, 3d-pixar ou illustration. |
sourceImageUrl | A imagem principal que serve de âncora, definida quando você aprova uma candidata. |
canonicalDescription | Uma descrição visual de cerca de 80 a 120 palavras, escrita pelo Nodaro quando a imagem principal é aprovada. Até lá, é uma string vazia. |
styleLock | Se as variações são geradas a partir da imagem principal. true por padrão. |
angles, materials, variations, motionClips | Os grupos de variações. Cada entrada é { name, url }; motionClips guarda vídeos. |
referencePhotos | Até 20 fotos do painel de inspiração, cada uma { kind, url }. |
pendingJobs | Só em GET /v1/objects/:id: as tarefas de variações ainda em execução para este objeto. |
Os grupos de variações
| Grupo | O que mostra | Variações predefinidas |
|---|---|---|
angles | O objeto de outro ponto de vista | front, side, top, back, three-quarter, detail, in-context, exploded, perspective |
materials | O objeto em outro material | wood, metal, glass, plastic, fabric, stone, ceramic, leather, paper, gold, silver, copper, marble |
variations | Outro estado ou estilo | clean, weathered, damaged, ornate, minimal, broken, antique, futuristic, holographic, dirty, polished |
motionClips | Clipes em loop com movimento de câmera | rotate-360, hover, spin-slow, parallax, pulse, drift, dolly-around, push-in, drone-orbit |
Fotos de referência
Um painel de inspiração acompanha o objeto. Todo nó que usa o objeto recebe essas fotos como referências extras, mesmo sem uma imagem conectada, e o kind de cada foto diz ao modelo para que ela serve.
kind | Para que serve |
|---|---|
front | Uma vista frontal limpa. |
side | Um perfil lateral, útil para veículos, móveis e armas. |
detail | Um close de um detalhe marcante, como uma gravação ou uma dobradiça. |
context | O objeto no lugar, segurado ou instalado, para dar a escala. |
moodBoard | A paleta ou a sensação. |
other | Qualquer outra coisa. |
Você pode adicionar até 20 fotos, com qualquer quantidade de cada tipo. Para um adereço principal ou um produto de destaque, adicione de três a seis fotos antes da primeira geração: assim, os primeiros resultados ficam muito mais fiéis.
Listar objetos
GET /v1/objects retorna os seus objetos ativos, do mais novo para o mais antigo. Adicione archived=true para ver os arquivados, ou projectId para ver um projeto. Adicione q para manter apenas os objetos cujo nome ou descrição contém todas as palavras dele, sem diferenciar maiúsculas de minúsculas: a mesma busca dos personagens. A ferramenta MCP list_objects aceita a mesma busca como search. Sem limit, a rota retorna a lista completa. Com limit (no máximo 500), ela retorna uma página e um nextCursor; envie esse valor de volta como cursor até ele ser null.
curl "https://app.nodaro.ai/v1/objects?limit=100" \
-H "Authorization: Bearer $NODARO_API_KEY"import { createClient, StaticTokenAuth } from '@nodaro/sdk'
const client = createClient({
baseUrl: 'https://app.nodaro.ai',
auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})
const page = await client.objects.list({ limit: 100 })
const next = await client.objects.list({ limit: 100, cursor: page.nextCursor! })
const { objects: archived } = await client.objects.listArchived()nodaro objects list --json
nodaro objects list --archivedGET /v1/objects/:id retorna um objeto com pendingJobs. Um objeto arquivado retorna 404 not_found, a mesma resposta de um objeto que não existe. Cada linha, na lista e por ID, também traz o estado dela na prateleira do Nodaro Keepers: catalog, catalogSort e catalogCategory. Eles são false, 0 e null nas suas próprias linhas e em toda cópia.
Criar ou atualizar um objeto
POST /v1/objects cria um objeto quando o corpo não tem id, e atualiza o objeto quando tem. Uma criação precisa de nodeId e name; use qualquer rótulo em nodeId, como "scripted", quando não houver nó no canvas.
Em uma atualização, só os campos que você envia são gravados. Os grupos de variações nunca são gravados por uma atualização, então um salvamento não pode sobrescrever uma variação que uma tarefa está adicionando. Envie expectedUpdatedAt, o updatedAt atual do objeto, para recusar a atualização quando alguém tiver alterado o objeto depois que você o leu: nesse caso, a rota retorna 409 concurrent_modification.
curl -X POST https://app.nodaro.ai/v1/objects \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodeId": "scripted",
"name": "Antique Lantern",
"description": "Weathered brass lantern with hand-engraved filigree",
"category": "tool",
"style": "realistic"
}'const { id } = await client.objects.create({
nodeId: 'scripted',
name: 'Antique Lantern',
description: 'Weathered brass lantern with hand-engraved filigree',
category: 'tool',
style: 'realistic',
})
const object = await client.objects.get(id)
await client.objects.update(id, { styleLock: false, expectedUpdatedAt: object.updatedAt })nodaro objects create "Antique Lantern" --node-id scripted \
--description "Weathered brass lantern with hand-engraved filigree" \
--category tool --style realistic
nodaro objects update <id> --style-lock falseUma criação retorna { id }. Uma atualização retorna { id, updatedAt }.
Propriedade
Tipo
O que o Bloqueio de estilo muda
- Ativado (padrão). Cada ângulo, material e variação é gerado a partir da imagem principal aprovada. A variação mantém as proporções, a silhueta e os detalhes marcantes. Os nós que usam o objeto também recebem a descrição canônica dele. Use para tudo o que precisa parecer o mesmo item em todas as tomadas.
- Desativado. As variações são geradas só a partir de texto. Os nós ainda recebem a descrição canônica, mas apenas como orientação, então o modelo pode reinterpretar o design. Use para explorar alternativas ou comparar visuais.
Gerar imagens principais candidatas
POST /v1/generate-object inicia uma tarefa por candidata e retorna jobIds na hora, um ID por candidata. Uma requisição com uma única candidata também retorna jobId. Consulte as tarefas periodicamente com a API de tarefas.
Com attachToObjectId e count igual a 1, o resultado vira a imagem principal do objeto quando a tarefa termina. Com várias candidatas, nada é anexado; aprove a que você preferir.
curl -X POST https://app.nodaro.ai/v1/generate-object \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Antique Lantern", "count": 4 }'const { jobIds } = await client.objects.generate({
name: 'Antique Lantern',
description: 'Weathered brass lantern with hand-engraved filigree',
count: 4,
})nodaro objects generate --name "Antique Lantern" --count 1 \
--attach-to-object-id <id> --watch{
"jobIds": [
"5e2a8c1f-3b7d-4f9a-a6c2-8d1e4b7f0a3c",
"6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d",
"7a4c1e3b-5d9f-4b2c-c8e4-1f3a6d9b2c5e",
"8b5d2f4c-6e1a-4c3d-d9f5-2a4b7e1c3d6f"
]
}| Campo | O que faz |
|---|---|
name | Obrigatório. O nome do objeto, de 1 a 200 caracteres. |
description | Notas de identidade, até 2.000 caracteres. |
category, style | A categoria e o estilo visual do objeto. |
count | Quantas candidatas gerar, de 1 a 10. O padrão é 1. |
provider | O ID do modelo de imagem. Omita para usar o modelo padrão. |
seedPromptHint | Um trecho de prompt para incorporar ao prompt, com até 2.000 caracteres, por exemplo antique brass, do seletor Material. |
sourceImageUrl | Uma imagem de partida. |
aspectRatio | A proporção da imagem principal. |
attachToObjectId, expectedUpdatedAt | Anexa uma única candidata a este objeto, opcionalmente só quando o objeto não mudou. |
generate-object-asset e generate-object-motion também aceitam seedPromptHint. Ele permite incluir no prompt uma escolha de catálogo, como um veículo ou um material, sem conectar um nó de seletor.
Gerar uma variação
POST /v1/generate-object-asset gera uma variação e retorna { jobId }. Envie attachToObjectId, attachToColumn e attachName para acrescentar { name: attachName, url } ao grupo quando a tarefa terminar.
curl -X POST https://app.nodaro.ai/v1/generate-object-asset \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Antique Lantern",
"assetType": "materials",
"variant": "gold",
"attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
"attachToColumn": "materials",
"attachName": "gold"
}'await client.objects.generateAsset({
name: 'Antique Lantern',
assetType: 'variations',
variant: 'weathered',
attachToObjectId: id,
attachToColumn: 'variations',
attachName: 'weathered',
})nodaro objects generate-asset --asset-type materials --variant gold \
--attach-to-object-id <id> --attach-to-column materials --watch| Campo | O que faz |
|---|---|
name | Obrigatório. O nome do objeto. |
assetType | Obrigatório. angles, materials, variations ou custom. |
variant | Obrigatório. A variação a gerar, de 1 a 100 caracteres. |
description | Uma descrição desta variação, até 1.000 caracteres. Quando você anexa a um objeto e omite o campo, o Nodaro escreve um rascunho a partir da descrição canônica do objeto e do nome da variação. Envie a sua própria descrição para pular o rascunho. |
provider, sourceImageUrl, aspectRatio | O modelo de imagem, a imagem a variar e a proporção. |
attachToObjectId, attachToColumn, attachName | Para onde vai o resultado. attachToColumn é angles, materials ou variations, e uma variação custom precisa indicá-lo. |
Animar a imagem principal
POST /v1/generate-object-motion transforma uma imagem do objeto em um clipe curto com movimento de câmera, como uma rotação lenta, uma flutuação ou uma órbita de drone. Use os clipes como B-roll ou como início de um vídeo mais longo. A rota retorna { jobId }.
sourceImageUrl é obrigatório; não há alternativa automática, então envie a imagem principal aprovada. Com attachToObjectId e attachName, o clipe é acrescentado a motionClips quando termina; você não envia uma coluna.
curl -X POST https://app.nodaro.ai/v1/generate-object-motion \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Antique Lantern",
"motionPrompt": "slow 360 rotation, soft golden rim light",
"sourceImageUrl": "https://cdn.nodaro.ai/objects/lantern-main.png",
"provider": "kling-turbo",
"attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
"attachName": "rotate-360"
}'const lantern = await client.objects.get(id)
await client.objects.generateMotion({
name: 'Antique Lantern',
motionPrompt: 'slow 360 rotation, soft golden rim light',
sourceImageUrl: lantern.sourceImageUrl!,
provider: 'kling-turbo',
attachToObjectId: id,
attachName: 'rotate-360',
})nodaro objects generate-motion --name "Antique Lantern" \
--motion-prompt "slow 360 rotation, soft golden rim light" \
--source-image-url "https://cdn.nodaro.ai/objects/lantern-main.png" \
--provider kling-turbo --attach-to-object-id <id> --attach-name "rotate-360" --watch| Campo | O que faz |
|---|---|
name, motionPrompt | Obrigatórios. O nome do objeto e o movimento a criar. |
sourceImageUrl | Obrigatório. O quadro inicial. |
provider | kling-turbo (o padrão), kling, kling-3.0, hailuo-2.3, wan-i2v ou seedance-2-mini. |
aspectRatio | 1:1 (o padrão, um quadro de produto centralizado), 3:4, 16:9, 9:16 ou 4:3. |
refineFromVideoUrl | Um clipe existente para refinar com o novo prompt, em vez de começar de novo a partir da imagem. A composição se mantém; use um modelo compatível com vídeo para vídeo, como wan-i2v. |
attachToObjectId, attachName | O objeto e o nome do clipe em motionClips. |
O preço de um clipe é o preço de imagem para vídeo do modelo:
| Modelo | Desenvolvedor | Modos | Créditos | Detalhes |
|---|---|---|---|---|
| Kling 2.5 Turbo Pro | Kuaishou | Imagem para vídeo, Texto para vídeo | a partir de 121 | Kling mais rápido — boa qualidade por um custo menor. Aceita quadro final. |
| Kling 2.6 | Kuaishou | Imagem para vídeo, Texto para vídeo | a partir de 152 | Kling 2.6 I2V — movimento muito realista. Clipes de 5 ou 10 s, com áudio nativo opcional. |
| Kling 3.0 | Kuaishou | Imagem para vídeo, Texto para vídeo | a partir de 297 | Kling 3.0 de alta qualidade — duração variável de 3 a 15 s, áudio nativo, 720P/1080P. |
| Hailuo 2.3 Standard | MiniMax | Imagem para vídeo | a partir de 83 | Nível mais barato do Hailuo 2.3 — boa qualidade de base. |
| Wan 2.6 I2V | Alibaba | Imagem para vídeo | a partir de 193 | Wan 2.6 de imagem para vídeo — 5, 10 ou 15 s em 720p/1080p. |
| Seedance 2 Mini | Bytedance | Imagem para vídeo, Texto para vídeo | a partir de 132 | Nível econômico do Seedance 2 — só 480p/720p, preço por segundo conforme a resolução. |
seedance-2-mini é o Seedance 2 Mini. O Seedance 1.5 foi descontinuado em outubro de 2026: uma requisição que ainda informa seedance é executada, e cobrada, como seedance-2-mini.
Aprovar uma imagem principal
POST /v1/objects/:id/approve-main-image define uma candidata concluída como imagem principal e, na mesma chamada, escreve canonicalDescription: o texto que os prompts seguintes usam para descrever o objeto. O corpo é { candidateJobId, expectedUpdatedAt? }, e a candidata precisa ser uma tarefa completed que pertence a você.
A rota retorna { sourceImageUrl, canonicalDescription }. Quando a escrita da descrição falha, a imagem principal é definida mesmo assim, e canonicalDescription é uma string vazia; o SDK retorna null no lugar. Chame POST /v1/objects/:id/llm-caption para tentar de novo. Essa rota retorna { canonicalDescription }, responde 502 quando a descrição não pode ser escrita e 400 main_image_required quando ainda não há imagem principal. Ela não aceita expectedUpdatedAt: repeti-la é sempre seguro. A aprovação em si é gratuita. A descrição é uma chamada de visão do Claude Sonnet 4.6, cobrada pelos tokens que usou, pela tarifa desse modelo. Veja Como as chamadas de LLM são cobradas. Uma aprovação nunca é recusada por falta de créditos. Com saldo insuficiente para a descrição, a imagem é aprovada mesmo assim, a descrição é pulada, e llm-caption pode escrevê-la depois. Uma descrição que o provedor cobrou é cobrada mesmo quando volta vazia. Uma que o provedor não cobrou é reembolsada.
curl -X POST https://app.nodaro.ai/v1/objects/2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c/approve-main-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "candidateJobId": "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d" }'const approved = await client.objects.approveMainImage(id, jobIds[1])
if (approved.canonicalDescription === null) {
await client.objects.recaption(id)
}nodaro objects approve-main-image <id> --candidate-job-id <jobId>
nodaro objects recaption <id>approve-main-image e llm-caption mudam o objeto. Com um token de app OAuth, elas precisam do escopo assets:write. Um token sem ele recebe 403 insufficient_scope. O seu token de sessão e os tokens de API pessoais não precisam de escopo.
Arquivar, restaurar e excluir um objeto
| Ação | curl | TypeScript SDK | CLI |
|---|---|---|---|
| Arquivar | DELETE /v1/objects/:id | client.objects.delete(id) | nodaro objects delete <id> |
| Restaurar | POST /v1/objects/:id/restore | client.objects.restore(id) | nodaro objects restore <id> |
| Excluir de vez | DELETE /v1/objects/:id?permanent=true | client.objects.permanentDelete(id) | nodaro objects delete <id> --permanent |
- Arquivar retorna
{ success: true, archived: true }. Arquivar um objeto já arquivado não muda nada. - Restaurar retorna
{ id, name }. Quando um objeto ativo tem o mesmo nome, sem diferenciar maiúsculas de minúsculas, o Nodaro adiciona o sufixo(restored)e retorna o novo nome. - Excluir de vez retorna
{ success: true, permanent: true }e remove o objeto e todos os arquivos que ele referencia e que são seus: a imagem principal, as variações, os clipes e as fotos de referência. Um arquivo que a geração de outro usuário fez, ou que a pasta de uploads ou a biblioteca de outro usuário guarda, continua no armazenamento. Esse arquivo nunca contou na sua cota de armazenamento, então nada é devolvido por ele. Excluir de vez só funciona em um objeto arquivado; um objeto ativo retorna400 not_archived. Arquive primeiro e depois exclua.
Escolher uma variação ao executar um app
Quando um workflow com um nó Objeto/adereço é publicado como app, o objeto vira uma das entradas do app. Envie "<bucket>/<variant>" para usar uma variação como imagem principal do objeto nessa execução, por exemplo "materials/gold". Escreva o nome da variação em minúsculas, com hífens no lugar dos espaços: polished-brass corresponde a uma variação chamada Polished Brass. Com um grupo ou uma variação desconhecidos, a execução usa a imagem principal. Veja Workflows para executar apps.
Usar o objeto em outras gerações
Envie as URLs das imagens do objeto como imagens de referência para Gerar imagem ou Gerar vídeo; URLs explícitas são a opção mais simples no código. Em um workflow, conecte o nó do objeto ao nó de imagem, ou mencione uma variação no prompt, por exemplo @lantern:1:materials/gold para um objeto chamado Lantern. Quando você conecta um objeto sem mencioná-lo, o Nodaro também procura nomes de variações no seu prompt: “gold finish” (acabamento dourado) seleciona materials/gold. Veja Objetos e adereços.
Usar pelo MCP
| Ferramenta | O que faz |
|---|---|
list_objects, get_object | Encontra um objeto e lê as URLs das variações dele. |
generate_object | Gera uma imagem principal ou uma variação. |
approve_object_main_image, recaption_object | Aprova uma imagem principal ou escreve de novo a descrição do objeto. |
generate_object_motion | Anima a imagem principal. |
Não há ferramentas MCP para criar, atualizar, arquivar, restaurar ou excluir objetos: essas alterações passam pela API REST, pelo SDK ou pela CLI. Veja a Referência das ferramentas MCP.
Créditos
| Rota | Preço no Nodaro Cloud |
|---|---|
POST /v1/generate-object | O preço do modelo de imagem vezes count, reservado para todas as candidatas antes de a primeira tarefa começar. |
POST /v1/generate-object-asset | O preço do modelo de imagem, por variação. |
POST /v1/generate-object-motion | O preço de imagem para vídeo do modelo de vídeo, por clipe. |
approve-main-image | A aprovação é gratuita. A descrição dela é uma chamada de visão, cobrada pelos tokens que usou. |
llm-caption | A mesma chamada de visão, cobrada da mesma forma. |
Erros
| Status | Código | Significado |
|---|---|---|
400 | validation_error | Um campo está ausente ou é inválido. |
400 | not_archived | Uma exclusão permanente foi enviada para um objeto que não está arquivado. |
400 | main_image_required | llm-caption foi chamado antes de o objeto ter uma imagem principal. |
401 | unauthorized | O token está ausente, é inválido ou foi revogado. |
402 | insufficient_credits | Só no Nodaro Cloud. A conta não tem créditos para cobrir a reserva. |
404 | not_found | Nenhum objeto ativo com esse ID pertence a você. |
409 | concurrent_modification | expectedUpdatedAt não corresponde mais. Leia o objeto de novo, mescle as alterações e tente outra vez. |
502 | — | Não foi possível escrever a descrição canônica. Tente de novo. |
Perguntas frequentes
O que é um objeto na API do Nodaro?
Um objeto é um adereço, produto, veículo ou móvel salvo, com uma imagem principal aprovada, uma descrição escrita e imagens de variações. Os nós de imagem e de vídeo reutilizam o objeto para que o item tenha a mesma aparência em todas as tomadas.
O que o Bloqueio de estilo faz?
Com o Bloqueio de estilo ativado, que é o padrão, cada variação é gerada a partir da imagem principal aprovada, então as proporções e os detalhes continuam iguais. Desative-o para deixar as variações reinterpretarem o design, por exemplo para explorar alternativas.
Posso excluir um objeto permanentemente pela API?
Sim. Primeiro arquive o objeto com DELETE /v1/objects/:id e depois chame DELETE /v1/objects/:id?permanent=true. A exclusão permanente remove o objeto e os arquivos dele, e recusa um objeto que não está arquivado.
Quais modelos podem animar um objeto?
Seis modelos de vídeo, pelos IDs de provider kling-turbo (o padrão, Kling 2.5 Turbo Pro), kling, kling-3.0, hailuo-2.3, wan-i2v e seedance-2-mini. Cada clipe custa o preço de imagem para vídeo desse modelo.
Por que GET /v1/objects/:id retorna 404 para um objeto que arquivei?
Objetos arquivados ficam ocultos nas leituras por ID. Liste-os com GET /v1/objects?archived=true e restaure um deles com POST /v1/objects/:id/restore.
Páginas relacionadas
Objetos e adereços
Objeto/adereço
Personagens
Locais
Tarefas
Última atualização
Personagens
Crie, atualize, arquive e restaure personagens via REST, gere candidatos a retrato, expressões, ângulos e clipes de movimento e aprove o retrato-âncora.
Locais
Pela API REST, crie e arquive locais e gere planos de estabelecimento, variações de hora do dia, tempo e ângulo, vistas de 360° e clipes de movimento.