# 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.

Source: https://nodaro.ai/pt-BR/docs/developers/api/character-training

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** (Generate Image)](https://nodaro.ai/docs/nodes/image/generate-image). 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 self-hosted, as rotas não existem e respondem `404`. Em uma instalação self-hosted, mantenha um personagem consistente com o retrato aprovado e as imagens de referência dele, como descrito em [Personagens](https://nodaro.ai/docs/developers/api/characters). As rotas aceitam um token Bearer e só agem sobre os seus próprios personagens. Veja [Autenticação](https://nodaro.ai/docs/developers/api/authentication).

## Endpoints
| Método | Caminho | O que faz |
| --- | --- | --- |
| `POST` | `/v1/characters/:id/train` | Inicia um treinamento. Reserva 1.650 créditos. |
| `GET` | `/v1/characters/:id/training` | Retorna o status do treinamento. |
| `DELETE` | `/v1/characters/:id/lora` | Cancela um treinamento em andamento ou remove o modelo treinado. |

## Antes de treinar
O personagem precisa de pelo menos **4 imagens diferentes**. 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.

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](https://nodaro.ai/docs/developers/api/characters#generate-an-expression-angle-pose-or-lighting-variant).

## Iniciar um treinamento
`POST /v1/characters/:id/train` reserva 1.650 créditos e inicia o treinamento. A rota responde `202` com o ID do job 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**

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

**TypeScript SDK**

```ts

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

// The SDK has no training methods yet; its generic request method calls the route.
const training = await client.request('POST', `/v1/characters/${characterId}/train`)
```

```json
{
"jobId": "7a9c1e3b-5d2f-4b8a-9c6e-1f3d5b7a9c2e",
"trainingId": "q4m8x2k6p1",
"triggerWord": "TOK_kira_a1b2c3"
}
```

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, a cada poucos segundos; o editor faz essa consulta periódica a cada 8 segundos.

**curl**

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

**TypeScript SDK**

```ts
type Training = { status: string; error: string | null; triggerWord: string | null }

const path = `/v1/characters/${characterId}/training`
let state = await client.request<Training>('GET', path)
while (state.status === 'queued' || state.status === 'training') {
await new Promise((resolve) => setTimeout(resolve, 8000))
state = await client.request<Training>('GET', path)
}
```

```json
{
"status": "succeeded",
"trainingId": "q4m8x2k6p1",
"error": null,
"trainedAt": "2026-09-20T11:42:08Z",
"version": "b81f4c0e9d27",
"triggerWord": "TOK_kira_a1b2c3",
"imageCount": 12
}
```

| Campo | O que contém |
| --- | --- |
| `status` | `untrained`, `queued`, `training`, `succeeded`, `failed` ou `cancelled`. |
| `trainingId` | O treinamento atual ou o último, ou `null`. |
| `error` | Por que o treinamento falhou, ou `null`. |
| `trainedAt` | Quando o modelo terminou de treinar, ou `null`. |
| `version` | A versão do modelo treinado, ou `null`. |
| `triggerWord` | A palavra que invoca o personagem no modelo treinado, ou `null`. |
| `imageCount` | Com quantas imagens o modelo foi treinado, ou `null`. |

## Gerar imagens com o modelo treinado
Quando o status for `succeeded`, execute o [Gerar imagem](https://nodaro.ai/docs/nodes/image/generate-image) 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** (Modify Image)](https://nodaro.ai/docs/nodes/image/modify-image) e os nós de vídeo, continuam usando as imagens de referência do personagem.

Veja [Executar um único nó](https://nodaro.ai/docs/developers/api/nodes) para a requisição do Gerar imagem e [Treinamento de personagens](https://nodaro.ai/docs/guides/character-training) 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. A rota retorna `{ ok: true }`. 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.

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

## Créditos
| Ação | Créditos |
| --- | --- |
| Um treinamento | 1.650, reembolsados quando o treinamento falha ou é cancelado. |
| Um novo treinamento | 1.650 a cada vez. |
| Uma imagem do modelo treinado | 22 por imagem, em vez do preço do modelo selecionado. |

Veja [Créditos](https://nodaro.ai/docs/developers/api/credits) para saldos e transações.

## Erros
| Status | Código | Significado |
| --- | --- | --- |
| `400` | `insufficient_training_images` | O personagem tem menos de 4 imagens diferentes. Adicione ângulos ou expressões e tente de novo. |
| `401` | `unauthorized` | O token está ausente, é inválido ou foi revogado. |
| `402` | `insufficient_credits` | A conta não cobre os 1.650 créditos. |
| `404` | `not_found` | Nenhum personagem com esse ID pertence a você, ou a instância não é o Nodaro Cloud. |
| `409` | `already_training_or_not_found` | Já há um treinamento na fila ou em execução para este personagem, ou o personagem não é seu. |
| `429` | — | Mais de 3 inícios de treinamento em um minuto com este token. |
| `502` | `training_dispatch_failed` | O serviço de treinamento recusou a requisição. Os créditos são reembolsados. |
| `503` | `public_url_not_configured`, `webhook_not_configured` | O treinamento não está configurado nesta instância. |

## Frequently asked questions

### 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 self-hosted?

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