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.
As ferramentas de personagens permitem que um assistente crie e use os personagens da sua biblioteca do Estúdio de personagens: 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 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 essa tarefa 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 ou 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 faça uma busca quando o usuário citar um personagem.
Permissão: assets:read. Créditos: grátis.
| Parâmetro | Tipo | Observações |
|---|---|---|
search | string | Até 5 palavras, com até 200 caracteres. Cada palavra precisa aparecer no nome ou na descrição do personagem, sem diferenciar maiúsculas de minúsculas. Um valor em branco significa nenhuma busca. |
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.
No Nodaro Cloud, o personagem também traz training: o estado do treinamento de alta fidelidade dele, como { status, error, trainedAt, imageCount }. status é um destes: untrained, queued, training, succeeded, failed ou cancelled. Leia-o para acompanhar uma execução de train_character.
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 chamada de visão do Claude Sonnet 4.6 para a descrição, cobrada pelos tokens que usou (como as chamadas de LLM são cobradas). A aprovação nunca é recusada por falta de créditos. Quando o seu saldo é baixo demais para a descrição, a imagem é aprovada mesmo assim e a descrição é pulada. Execute recaption_character depois para escrevê-la.
| Parâmetro | Tipo | Observações |
|---|---|---|
character_id | string | Obrigatório. O personagem. |
candidate_job_id | string | Obrigatório. Uma tarefa concluída de generate_character feita 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 chamada de visão do Claude Sonnet 4.6, cobrada pelos tokens que usou, como a descrição da aprovação.
| 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: gpt-image-2. |
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 tarefa. Para um retrato, passe a tarefa 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” (a cabeça vira devagar para a esquerda, os olhos acompanham a câmera, sorriso suave). |
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 tarefa. O cartão reproduz o clipe quando ele fica pronto.
train_character
Treina um modelo de alta fidelidade de um personagem salvo com as próprias imagens do personagem. Depois disso, um nó Gerar imagem cujo prompt menciona com @ esse único personagem preserva fielmente a identidade dele. Leia Treinamento de personagens para o mesmo recurso no app.
Permissão: workflows:execute e assets:write. Créditos: 1.650 créditos por treinamento. Somente no Nodaro Cloud.
| Parâmetro | Tipo | Observações |
|---|---|---|
id | string | Obrigatório. O ID do personagem, de list_characters. |
selected_image_urls | array | Treina só com estas imagens do personagem, pelo menos 4 distintas. Padrão: todas as imagens elegíveis. |
O personagem precisa de pelo menos 4 imagens distintas: o retrato, as fotos de referência, as expressões, as poses, os ângulos e as variações de iluminação contam.
Retorna: na hora, com jobId, trainingId e triggerWord. O treinamento leva cerca de 15 minutos. Acompanhe-o com get_character, no campo training.
- Recusas. A ferramenta responde
already_training_or_not_foundenquanto um treinamento do personagem está em andamento, einsufficient_training_imagescom menos de 4 imagens. - Créditos. Os créditos são reembolsados quando o treinamento falha ou é cancelado. Treinar de novo um personagem já treinado custa o mesmo valor outra vez.
- Remover um modelo treinado. Nenhuma ferramenta MCP o remove, porque a remoção destrói um treinamento pago e não pode ser desfeita. Use
DELETE /v1/characters/:id/lora,client.characters.deleteLora(id)no SDK ounodaro characters delete-lora <id>na CLI. Veja Treinamento de personagem.
Perguntas frequentes
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.
Um assistente pode treinar um modelo de personagem pelo MCP?
Sim, no Nodaro Cloud. train_character treina um modelo de alta fidelidade de um personagem salvo que tenha pelo menos 4 imagens distintas. Custa 1.650 créditos, reembolsados se o treinamento falhar ou for cancelado.
Páginas relacionadas
Estúdio de personagens
Treinamento de personagens
Personagens consistentes
Personagem
Locais
Última atualização
Música
Crie músicas e instrumentais com o Suno e outros modelos e depois estenda, faça covers e mashups, edite, separe e converta tudo com o MCP do Nodaro.
Locais
Crie locais num assistente de IA, gere e aprove planos de estabelecimento, adicione variações de hora do dia, tempo e ângulo e anime clipes de atmosfera.