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

Treinamento de personagem

Treine um modelo de alta fidelidade de um personagem via REST, consulte o treinamento periodicamente, remova o modelo e saiba quando o Gerar imagem o usa.

Disponível em Nodaro Cloud

O treinamento de personagem cria um modelo dedicado de um personagem a partir das imagens dele, para obter a semelhança mais fiel no Gerar imagem. Você inicia um treinamento com uma chamada, consulta o treinamento periodicamente até ele terminar e remove o modelo quando não precisar mais dele. Depois do treinamento, o Gerar imagem usa o modelo treinado automaticamente sempre que um prompt menciona esse personagem.

O treinamento de personagem roda só no Nodaro Cloud. Nas instalações auto-hospedadas, as rotas não existem e respondem 404. Em uma instalação auto-hospedada, mantenha um personagem consistente com o retrato aprovado e as imagens de referência dele, como descrito em Personagens. As rotas aceitam um token Bearer e só agem sobre os seus próprios personagens. Veja Autenticação.

O SDK encapsula as rotas como client.characters.train, trainingStatus e deleteLora. Na CLI, use nodaro characters train, training e delete-lora. Um assistente de IA conectado pelo MCP inicia um treinamento com train_character e o acompanha com get_character. Remover um modelo treinado não é uma ferramenta do MCP.

Com um token de app OAuth, iniciar um treinamento e remover um modelo treinado exigem assets:write, o mesmo escopo de criar ou excluir o personagem. Sem ele, as rotas respondem 403 insufficient_scope antes de qualquer reserva. A leitura do status não exige escopo. Uma sessão ou um token de API pessoal não exige escopo.

Endpoints

MétodoCaminhoO que faz
POST/v1/characters/:id/trainInicia um treinamento. Reserva 1.650 créditos.
GET/v1/characters/:id/trainingRetorna o status do treinamento.
DELETE/v1/characters/:id/loraCancela um treinamento em andamento ou remove o modelo treinado.

Antes de treinar

O personagem precisa de pelo menos 4 imagens diferentes. Por padrão, o Nodaro reúne as imagens do personagem nesta ordem, remove as duplicatas e treina com até 20:

  1. O retrato aprovado.
  2. As fotos de referência.
  3. As expressões, as poses, os ângulos da cabeça e os ângulos do corpo.
  4. As variações de iluminação.

Para treinar com um subconjunto, envie { "selectedImageUrls": [...] } no corpo: até 200 URLs de imagens do próprio personagem. O treinamento então usa apenas essas, e pelo menos 4 precisam restar. Uma lista omitida ou vazia significa todas as imagens elegíveis.

As folhas de personagem não contam, porque as vistas delas repetem os ângulos. Quando um personagem tem menos de 4 imagens, gere primeiro alguns ângulos e expressões com POST /v1/generate-character-asset. Veja Personagens.

Iniciar um treinamento

POST /v1/characters/:id/train reserva 1.650 créditos e inicia o treinamento. A rota responde 202 com o ID da tarefa do treinamento, o ID do treinamento e a palavra-gatilho do personagem. Você nunca precisa digitar a palavra-gatilho: o Nodaro a adiciona aos prompts por você.

curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/train \
  -H "Authorization: Bearer $NODARO_API_KEY"

# Or train on a subset of the character's images
curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/train \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selectedImageUrls": ["https://cdn.nodaro.ai/characters/kira-portrait.png", "https://cdn.nodaro.ai/characters/kira-smile.png", "https://cdn.nodaro.ai/characters/kira-left.png", "https://cdn.nodaro.ai/characters/kira-right.png"]}'
import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const training = await client.characters.train(characterId)
// Or a subset: client.characters.train(characterId, { selectedImageUrls: [...] })
{
  "jobId": "7a9c1e3b-5d2f-4b8a-9c6e-1f3d5b7a9c2e",
  "trainingId": "q4m8x2k6p1",
  "triggerWord": "TOK_kira_a1b2c3"
}

A tarefa do treinamento, jobId, termina como completed, failed ou cancelled junto com o treinamento, então você também pode acompanhá-la com GET /v1/jobs/:id/status.

Um clique duplo é seguro: enquanto um treinamento está na fila ou em execução, outro início responde 409 already_training_or_not_found e não reserva nada. Cada token pode iniciar 3 treinamentos por minuto.

Acompanhar o treinamento

GET /v1/characters/:id/training retorna o estado do treinamento. Um treinamento leva cerca de 15 minutos. Consulte periodicamente, mais ou menos a cada 10 segundos. O SDK não tem uma função auxiliar de espera.

curl https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/training \
  -H "Authorization: Bearer $NODARO_API_KEY"
let training = await client.characters.trainingStatus(characterId)
while (training.status === 'queued' || training.status === 'training') {
  await new Promise((resolve) => setTimeout(resolve, 10_000))
  training = await client.characters.trainingStatus(characterId)
}
if (training.status !== 'succeeded') console.warn(training.status, training.error)
{
  "status": "succeeded",
  "trainingId": "q4m8x2k6p1",
  "error": null,
  "trainedAt": "2026-09-20T11:42:08Z",
  "version": "b81f4c0e9d27",
  "triggerWord": "TOK_kira_a1b2c3",
  "imageCount": 12
}
CampoO que contém
statusuntrained, queued, training, succeeded, failed ou cancelled. untrained significa que nunca houve treinamento, que o modelo foi removido ou que um treinamento não pôde ser iniciado.
trainingIdO treinamento atual ou o último, ou null.
errorPor que o treinamento falhou, ou null.
trainedAtQuando o último treinamento bem-sucedido terminou, ou null.
versionA versão do modelo do último treinamento bem-sucedido, ou null.
triggerWordA palavra que invoca o personagem no modelo treinado, ou null.
imageCountQuantas imagens o treinamento mais recente usou, ou null.

