NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
Referência das ferramentas

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âmetroTipoObservações
searchstringAté 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.
limitintegerDe 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âmetroTipoObservações
idstringObrigató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âmetroTipoObservações
namestringObrigató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.
descriptionstringQuem é o personagem, com até 2.000 caracteres.
genderstringAté 50 caracteres.
stylestringO estilo visual, como realistic, anime, 3d-pixar ou illustration.
base_outfitstringA roupa padrão, com até 1.000 caracteres.
seed_promptstringUm prompt curto que define o primeiro retrato, com até 4.000 caracteres.
identity_lockstringO 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âmetroTipoObservações
idstringObrigatório. O ID do personagem.
name, description, gender, style, base_outfit, seed_prompt, identity_lockComo em create_character.
expected_updated_atstringO 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âmetroTipoObservações
character_idstringObrigatório. O personagem.
candidate_job_idstringObrigató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âmetroTipoObservações
idstringObrigató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âmetroTipoObservações
namestringObrigatório. O nome do personagem.
kindstringmain (padrão) para um retrato, ou asset para uma variação.
description, gender, style, base_outfitstringA identidade, para um retrato.
modelstringO modelo de imagem. Padrão: gpt-image-2.
asset_typestringObrigatório para asset: expressions, poses, lighting, headAngles, bodyAngles ou custom. angles é um nome antigo de headAngles.
variantstringObrigató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_idstringSalva o resultado neste personagem e usa o retrato aprovado dele como origem. Sem um retrato aprovado, a chamada retorna portrait_required.
attach_to_columnstringObrigató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_namestringO nome da variação salva. Padrão: a variação.
source_image_urlstringUma 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âmetroTipoObservações
motion_promptstringObrigató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).
namestringObrigatório. O nome do personagem.
attach_to_character_idstringEscolhe a imagem de origem no personagem e salva o clipe nos movimentos dele.
source_image_urlstringUma imagem de origem à sua escolha. Obrigatório sem attach_to_character_id.
providerstringkling (padrão), kling-turbo, kling-3.0, wan-i2v ou wan-2.7-i2v.
attach_namestringO nome do movimento salvo, como walking.
description, motion_description, gender, style, base_outfitstringDetalhes 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âmetroTipoObservações
idstringObrigatório. O ID do personagem, de list_characters.
selected_image_urlsarrayTreina 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_found enquanto um treinamento do personagem está em andamento, e insufficient_training_images com 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 ou nodaro 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.

Última atualização

Nesta página