# Objetos e criaturas

> Liste e leia seus objetos e criaturas, gere imagens e variações, aprove imagens principais e anime clipes de rotação e de repouso num assistente de IA.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/objects-and-creatures

As **ferramentas de objetos e criaturas** permitem que um assistente use os adereços, produtos e criaturas da sua biblioteca: itens e seres com aparência fixa, que continuam iguais em todas as tomadas. O assistente os lista e lê, gera imagens e variações, aprova imagens principais e anima clipes de movimento curtos. Objetos e criaturas funcionam do mesmo jeito; as criaturas acrescentam uma espécie em texto livre. Leia [Objetos e adereços](https://nodaro.ai/docs/guides/objects) e [Animais e criaturas](https://nodaro.ai/docs/guides/creatures) para fazer o mesmo trabalho no app.

Objetos e criaturas são criados no app. Nenhuma ferramenta MCP os cria.

## Ferramentas de objetos
### `list_objects`
Lista os seus objetos: adereços, acessórios e itens físicos que você reutiliza entre tomadas. Cada linha tem o nome, a descrição, a imagem principal e o número de variações. Dos mais recentes para os mais antigos.

**Permissão:** `assets:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `search` | string | Parte do nome do objeto, sem diferenciar maiúsculas de minúsculas, com até 100 caracteres. Use-o quando o usuário citar um objeto pelo nome. |
| `limit` | integer | De 1 a 100. Padrão: `50`. |

**Retorna:** os objetos. Chame `get_object` para obter as URLs das variações.

### `get_object`
Retorna um objeto completo: cada variação, com o nome e a URL, e as fotos de referência.

**Permissão:** `assets:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `id` | string | **Obrigatório.** O ID do objeto, de `list_objects`. |

**Retorna:** o objeto. Um erro quando ele não existe ou não é seu.

### `generate_object`
Gera uma imagem de um objeto (`kind: "main"`) ou uma variação (`kind: "asset"`). O resultado não é salvo num objeto.

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo de imagem.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `name` | string | **Obrigatório.** O nome do objeto. |
| `kind` | string | `main` (padrão) ou `asset`. |
| `description`, `style` | string | A aparência do objeto. |
| `category` | string | `furniture`, `vehicle`, `weapon`, `food`, `clothing`, `electronics`, `nature`, `tool`, `animal` ou `other`. |
| `asset_type` | string | Para `asset`: `angles`, `materials`, `variations` ou `custom`. |
| `variant` | string | Para `asset`: por exemplo `front`, `wood` ou `weathered`. |
| `model` | string | O modelo de imagem. Padrão: `nano-banana`. |
| `source_image_url` | string | Uma imagem de origem. |

**Retorna:** um ID de job.

### `approve_object_main_image`
Transforma um candidato concluído na imagem principal do objeto e faz um modelo de visão descrever a forma, o material, o estado e a finalidade dele na descrição canônica.

**Permissão:** `assets:write`. **Créditos:** uma execução curta de LLM para a descrição.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `object_id` | string | **Obrigatório.** O objeto. |
| `candidate_job_id` | string | **Obrigatório.** Um job de imagem concluído feito por você e gerado para este objeto. Um job feito para outro objeto retorna `candidate_object_mismatch`. |
| `expected_updated_at` | string | O `updatedAt` do objeto. Quando o objeto mudou desde então, a chamada retorna `concurrent_modification` com o novo valor. |

**Retorna:** a URL da imagem principal e a descrição. Quando a descrição falha, a imagem é definida mesmo assim e a descrição fica vazia; execute `recaption_object`.

### `recaption_object`
Faz o modelo de visão descrever de novo a imagem principal atual, em cerca de 80 a 120 palavras, e salva o texto como descrição canônica.

**Permissão:** `assets:write`. **Créditos:** uma execução curta de LLM.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `object_id` | string | **Obrigatório.** O objeto. |

**Retorna:** a nova descrição. `main_image_required` quando o objeto não tem imagem principal, e `caption_failed` quando a descrição falha.

### `generate_object_motion`
Anima um objeto num clipe curto, como “slow 360-degree rotation”, “object hovering with subtle bob” ou “parallax pan from left to right”.

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo de vídeo. O padrão, Kling 2.5 Turbo Pro, faz um clipe de 5 segundos por 138 créditos.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `motion_prompt` | string | **Obrigatório.** O movimento do objeto ou da câmera, com até 2.000 caracteres. |
| `source_image_url` | string | **Obrigatório.** O primeiro quadro, normalmente a imagem principal aprovada do objeto. |
| `name` | string | **Obrigatório.** O nome do objeto, usado como contexto no prompt. |
| `provider` | string | `kling-turbo` (padrão), `kling`, `kling-3.0`, `minimax`, `hailuo-2.3`, `wan-i2v`, `seedance` ou `bytedance-lite`. |
| `aspect_ratio` | string | `1:1` (padrão, para enquadramento de produto), `3:4`, `16:9`, `9:16` ou `4:3`. |
| `attach_to_object_id` | string | Salva o clipe nos clipes de movimento do objeto. A posse do objeto é verificada antes que qualquer crédito seja reservado. |
| `attach_name` | string | O nome do clipe salvo. |
| `refine_from_video_url` | string | Refina um clipe existente com um novo prompt, como vídeo para vídeo, por exemplo “same shot but faster rotation”. |
| `canonical_description`, `category`, `style` | string | Contexto extra para o prompt. |

**Retorna:** um ID de job. O cartão reproduz o clipe quando ele fica pronto.

## Ferramentas de criaturas
### `list_creatures`
Lista as suas criaturas: animais e seres não humanos com aparência fixa. Cada linha tem o nome, a descrição, a imagem principal e o número de variações. Das mais recentes para as mais antigas.

**Permissão:** `assets:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `search` | string | Parte do nome da criatura, sem diferenciar maiúsculas de minúsculas, com até 100 caracteres. |
| `limit` | integer | De 1 a 100. Padrão: `50`. |

**Retorna:** as criaturas. Chame `get_creature` para obter as URLs das variações.

### `get_creature`
Retorna uma criatura completa: cada variação, com o nome e a URL, as fotos de referência e a voz salva dela.

**Permissão:** `assets:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `id` | string | **Obrigatório.** O ID da criatura, de `list_creatures`. |

**Retorna:** a criatura. Um erro quando ela não existe ou não é sua.

### `generate_creature`
Gera uma imagem de uma criatura (`kind: "main"`) ou uma variação (`kind: "asset"`). O resultado não é salvo numa criatura.

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo de imagem.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `name` | string | **Obrigatório.** O nome da criatura. |
| `kind` | string | `main` (padrão) ou `asset`. |
| `species` | string | Texto livre, como `dragon`, `wolf` ou `griffin`, com até 200 caracteres. |
| `category` | string | Texto livre, como `mammal`, `mythical` ou `reptile`. |
| `style` | string | Texto livre, como `realistic`, `anime`, `3d-pixar` ou `illustration`. |
| `description` | string | A aparência da criatura. |
| `asset_type` | string | Para `asset`: `angles`, `poses`, `variations` ou `custom`. |
| `variant` | string | Para `asset`: por exemplo `front`, `standing` ou `weathered`. |
| `model` | string | O modelo de imagem. Padrão: `nano-banana`. |
| `source_image_url` | string | Uma imagem de origem. |

**Retorna:** um ID de job.

### `approve_creature_main_image`
Transforma um candidato concluído na imagem principal da criatura e faz um modelo de visão descrever a espécie, a anatomia, a coloração e o estado dela na descrição canônica.

**Permissão:** `assets:write`. **Créditos:** uma execução curta de LLM para a descrição.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `creature_id` | string | **Obrigatório.** A criatura. |
| `candidate_job_id` | string | **Obrigatório.** Um job de imagem concluído feito por você e gerado para esta criatura. Um job feito para outra criatura retorna `candidate_creature_mismatch`. |
| `expected_updated_at` | string | O `updatedAt` da criatura. Quando a criatura mudou desde então, a chamada retorna `concurrent_modification`. |

**Retorna:** a URL da imagem principal e a descrição. Quando a descrição falha, execute `recaption_creature`.

### `recaption_creature`
Faz o modelo de visão descrever de novo a imagem principal atual, em cerca de 80 a 120 palavras, e salva o texto como descrição canônica.

**Permissão:** `assets:write`. **Créditos:** uma execução curta de LLM.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `creature_id` | string | **Obrigatório.** A criatura. |

**Retorna:** a nova descrição. `main_image_required` quando a criatura não tem imagem principal, e `caption_failed` quando a descrição falha.

### `generate_creature_motion`
Anima uma criatura num clipe curto de repouso, como “creature breathing with subtle idle sway”, uma caminhada furtiva, um bater de asas ou uma panorâmica com paralaxe.

**Permissão:** `workflows:execute`. **Créditos:** o preço do modelo de vídeo. O padrão, Kling 2.5 Turbo Pro, faz um clipe de 5 segundos por 138 créditos.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `motion_prompt` | string | **Obrigatório.** O movimento da criatura ou da câmera, com até 2.000 caracteres. |
| `source_image_url` | string | **Obrigatório.** O primeiro quadro, normalmente a imagem principal aprovada da criatura. |
| `name` | string | **Obrigatório.** O nome da criatura. |
| `provider` | string | `kling-turbo` (padrão), `kling`, `kling-3.0`, `minimax`, `hailuo-2.3`, `wan-i2v`, `seedance` ou `bytedance-lite`. |
| `aspect_ratio` | string | `1:1` (padrão), `3:4`, `16:9`, `9:16` ou `4:3`. |
| `attach_to_creature_id` | string | Salva o clipe nos clipes de movimento da criatura. A posse da criatura é verificada antes que qualquer crédito seja reservado. |
| `attach_name` | string | O nome do clipe salvo. |
| `refine_from_video_url` | string | Refina um clipe existente com um novo prompt, como vídeo para vídeo. |
| `canonical_description`, `category`, `style` | string | Contexto extra para o prompt. |

**Retorna:** um ID de job. O cartão reproduz o clipe quando ele fica pronto.

## Frequently asked questions

### Um assistente pode criar um novo objeto ou uma nova criatura?

Não como um registro salvo. Não existe ferramenta de criação de objetos nem de criaturas; crie-os no app. Depois, o assistente pode listá-los, lê-los, gerar imagens e clipes para eles e aprovar as imagens principais feitas para eles.

### Por que a aprovação de uma imagem principal falha com um erro de incompatibilidade?

O job candidato precisa ter sido gerado para aquele objeto ou aquela criatura. Um candidato feito para outro registro, ou sem vínculo com nenhum, retorna candidate_object_mismatch ou candidate_creature_mismatch.

### Que clipes de movimento posso fazer de um produto?

Clipes curtos, como uma rotação lenta de 360 graus, um objeto flutuando com uma leve oscilação ou uma panorâmica com paralaxe. generate_object_motion usa enquadramento quadrado e o Kling 2.5 Turbo Pro por padrão.

### Qual é a diferença entre um objeto e uma criatura?

Um objeto é um adereço, um produto, um veículo ou outro item físico. Uma criatura é um animal ou um ser não humano, com uma espécie em texto livre, como dragão ou lobo, e variações de pose em vez de variações de material.