# Personagens

> Crie personagens num assistente de IA, gere e aprove os retratos, adicione expressões, poses, ângulos e clipes de movimento e reutilize-os como referência.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/characters

As **ferramentas de personagens** permitem que um assistente crie e use os personagens da sua biblioteca do Estúdio de personagens (Character Studio): pessoas ou figuras com aparência fixa, que continuam iguais em todas as imagens e vídeos. O assistente cria um personagem, gera e aprova o retrato dele, adiciona variações como expressões, poses, ângulos e iluminação, anima o personagem em clipes de movimento e passa as imagens dele como referência para outras gerações. Leia [Estúdio de personagens](https://nodaro.ai/docs/guides/character-studio) para fazer o mesmo trabalho no app.

## O ciclo de vida de um personagem
### Crie o personagem
`create_character` salva o nome e a identidade: descrição, gênero, estilo e roupa. O personagem ainda não tem retrato.

### Gere e aprove um retrato
`generate_character` com `kind: "main"` cria um retrato. Execute até gostar de um e depois passe esse job para `approve_portrait`. O retrato aprovado se torna a base do personagem, e um modelo de visão escreve a descrição canônica dele.

### Adicione variações
`generate_character` com `kind: "asset"` e `attach_to_character_id` cria expressões, poses, ângulos da cabeça e do corpo e variações de iluminação a partir do retrato aprovado, e salva cada uma no personagem.

### Anime e reutilize
`generate_character_motion` transforma o personagem em clipes de movimento. `get_character` retorna todas as imagens e clipes, prontos para passar como referência para [`generate_image`](https://nodaro.ai/docs/mcp/tools/image#generate_image) ou [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video).

## `list_characters`
Lista os seus personagens, dos atualizados mais recentemente para os mais antigos, com o nome, a descrição, o retrato, o número de variações de cada tipo e o texto de identidade de cada um. Os personagens arquivados ficam de fora. Sem `search`, a ferramenta retorna só a primeira página, então busque pelo nome quando o usuário citar um personagem.

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

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

**Retorna:** os personagens. Chame `get_character` para obter as URLs das imagens.

## `get_character`
Retorna um personagem completo: cada expressão, pose, movimento, ângulo da cabeça, ângulo do corpo e variação de iluminação, com o nome e a URL. Também retorna as fotos de referência e as URLs de referências da vida real, quando uma variação as tem.

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

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

**Retorna:** o personagem, incluindo `updatedAt` para `update_character`. Um erro quando o personagem não existe ou não é seu.

## `create_character`
Cria um personagem com a identidade dele. Ele ainda não tem retrato: gere um em seguida com `generate_character`.

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

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `name` | string | **Obrigatório.** O nome de exibição, como `Kira`, com até 200 caracteres. Precisa ser único entre os seus personagens ativos; um nome repetido retorna `name_taken`. |
| `description` | string | Quem é o personagem, com até 2.000 caracteres. |
| `gender` | string | Até 50 caracteres. |
| `style` | string | O estilo visual, como `realistic`, `anime`, `3d-pixar` ou `illustration`. |
| `base_outfit` | string | A roupa padrão, com até 1.000 caracteres. |
| `seed_prompt` | string | Um prompt curto que define o primeiro retrato, com até 4.000 caracteres. |
| `identity_lock` | string | O quanto o Estúdio de personagens preserva o rosto nas variações geradas: `off` (padrão), `soft` ou `strict`. |

**Retorna:** o ID do novo personagem.

## `update_character`
Altera a identidade de um personagem. Só são gravados os campos que você informar.

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

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `id` | string | **Obrigatório.** O ID do personagem. |
| `name`, `description`, `gender`, `style`, `base_outfit`, `seed_prompt`, `identity_lock` | | Como em `create_character`. |
| `expected_updated_at` | string | O `updatedAt` de `get_character`. A alteração é recusada quando o personagem mudou desde a sua leitura. |

**Retorna:** uma confirmação, ou um erro de conflito quando `expected_updated_at` está desatualizado.

## `approve_portrait`
Transforma um resultado concluído de `generate_character` no retrato do personagem e faz um modelo de visão descrevê-lo, para preencher a descrição canônica do personagem.

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

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `character_id` | string | **Obrigatório.** O personagem. |
| `candidate_job_id` | string | **Obrigatório.** Um job concluído de `generate_character` feito por você. |

**Retorna:** a URL do retrato e a descrição. Quando a descrição falha, o retrato é definido mesmo assim e a descrição fica vazia; execute `recaption_character`.

## `recaption_character`
Faz o modelo de visão descrever de novo o retrato atual e salva a nova descrição canônica. Use-a depois de trocar o retrato ou quando a descrição não estiver certa.

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

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

**Retorna:** a nova descrição. `400 no_portrait` quando o personagem não tem retrato.

## `generate_character`
Gera um retrato do personagem (`kind: "main"`) ou uma variação dele (`kind: "asset"`).

**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 personagem. |
| `kind` | string | `main` (padrão) para um retrato, ou `asset` para uma variação. |
| `description`, `gender`, `style`, `base_outfit` | string | A identidade, para um retrato. |
| `model` | string | O modelo de imagem. Padrão: `nano-banana`. |
| `asset_type` | string | Obrigatório para `asset`: `expressions`, `poses`, `lighting`, `headAngles`, `bodyAngles` ou `custom`. `angles` é um nome antigo de `headAngles`. |
| `variant` | string | Obrigatório para `asset`: a variação, como `smile` ou `angry` para expressões, `front`, `3/4 left`, `left profile`, `right profile`, `3/4 right` ou `back` para ângulos, `standing` ou `walking` para poses, e `daylight`, `night` ou `dramatic` para iluminação. |
| `attach_to_character_id` | string | Salva o resultado neste personagem e usa o retrato aprovado dele como origem. Sem um retrato aprovado, a chamada retorna `portrait_required`. |
| `attach_to_column` | string | Obrigatório com `attach_to_character_id` para uma variação `custom`: onde salvá-la, como `expressions`, `poses`, `angles`, `body_angles`, `lighting_variations`, `sheets`, `detail_closeups`, `outfit_variations` ou `boards`. |
| `attach_name` | string | O nome da variação salva. Padrão: a variação. |
| `source_image_url` | string | Uma imagem de origem, quando você não anexa o resultado a um personagem. |

**Retorna:** um ID de job. Para um retrato, passe o job para `approve_portrait` quando gostar do resultado.

## `generate_character_motion`
Anima um personagem num clipe de movimento curto, a partir de uma das imagens dele.

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

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `motion_prompt` | string | **Obrigatório.** O que se move e como, com até 2.000 caracteres, por exemplo “slow head turn left, eyes track the camera, soft smile”. |
| `name` | string | **Obrigatório.** O nome do personagem. |
| `attach_to_character_id` | string | Escolhe a imagem de origem no personagem e salva o clipe nos movimentos dele. |
| `source_image_url` | string | Uma imagem de origem à sua escolha. Obrigatório sem `attach_to_character_id`. |
| `provider` | string | `kling` (padrão), `kling-turbo`, `kling-3.0`, `wan-i2v` ou `wan-2.7-i2v`. |
| `attach_name` | string | O nome do movimento salvo, como `walking`. |
| `description`, `motion_description`, `gender`, `style`, `base_outfit` | string | Detalhes opcionais de identidade e de movimento. |

Com `attach_to_character_id`, a imagem de origem é escolhida nesta ordem: o seu `source_image_url`, o ângulo frontal do corpo do personagem, qualquer outro ângulo do corpo e, por fim, o retrato. Uma imagem de corpo inteiro se move muito melhor do que um retrato da cabeça, então gere primeiro os ângulos do corpo.

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

## Frequently asked questions

### Como um assistente cria um personagem consistente no Nodaro?

Ele chama create_character com um nome e uma descrição, gera um retrato com generate_character e aprova o melhor com approve_portrait. O retrato aprovado passa a ser a base de todas as variações e de todos os clipes de movimento do personagem.

### Como uso um personagem salvo numa imagem ou num vídeo?

Encontre-o com list_characters, leia as imagens dele com get_character e passe a URL do retrato, da expressão ou da pose certa em reference_image_urls de generate_image, image_to_image ou generate_video.

### Por que uma variação falha com portrait_required?

As variações usam o retrato aprovado como origem. Primeiro, gere um retrato com kind main e aprove-o com approve_portrait.

### De qual imagem um clipe de movimento deve partir?

Uma imagem de corpo inteiro se move muito melhor do que um retrato da cabeça. Gere primeiro os ângulos do corpo do personagem; depois, generate_character_motion usa automaticamente o ângulo frontal do corpo.