# 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. Source: https://nodaro.ai/pt-BR/docs/developers/api/objects 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](https://nodaro.ai/docs/developers/api/authentication). ## Endpoints | Método | Caminho | O que faz | | --- | --- | --- | | `GET` | `/v1/objects` | Lista os seus objetos. | | `GET` | `/v1/objects/:id` | Retorna um objeto com os jobs 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`: os jobs 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. 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** ```bash curl "https://app.nodaro.ai/v1/objects?limit=100" \ -H "Authorization: Bearer $NODARO_API_KEY" ``` **TypeScript SDK** ```ts 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() ``` **CLI** ```bash 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** ```bash 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" }' ``` **TypeScript SDK** ```ts 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 }) ``` **CLI** ```bash nodaro objects create "Antique Lantern" --node-id scripted \ --description "Weathered brass lantern with hand-engraved filigree" \ --category tool --style realistic nodaro objects update --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](https://nodaro.ai/docs/developers/api/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** ```bash 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 }' ``` **TypeScript SDK** ```ts const { jobIds } = await client.objects.generate({ name: 'Antique Lantern', description: 'Weathered brass lantern with hand-engraved filigree', count: 4, }) ``` **CLI** ```bash nodaro objects generate --name "Antique Lantern" --count 1 \ --attach-to-object-id --watch ``` ```json { "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**](https://nodaro.ai/docs/nodes/creative-controls/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 o job terminar. **curl** ```bash 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" }' ``` **TypeScript SDK** ```ts await client.objects.generateAsset({ name: 'Antique Lantern', assetType: 'variations', variant: 'weathered', attachToObjectId: id, attachToColumn: 'variations', attachName: 'weathered', }) ``` **CLI** ```bash nodaro objects generate-asset --asset-type materials --variant gold \ --attach-to-object-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** ```bash 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" }' ``` **TypeScript SDK** ```ts 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', }) ``` **CLI** ```bash 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 --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`, `minimax`, `hailuo-2.3`, `wan-i2v`, `seedance` ou `bytedance-lite`. | | `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: | Model | Maker | Modes | Credits | Details | | --- | --- | --- | --- | --- | | [Kling 2.5 Turbo Pro](https://nodaro.ai/docs/models/video/kling-2-5-turbo-pro) | Kuaishou | Image to video, Text to video | a partir de 121 | Faster Kling — good quality at lower cost. Supports end frame. | | [Kling 2.6](https://nodaro.ai/docs/models/video/kling-2-6) | Kuaishou | Image to video, Text to video | a partir de 152 | Kling 2.6 I2V — strong motion realism. 5s/10s, optional native audio. | | [Kling 3.0](https://nodaro.ai/docs/models/video/kling-3-0) | Kuaishou | Image to video, Text to video | a partir de 297 | Premium Kling 3.0 — variable 3-15s duration, native audio, 720P/1080P. | | [Hailuo 02 I2V Pro](https://nodaro.ai/docs/models/video/hailuo-02-i2v-pro) | MiniMax | Image to video, Text to video | 158 | Hailuo 02 Pro — strong photoreal motion, fixed 5-second clips. Supports end frame. | | [Hailuo 2.3 Standard](https://nodaro.ai/docs/models/video/hailuo-2-3-standard) | MiniMax | Image to video | a partir de 83 | Cheaper Hailuo 2.3 tier — good baseline quality. | | [Wan 2.6 I2V](https://nodaro.ai/docs/models/video/wan-2-6-i2v) | Alibaba | Image to video | a partir de 193 | Wan 2.6 image-to-video — 5/10/15s at 720p/1080p. | | [Bytedance Lite I2V](https://nodaro.ai/docs/models/video/bytedance-lite-i2v) | Bytedance | Image to video, Text to video | 63 | Cheapest Bytedance video tier with end-frame support. | `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** ```bash 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" }' ``` **TypeScript SDK** ```ts const approved = await client.objects.approveMainImage(id, jobIds[1]) if (approved.canonicalDescription === null) { await client.objects.recaption(id) } ``` **CLI** ```bash nodaro objects approve-main-image --candidate-job-id nodaro objects recaption ``` ## Arquivar, restaurar e excluir um objeto | Ação | curl | TypeScript SDK | CLI | | --- | --- | --- | --- | | Arquivar | `DELETE /v1/objects/:id` | `client.objects.delete(id)` | `nodaro objects delete ` | | Restaurar | `POST /v1/objects/:id/restore` | `client.objects.restore(id)` | `nodaro objects restore ` | | Excluir de vez | `DELETE /v1/objects/:id?permanent=true` | `client.objects.permanentDelete(id)` | `nodaro objects delete --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: 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)](https://nodaro.ai/docs/nodes/assets/object) é publicado como app, o objeto vira uma das entradas do app. Envie `"/"` 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](https://nodaro.ai/docs/developers/api/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)](https://nodaro.ai/docs/nodes/image/generate-image) ou [**Gerar vídeo** (Generate Video)](https://nodaro.ai/docs/nodes/video/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](https://nodaro.ai/docs/guides/objects). ## 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: `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](https://nodaro.ai/docs/mcp/tools). ## 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 o primeiro job 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` | Grátis. | | `llm-caption` | 8 créditos por chamada. | ## 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. | ## Frequently asked questions ### 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? Oito modelos de vídeo, pelos IDs de provider kling-turbo (o padrão, Kling 2.5 Turbo Pro), kling, kling-3.0, minimax, hailuo-2.3, wan-i2v, seedance e bytedance-lite. 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.