NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

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étodoCaminhoO que faz
GET/v1/objectsLista os seus objetos.
GET/v1/objects/:idRetorna um objeto com as tarefas dele em andamento.
POST/v1/objectsCria um objeto, ou atualiza um objeto quando o corpo tem um id.
DELETE/v1/objects/:idArquiva um objeto. Ele pode ser restaurado.
DELETE/v1/objects/:id?permanent=trueExclui de vez um objeto arquivado e os arquivos dele.
POST/v1/objects/:id/restoreRestaura um objeto arquivado.
POST/v1/generate-objectGera imagens principais candidatas.
POST/v1/generate-object-assetGera uma variação de ângulo, de material, de estado ou personalizada.
POST/v1/generate-object-motionAnima a imagem principal em um clipe de movimento.
POST/v1/objects/:id/approve-main-imageAprova uma candidata como imagem principal e escreve a descrição do objeto.
POST/v1/objects/:id/llm-captionEscreve a descrição de novo a partir da imagem principal atual.

O que um objeto guarda

CampoO que guarda
id, name, descriptionO identificador, o nome de exibição e as notas de identidade.
categoryfurniture, vehicle, weapon, food, clothing, electronics, nature, tool, animal ou other.
stylerealistic, anime, 3d-pixar ou illustration.
sourceImageUrlA imagem principal que serve de âncora, definida quando você aprova uma candidata.
canonicalDescriptionUma descrição visual de cerca de 80 a 120 palavras, escrita pelo Nodaro quando a imagem principal é aprovada. Até lá, é uma string vazia.
styleLockSe as variações são geradas a partir da imagem principal. true por padrão.
angles, materials, variations, motionClipsOs grupos de variações. Cada entrada é { name, url }; motionClips guarda vídeos.
referencePhotosAté 20 fotos do painel de inspiração, cada uma { kind, url }.
pendingJobsSó em GET /v1/objects/:id: as tarefas de variações ainda em execução para este objeto.

Os grupos de variações

GrupoO que mostraVariações predefinidas
anglesO objeto de outro ponto de vistafront, side, top, back, three-quarter, detail, in-context, exploded, perspective
materialsO objeto em outro materialwood, metal, glass, plastic, fabric, stone, ceramic, leather, paper, gold, silver, copper, marble
variationsOutro estado ou estiloclean, weathered, damaged, ornate, minimal, broken, antique, futuristic, holographic, dirty, polished
motionClipsClipes em loop com movimento de câmerarotate-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.

kindPara que serve
frontUma vista frontal limpa.
sideUm perfil lateral, útil para veículos, móveis e armas.
detailUm close de um detalhe marcante, como uma gravação ou uma dobradiça.
contextO objeto no lugar, segurado ou instalado, para dar a escala.
moodBoardA paleta ou a sensação.
otherQualquer 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 --archived

GET /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 false

Uma 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"
  ]
}
CampoO que faz
nameObrigatório. O nome do objeto, de 1 a 200 caracteres.
descriptionNotas de identidade, até 2.000 caracteres.
category, styleA categoria e o estilo visual do objeto.
countQuantas candidatas gerar, de 1 a 10. O padrão é 1.
providerO ID do modelo de imagem. Omita para usar o modelo padrão.
seedPromptHintUm trecho de prompt para incorporar ao prompt, com até 2.000 caracteres, por exemplo antique brass, do seletor Material.
sourceImageUrlUma imagem de partida.
aspectRatioA proporção da imagem principal.
attachToObjectId, expectedUpdatedAtAnexa 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
CampoO que faz
nameObrigatório. O nome do objeto.
assetTypeObrigatório. angles, materials, variations ou custom.
variantObrigatório. A variação a gerar, de 1 a 100 caracteres.
descriptionUma 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, aspectRatioO modelo de imagem, a imagem a variar e a proporção.
attachToObjectId, attachToColumn, attachNamePara 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
CampoO que faz
name, motionPromptObrigatórios. O nome do objeto e o movimento a criar.
sourceImageUrlObrigatório. O quadro inicial.
providerkling-turbo (o padrão), kling, kling-3.0, hailuo-2.3, wan-i2v ou seedance-2-mini.
aspectRatio1:1 (o padrão, um quadro de produto centralizado), 3:4, 16:9, 9:16 ou 4:3.
refineFromVideoUrlUm 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, attachNameO objeto e o nome do clipe em motionClips.

O preço de um clipe é o preço de imagem para vídeo do modelo:

ModeloDesenvolvedorModosCréditosDetalhes
Kling 2.5 Turbo ProKuaishouImagem para vídeo, Texto para vídeoa partir de 121Kling mais rápido — boa qualidade por um custo menor. Aceita quadro final.
Kling 2.6KuaishouImagem para vídeo, Texto para vídeoa partir de 152Kling 2.6 I2V — movimento muito realista. Clipes de 5 ou 10 s, com áudio nativo opcional.
Kling 3.0KuaishouImagem para vídeo, Texto para vídeoa partir de 297Kling 3.0 de alta qualidade — duração variável de 3 a 15 s, áudio nativo, 720P/1080P.
Hailuo 2.3 StandardMiniMaxImagem para vídeoa partir de 83Nível mais barato do Hailuo 2.3 — boa qualidade de base.
Wan 2.6 I2VAlibabaImagem para vídeoa partir de 193Wan 2.6 de imagem para vídeo — 5, 10 ou 15 s em 720p/1080p.
Seedance 2 MiniBytedanceImagem para vídeo, Texto para vídeoa partir de 132Ní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çãocurlTypeScript SDKCLI
ArquivarDELETE /v1/objects/:idclient.objects.delete(id)nodaro objects delete <id>
RestaurarPOST /v1/objects/:id/restoreclient.objects.restore(id)nodaro objects restore <id>
Excluir de vezDELETE /v1/objects/:id?permanent=trueclient.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 retorna 400 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

FerramentaO que faz
list_objects, get_objectEncontra um objeto e lê as URLs das variações dele.
generate_objectGera uma imagem principal ou uma variação.
approve_object_main_image, recaption_objectAprova uma imagem principal ou escreve de novo a descrição do objeto.
generate_object_motionAnima 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

RotaPreço no Nodaro Cloud
POST /v1/generate-objectO preço do modelo de imagem vezes count, reservado para todas as candidatas antes de a primeira tarefa começar.
POST /v1/generate-object-assetO preço do modelo de imagem, por variação.
POST /v1/generate-object-motionO preço de imagem para vídeo do modelo de vídeo, por clipe.
approve-main-imageA aprovação é gratuita. A descrição dela é uma chamada de visão, cobrada pelos tokens que usou.
llm-captionA mesma chamada de visão, cobrada da mesma forma.

Erros

StatusCódigoSignificado
400validation_errorUm campo está ausente ou é inválido.
400not_archivedUma exclusão permanente foi enviada para um objeto que não está arquivado.
400main_image_requiredllm-caption foi chamado antes de o objeto ter uma imagem principal.
401unauthorizedO token está ausente, é inválido ou foi revogado.
402insufficient_creditsSó no Nodaro Cloud. A conta não tem créditos para cobrir a reserva.
404not_foundNenhum objeto ativo com esse ID pertence a você.
409concurrent_modificationexpectedUpdatedAt 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.

Última atualização

Nesta página