Objetos

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

O que um objeto guarda

Os grupos de variações

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.

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

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 um job 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 }.

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 um job por candidata e retorna jobIds na hora, um ID por candidata. Uma requisição com uma única candidata também retorna jobId. Consulte os jobs periodicamente com a API de jobs.

Com attachToObjectId e count igual a 1, o resultado vira a imagem principal do objeto quando o job 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"
  ]
}

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 o job 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

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

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

seedance (Seedance 1.5 Pro) é um modelo mais antigo. As rotas ainda o aceitam, mas o catálogo de modelos (GET /v1/models) não o lista mais, por isso a tabela não tem uma linha para ele.

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

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>

Arquivar, restaurar e excluir um objeto

• 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: a imagem principal, as variações, os clipes e as fotos de referência. 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 (Object/Props Asset) é 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 (Generate Image) ou Gerar vídeo (Generate Video); 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” seleciona materials/gold. Veja Objetos e adereços.

Usar pelo MCP

Não há ferramentas MCP para criar, atualizar, arquivar, restaurar ou excluir objetos: generate_object cria objetos, e as outras alterações passam pela API REST, pelo SDK ou pela CLI. Veja a Referência das ferramentas MCP.

Créditos

Erros