Criaturas

A API de criaturas gerencia animais e outros seres não humanos com uma aparência fixa: um animal de estimação, um dragão, um mascote. Uma criatura tem uma imagem principal aprovada, uma descrição escrita e imagens de variações. Os nós de imagem e de vídeo reaproveitam a criatura para que ela tenha a mesma aparência em todas as tomadas. As criaturas funcionam como os objetos, com três acréscimos: uma species em texto livre, painéis com nome e uma voz opcional.

As rotas funcionam em todas as edições e aceitam um token Bearer: um token de API pessoal (ndr_…), um token de app OAuth (ndr_app_…) ou o token da sua sessão na Community Edition. Veja Autenticação. A CLI não tem comandos de criaturas; use REST, o SDK ou o MCP.

Endpoints

O que uma criatura contém

Listar e ler criaturas

GET /v1/creatures retorna as suas criaturas ativas. A rota aceita os mesmos parâmetros da lista de objetos: archived=true, projectId e um limit opcional (no máximo 500) com cursor. Sem limit, você recebe a lista completa. Com ele, recebe uma página e um nextCursor para enviar de volta até ele ser null.

GET /v1/creatures/:id retorna uma criatura. Uma criatura arquivada retorna 404 not_found.

curl "https://app.nodaro.ai/v1/creatures?limit=50" \
  -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 { creatures, nextCursor } = await client.creatures.list({ limit: 50 })
const { creatures: archived } = await client.creatures.listArchived()

Criar ou atualizar uma criatura

POST /v1/creatures cria uma criatura quando o corpo não tem id e a atualiza quando tem. Uma criação precisa de nodeId e name; use qualquer rótulo em nodeId, como "scripted", quando não houver um nó no canvas. Uma criação retorna { id }, e uma atualização retorna { id, updatedAt }.

Em uma atualização, só os campos que você envia são gravados. Uma atualização nunca grava os grupos de mídias, mas boards é você quem define: envie a lista inteira para substituí-la. Envie expectedUpdatedAt para que a atualização seja recusada com 409 concurrent_modification quando alguém tiver alterado a criatura depois que você a leu.

curl -X POST https://app.nodaro.ai/v1/creatures \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Ember",
    "species": "red dragon",
    "description": "Young dragon with copper scales and a chipped left horn",
    "style": "realistic"
  }'

const { id } = await client.creatures.create({
  nodeId: 'scripted',
  name: 'Ember',
  species: 'red dragon',
  description: 'Young dragon with copper scales and a chipped left horn',
  style: 'realistic',
})

await client.creatures.update(id, {
  voice: { voiceId: 'Callum', voiceName: 'Callum', traits: 'gravelly, slow', voiceType: 'premade' },
})

Painéis

Um painel é uma folha de referência densa da criatura para um visual ou um clima. Renderize um painel com a predefinição generate-image/creature-board do Gerar imagem (Generate Image) e salve a URL dele em boards. Veja Predefinições e Painéis de referência e grades de consistência.

Gerar imagens principais e variações

POST /v1/generate-creature inicia um job por candidato e retorna jobIds; uma requisição de um único candidato também retorna jobId. Com attachToCreatureId e count igual a 1, o resultado vira a imagem principal quando o job termina. Com vários candidatos, nada é anexado; aprove o que preferir.

POST /v1/generate-creature-asset gera uma variação e retorna { jobId }. assetType é angles, poses, variations ou custom. Envie attachToCreatureId, attachToColumn (angles, poses ou variations) e attachName para acrescentar o resultado a um grupo; uma variação custom precisa indicar a coluna.

curl -X POST https://app.nodaro.ai/v1/generate-creature \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "species": "red dragon",
    "count": 1,
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a"
  }'

curl -X POST https://app.nodaro.ai/v1/generate-creature-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "assetType": "poses",
    "variant": "wings spread",
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
    "attachToColumn": "poses",
    "attachName": "wings spread"
  }'

const { jobIds } = await client.creatures.generate({
  name: 'Ember',
  species: 'red dragon',
  count: 4,
})

await client.creatures.generateAsset({
  name: 'Ember',
  assetType: 'poses',
  variant: 'wings spread',
  attachToCreatureId: id,
  attachToColumn: 'poses',
  attachName: 'wings spread',
})

Animar a imagem principal

