# キャラクター学習

> REST API でキャラクターの高精度モデルを学習させ、学習の状況をポーリングし、モデルを削除します。画像生成ノードが学習済みモデルを使う条件も説明します。

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

**キャラクター学習**は、1 人のキャラクターの画像から、そのキャラクター専用のモデルを作ります。[**画像生成**（Generate Image）](https://nodaro.ai/docs/nodes/image/generate-image)で、最も高い再現度を得るためのものです。1 回の呼び出しで学習を開始し、終わるまでポーリングして、不要になったらモデルを削除します。学習後は、プロンプトがそのキャラクターをメンションするたびに、画像生成ノードが自動で学習済みモデルを使います。

キャラクター学習は Nodaro Cloud でのみ実行できます。セルフホスティング環境にはこれらのルートがなく、`404` が返されます。セルフホスティング環境では、[キャラクター](https://nodaro.ai/docs/developers/api/characters)で説明しているとおり、承認済みのポートレートとリファレンス画像で、キャラクターの一貫性を保ってください。これらのルートはベアラートークンを受け付け、あなた自身のキャラクターだけを操作します。[認証](https://nodaro.ai/docs/developers/api/authentication)を参照してください。

## エンドポイント
| メソッド | パス | 内容 |
| --- | --- | --- |
| `POST` | `/v1/characters/:id/train` | 学習を開始します。1,500 クレジットを確保します。 |
| `GET` | `/v1/characters/:id/training` | 学習のステータスを取得します。 |
| `DELETE` | `/v1/characters/:id/lora` | 進行中の学習をキャンセルするか、学習済みモデルを削除します。 |

## 学習の前に
キャラクターには、**4 枚以上の異なる画像**が必要です。Nodaro は、次の順序でキャラクターから画像を集め、重複を除いて、最大 20 枚で学習します。

1. 承認済みのポートレート。
2. リファレンス写真。
3. 表情、ポーズ、頭部のアングル、全身のアングル。
4. ライティングのバリエーション。

キャラクターシートは、そのビューがアングルと重複するため、数に含まれません。キャラクターの画像が 4 枚未満の場合は、先に `POST /v1/generate-character-asset` で、いくつかのアングルと表情を生成してください。[キャラクター](https://nodaro.ai/docs/developers/api/characters#generate-an-expression-angle-pose-or-lighting-variant)を参照してください。

## 学習を開始する
`POST /v1/characters/:id/train` は、1,500 クレジットを確保して学習を開始します。レスポンスは `202` で、学習のジョブ ID、学習の ID、キャラクターのトリガーワードが返されます。トリガーワードを入力する必要はありません。Nodaro がプロンプトに自動で追加します。

**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"
}
```

ダブルクリックしても問題ありません。学習がキュー待ちか実行中の間に、もう一度開始しようとすると `409 already_training_or_not_found` が返され、何も確保されません。各トークンが開始できる学習は、1 分あたり 3 回までです。

## 学習の状況を確認する
`GET /v1/characters/:id/training` は、学習の状態を返します。学習には約 15 分かかります。数秒ごとにポーリングしてください。エディターは、8 秒ごとにポーリングしています。

**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
}
```

| フィールド | 内容 |
| --- | --- |
| `status` | `untrained`、`queued`、`training`、`succeeded`、`failed`、`cancelled` のいずれかです。 |
| `trainingId` | 現在または直近の学習です。なければ `null` です。 |
| `error` | 学習が失敗した理由です。なければ `null` です。 |
| `trainedAt` | モデルの学習が完了した日時です。なければ `null` です。 |
| `version` | 学習済みモデルのバージョンです。なければ `null` です。 |
| `triggerWord` | 学習済みモデルでキャラクターを呼び出す単語です。なければ `null` です。 |
| `imageCount` | モデルの学習に使った画像の枚数です。なければ `null` です。 |

## 学習済みモデルで画像を生成する
ステータスが `succeeded` になったら、学習済みのキャラクターを `@` でちょうど 1 人メンションするプロンプトで、[画像生成](https://nodaro.ai/docs/nodes/image/generate-image)を実行します。そのキャラクターは、ノードに接続しておきます。すると Nodaro は、選択したモデルとリファレンス画像の代わりに、学習済みモデルを使います。

- **自動で処理されます**：トリガーワードはプロンプトの先頭に自動で入り、`@` メンションはテキストから削除されます。
- **画像 1 枚あたり 20 クレジット**：選択したモデルの料金の代わりに、学習済みモデルの料金がかかります。
- **学習済みのキャラクターは一度に 1 人**：プロンプトが学習済みのキャラクターを 2 人以上メンションしている場合、画像生成ノードは、選択したモデルをリファレンス画像とともに使う方式に戻ります。
- **画像生成ノードのみ**：[**画像修正**（Modify Image）](https://nodaro.ai/docs/nodes/image/modify-image)や動画ノードなど、ほかのノードは、引き続きキャラクターのリファレンス画像を使います。

画像生成のリクエストについては [1 つのノードを実行する](https://nodaro.ai/docs/developers/api/nodes)を、エディターでの同じ機能については[キャラクター学習](https://nodaro.ai/docs/guides/character-training)を参照してください。

## 再学習またはモデルの削除
- **再学習**：学習が成功、失敗、キャンセルのいずれかで終わった後なら、いつでも学習をもう一度開始できます。毎回 1,500 クレジットかかり、以前のモデルは置き換えられます。
- **削除**：`DELETE /v1/characters/:id/lora` は、進行中の学習をキャンセルしてそのクレジットを返還し、学習済みモデルを削除して、キャラクターの学習関連のフィールドをクリアします。`{ ok: true }` を返します。以降の生成は、リファレンス画像を使う方式に戻ります。
- **キャラクターのアーカイブ**：キャラクターをアーカイブした場合も、進行中の学習がキャンセルされてクレジットが返還され、学習済みモデルが削除されます。

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

## クレジット
| 操作 | クレジット |
| --- | --- |
| 学習 | 1,500。学習が失敗した場合やキャンセルされた場合は返還されます。 |
| 再学習 | 毎回 1,500。 |
| 学習済みモデルで作る画像 | 選択したモデルの料金の代わりに、1 枚あたり 20。 |

残高と取引履歴については、[クレジット](https://nodaro.ai/docs/developers/api/credits)を参照してください。

## エラー
| ステータス | コード | 意味 |
| --- | --- | --- |
| `400` | `insufficient_training_images` | キャラクターの異なる画像が 4 枚未満です。アングルや表情を追加してから、もう一度試してください。 |
| `401` | `unauthorized` | トークンがないか、無効か、取り消されています。 |
| `402` | `insufficient_credits` | アカウントの残高が、1,500 クレジットに足りません。 |
| `404` | `not_found` | あなたが所有するキャラクターの中に該当するものがないか、インスタンスが Nodaro Cloud ではありません。 |
| `409` | `already_training_or_not_found` | このキャラクターの学習がすでにキュー待ちか実行中であるか、キャラクターがあなたのものではありません。 |
| `429` | — | このトークンから、1 分間に 3 回を超えて学習を開始しようとしました。 |
| `502` | `training_dispatch_failed` | 学習サービスがリクエストを拒否しました。クレジットは返還されます。 |
| `503` | `public_url_not_configured`, `webhook_not_configured` | このインスタンスでは、学習が設定されていません。 |

## Frequently asked questions

### キャラクター学習には、写真が何枚必要ですか？

キャラクターの異なる画像が 4 枚以上必要です。対象は、承認済みのポートレート、リファレンス写真、表情、ポーズ、アングル、ライティングのバリエーションで、Nodaro はそのうち最大 20 枚を使って学習します。キャラクターシートは数に含まれません。

### キャラクター学習には、何クレジットかかりますか？

学習には 1,500 クレジットかかり、再学習のたびにも 1,500 クレジットかかります。学習が失敗した場合やキャンセルされた場合は、クレジットが返還されます。学習済みモデルで生成する画像は、その後 1 枚 20 クレジットです。

### 学習には、どのくらい時間がかかりますか？

約 15 分です。ステータスが succeeded、failed、cancelled のいずれかになるまで、数秒ごとに GET /v1/characters/:id/training をポーリングしてください。

### 画像生成ノードが学習済みモデルを使うのは、どんなときですか？

プロンプトが @ で学習済みのキャラクターをちょうど 1 人メンションし、そのキャラクターが画像生成ノードに接続されているときです。学習済みのキャラクターが 2 人以上の場合、ノードは代わりに、選択したモデルをリファレンス画像とともに使います。

### セルフホスティング環境で、キャラクターを学習させられますか？

いいえ。キャラクター学習は Nodaro Cloud でのみ実行でき、セルフホスティング環境にはこれらのルートがありません。セルフホスティング環境では、承認済みのポートレートとリファレンス画像で、キャラクターの一貫性を保ってください。