A geração usa o modelo treinado apenas enquanto status é succeeded. trainedAt e version continuam definidos durante um novo treinamento, um treinamento que falhou ou foi cancelado, ou um que não pôde ser iniciado, mas o modelo não é usado em nenhum desses estados. Um personagem que não é seu, ou que está arquivado, responde 404 not_found.

Gerar imagens com o modelo treinado

Quando o status for succeeded, execute o Gerar imagem com um prompt que mencione exatamente um personagem treinado com @ e com esse personagem conectado ao nó. O Nodaro então usa o modelo treinado em vez do modelo selecionado e das imagens de referência:

  • Automático. O Nodaro coloca a palavra-gatilho no início do prompt para você e remove do texto as suas menções com @.
  • 22 créditos por imagem. O preço do modelo treinado substitui o preço do modelo selecionado.
  • Um personagem treinado por vez. Quando o prompt menciona dois ou mais personagens treinados, o Gerar imagem volta a usar o modelo selecionado com imagens de referência.
  • Só no Gerar imagem. Outros nós, como o Modificar imagem e os nós de vídeo, continuam usando as imagens de referência do personagem.

Veja Executar um único nó para a requisição do Gerar imagem e Treinamento de personagens para o mesmo recurso no editor.

Treinar de novo ou remover o modelo

  • Treinar novamente. Inicie um treinamento outra vez a qualquer momento depois que um treinamento tiver sido concluído, falhado ou cancelado. Cada vez custa 1.650 créditos e substitui o modelo anterior.
  • Remover. DELETE /v1/characters/:id/lora cancela um treinamento em andamento e reembolsa os créditos dele, exclui o modelo treinado e limpa os campos de treinamento do personagem. O status passa a ser untrained. A rota retorna { ok: true }, e isso não pode ser desfeito. As gerações voltam a usar as imagens de referência.
  • Arquivar o personagem. Arquivar o personagem também cancela um treinamento em andamento, reembolsa os créditos dele e exclui o modelo treinado.
curl -X DELETE https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/lora \
  -H "Authorization: Bearer $NODARO_API_KEY"

Créditos

AçãoCréditos
Um treinamento1.650, reembolsados quando o treinamento falha ou é cancelado.
Um novo treinamento1.650 a cada vez.
Uma imagem do modelo treinado22 por imagem, em vez do preço do modelo selecionado.

Veja Créditos para saldos e transações.

Erros

StatusCódigoSignificado
400insufficient_training_imagesO personagem tem menos de 4 imagens diferentes. O count e a message da resposta dizem quantas ele tem. Adicione ângulos ou expressões e tente de novo.
400—Um ID ou um selectedImageUrls malformado. O corpo é { "message", "issues": [...] }.
401unauthorizedO token está ausente, é inválido ou foi revogado.
402insufficient_creditsA conta não cobre os 1.650 créditos. required e balance vêm na resposta.
403insufficient_scopeUm token de app OAuth sem assets:write.
404not_foundNenhum personagem com esse ID pertence a você, o personagem está arquivado, ou a instância não é o Nodaro Cloud.
409already_training_or_not_foundJá há um treinamento na fila ou em execução para este personagem, ou o personagem não é seu ou está arquivado.
422job_blockedA política de tarefas da implantação recusou o treinamento.
429—Mais de 3 inícios de treinamento em um minuto com este token.
500claim_failedNão foi possível reivindicar o treinamento. Nada foi iniciado: tente de novo.
502training_dispatch_failedNão foi possível iniciar o treinamento. Os créditos são reembolsados, e o status passa a ser untrained.
503public_url_not_configured, price_not_configuredO treinamento não está configurado nesta instância.
503dedup_race_winner_unresolvableUma duplicata da requisição estava em andamento e o resultado dela não pôde ser lido. Esta requisição não reservou nada: leia o status antes de tentar de novo.

As recusas que essas rotas escrevem por conta própria usam um formato de corpo mais antigo: o código é uma string simples, { "error": "<code>" }, às vezes com uma message no nível superior. As recusas de escopo, de créditos, de limite de taxa e de política de tarefas usam o envelope habitual { "error": { "code", "message" } }. O SDK lê os dois formatos em NodaroError.code e .message.

Perguntas frequentes

De quantas fotos o treinamento de personagem precisa?

Pelo menos 4 imagens diferentes do personagem, entre o retrato aprovado, as fotos de referência, as expressões, as poses, os ângulos e as variações de iluminação. O Nodaro treina com até 20 delas. As folhas de personagem não contam.

Quanto custa o treinamento de personagem?

Um treinamento custa 1.650 créditos, e cada novo treinamento também. Os créditos são reembolsados quando um treinamento falha ou é cancelado. Depois, cada imagem gerada com o modelo treinado custa 22 créditos.

Quanto tempo leva um treinamento?

Cerca de 15 minutos. Consulte periodicamente GET /v1/characters/:id/training, a cada poucos segundos, até o status ser succeeded, failed ou cancelled.

Quando o Gerar imagem usa o modelo treinado?

Quando o prompt menciona exatamente um personagem treinado com @ e esse personagem está conectado ao nó Gerar imagem. Com dois ou mais personagens treinados, o nó usa em vez disso o modelo selecionado com imagens de referência.

Posso treinar um personagem em uma instalação auto-hospedada?

Não. O treinamento de personagem roda só no Nodaro Cloud, e as rotas não existem nas instalações auto-hospedadas. Nelas, mantenha um personagem consistente com o retrato aprovado e as imagens de referência dele.

Última atualização

Nesta página