POST /v1/generate-creature-motion transforma uma imagem da criatura em um clipe, como um loop em repouso, uma caminhada à espreita ou um ataque, e retorna { jobId }. sourceImageUrl é obrigatório. Com attachToCreatureId e attachName, o clipe é acrescentado a motionClips.

curl -X POST https://app.nodaro.ai/v1/generate-creature-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "motionPrompt": "slow idle breathing, tail sways, smoke curls from the nostrils",
    "sourceImageUrl": "https://cdn.nodaro.ai/creatures/ember-main.png",
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
    "attachName": "idle"
  }'

await client.creatures.generateMotion({
  name: 'Ember',
  motionPrompt: 'slow idle breathing, tail sways, smoke curls from the nostrils',
  sourceImageUrl: ember.sourceImageUrl!,
  provider: 'kling-turbo',
  duration: 5,
  attachToCreatureId: id,
  attachName: 'idle',
})

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/creatures/:id/approve-main-image com { candidateJobId, expectedUpdatedAt? } define um candidato concluído como imagem principal e escreve canonicalDescription na mesma chamada. A rota retorna { sourceImageUrl, canonicalDescription }. Quando a escrita da descrição falha, a imagem principal continua definida e a descrição fica vazia; o SDK retorna null.

POST /v1/creatures/:id/llm-caption escreve a descrição de novo e retorna { canonicalDescription }. A rota responde 502 quando não consegue escrever a descrição e 400 main_image_required quando ainda não há imagem principal. As duas rotas podem ser repetidas com segurança. Aprovar é gratuito. Cada chamada de llm-caption custa 8 créditos, e uma chamada com falha (502) é reembolsada.

curl -X POST https://app.nodaro.ai/v1/creatures/0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "1c9e7a5b-3d2f-4c8e-9a4b-8f6d2e1a4c3b" }'

const ember = await client.creatures.get(id)
const approved = await client.creatures.approveMainImage(id, jobIds[0], ember.updatedAt)
if (approved.canonicalDescription === null) await client.creatures.recaption(id)

Arquivar, restaurar e excluir uma criatura

Arquivar retorna { success: true, archived: true }, e repetir a ação não muda nada. Restaurar retorna { id, name }, com o sufixo (restored) quando uma criatura ativa tem o mesmo nome. Excluir para sempre só funciona em uma criatura arquivada (caso contrário, 400 not_archived) e remove a criatura e todos os arquivos a que ela faz referência.

Fazer uma criatura falar

Nenhuma rota específica de criatura é necessária. Gere a fala com a voz da criatura e, depois, sincronize os lábios da imagem principal com ela:

const speech = await client.nodes.runAndWait('text-to-speech', {
  text: 'I knocked the vase off the shelf. I regret nothing.',
  voice: ember.voice!.voiceId,
  provider: ember.voice!.ttsProvider,
  voiceType: ember.voice!.voiceType,
})

const clip = await client.nodes.runAndWait('lip-sync', {
  imageUrl: ember.sourceImageUrl!,
  audioUrl: speech.audioUrl,
  provider: 'kling-avatar',
})

Veja Executar um único nó para nodes.runAndWait e as rotas POST /v1/<node-type> diretas.

Colocar uma criatura em uma tomada

No Gerar imagem, envie a criatura como uma referência estruturada com source: "wired-creature". A criatura é anexada automaticamente, com um texto que preserva a anatomia, as marcas e a coloração dela. Você também pode citá-la no prompt: @ember:1 a coloca onde você digitar. Um papel escolhe o que aproveitar da imagem, por exemplo @ember:1:markings. Os papéis são creature, anatomy, markings, pose, color e style.

{
  "prompt": "a wide shot of @ember:1 landing on the castle wall",
  "connectedReferences": [
    { "id": "cr-1", "defaultName": "Ember", "source": "wired-creature", "url": "https://cdn.nodaro.ai/creatures/ember-main.png" }
  ]
}

Em um workflow, conecte em vez disso o nó Animal/criatura (Animal/Creature Asset) ao nó de imagem ou de vídeo.

Uso pelo MCP

Veja a Referência das ferramentas MCP.

Créditos

No Nodaro Cloud, uma requisição de imagem principal custa o preço do modelo de imagem vezes count, reservado antes de o primeiro job começar. Uma variação custa o preço do modelo de imagem, e um clipe de movimento, o preço de imagem para vídeo do modelo de vídeo. A aprovação e a descrição dela são gratuitas. Cada chamada de llm-caption custa 8 créditos, e uma chamada com falha é reembolsada.

Erros