キャラクター学習
REST API でキャラクターの高精度モデルを学習させ、学習の状況をポーリングし、モデルを削除します。画像生成ノードが学習済みモデルを使う条件も説明します。
Nodaro Cloud で利用できます
キャラクター学習は、1 人のキャラクターの画像から、そのキャラクター専用のモデルを作ります。画像生成で、最も高い再現度を得るためのものです。1 回の呼び出しで学習を開始し、終わるまでポーリングして、不要になったらモデルを削除します。学習後は、プロンプトがそのキャラクターをメンションするたびに、画像生成ノードが自動で学習済みモデルを使います。
キャラクター学習は Nodaro Cloud でのみ実行できます。セルフホスティング環境にはこれらのルートがなく、404 が返されます。セルフホスティング環境では、キャラクターで説明しているとおり、承認済みのポートレートとリファレンス画像で、キャラクターの一貫性を保ってください。これらのルートはベアラートークンを受け付け、あなた自身のキャラクターだけを操作します。認証を参照してください。
SDK は、これらのルートを client.characters.train、trainingStatus、deleteLora としてラップしています。CLI では、nodaro characters train、training、delete-lora を使います。MCP で接続した AI アシスタントは、train_character で学習を開始し、get_character で状況を確認します。学習済みモデルの削除は、MCP のツールにはありません。
OAuth アプリのトークンでは、学習の開始と学習済みモデルの削除に assets:write が必要です。キャラクターの作成や削除と同じスコープです。このスコープがない場合は、何かが確保される前に 403 insufficient_scope が返されます。ステータスの読み取りには、スコープは不要です。セッションや個人用 API トークンには、スコープは不要です。
エンドポイント
| メソッド | パス | 内容 |
|---|---|---|
POST | /v1/characters/:id/train | 学習を開始します。1,650 クレジットを確保します。 |
GET | /v1/characters/:id/training | 学習のステータスを取得します。 |
DELETE | /v1/characters/:id/lora | 進行中の学習をキャンセルするか、学習済みモデルを削除します。 |
学習の前に
キャラクターには、4 枚以上の異なる画像が必要です。デフォルトでは、Nodaro は次の順序でキャラクターから画像を集め、重複を除いて、最大 20 枚で学習します。
- 承認済みのポートレート。
- リファレンス写真。
- 表情、ポーズ、頭部のアングル、全身のアングル。
- ライティングのバリエーション。
一部の画像だけで学習させるには、ボディで { "selectedImageUrls": [...] } を送ります。キャラクター自身の画像の URL を、最大 200 件まで指定できます。学習ではその画像だけが使われ、4 枚以上が残っている必要があります。リストを省くか空にすると、対象となるすべての画像が使われます。
キャラクターシートは、そのビューがアングルと重複するため、数に含まれません。キャラクターの画像が 4 枚未満の場合は、先に POST /v1/generate-character-asset で、いくつかのアングルと表情を生成してください。キャラクターを参照してください。
学習を開始する
POST /v1/characters/:id/train は、1,650 クレジットを確保して学習を開始します。レスポンスは 202 で、学習のジョブ ID、学習の ID、キャラクターのトリガーワードが返されます。トリガーワードを入力する必要はありません。Nodaro がプロンプトに自動で追加します。
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"
}学習のジョブ(jobId)は、学習とともに completed、failed、cancelled のいずれかで終わるので、GET /v1/jobs/:id/status で状況を確認することもできます。
ダブルクリックしても問題ありません。学習がキュー待ちか実行中の間に、もう一度開始しようとすると 409 already_training_or_not_found が返され、何も確保されません。各トークンが開始できる学習は、1 分あたり 3 回までです。
学習の状況を確認する
GET /v1/characters/:id/training は、学習の状態を返します。学習には約 15 分かかります。10 秒前後ごとにポーリングしてください。SDK には、完了を待つヘルパーはありません。
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
}| フィールド | 内容 |
|---|---|
status | untrained、queued、training、succeeded、failed、cancelled のいずれかです。untrained は、一度も学習していない、モデルが削除された、または学習を開始できなかったことを示します。 |
trainingId | 現在または直近の学習です。なければ null です。 |
error | 学習が失敗した理由です。なければ null です。 |
trainedAt | 直近の成功した学習が完了した日時です。なければ null です。 |
version | 直近の成功した学習のモデルのバージョンです。なければ null です。 |
triggerWord | 学習済みモデルでキャラクターを呼び出す単語です。なければ null です。 |
imageCount | 最新の学習で使った画像の枚数です。なければ null です。 |
生成で学習済みモデルが使われるのは、status が succeeded の間だけです。trainedAt と version は、再学習中、学習が失敗またはキャンセルされたとき、学習を開始できなかったときにも設定されたままですが、そのどの状態でもモデルは使われません。自分のものではないキャラクターや、アーカイブしたキャラクターには、404 not_found が返されます。
学習済みモデルで画像を生成する
ステータスが succeeded になったら、学習済みのキャラクターを @ でちょうど 1 人メンションするプロンプトで、画像生成を実行します。そのキャラクターは、ノードに接続しておきます。すると Nodaro は、選択したモデルとリファレンス画像の代わりに、学習済みモデルを使います。
- 自動で処理されます:トリガーワードはプロンプトの先頭に自動で入り、
@メンションはテキストから削除されます。 - 画像 1 枚あたり 22 クレジット:選択したモデルの料金の代わりに、学習済みモデルの料金がかかります。
- 学習済みのキャラクターは一度に 1 人:プロンプトが学習済みのキャラクターを 2 人以上メンションしている場合、画像生成ノードは、選択したモデルをリファレンス画像とともに使う方式に戻ります。
- 画像生成ノードのみ:画像修正や動画ノードなど、ほかのノードは、引き続きキャラクターのリファレンス画像を使います。
画像生成のリクエストについては 1 つのノードを実行するを、エディターでの同じ機能についてはキャラクター学習を参照してください。
再学習またはモデルの削除
- 再学習:学習が成功、失敗、キャンセルのいずれかで終わった後なら、いつでも学習をもう一度開始できます。毎回 1,650 クレジットかかり、以前のモデルは置き換えられます。
- 削除:
DELETE /v1/characters/:id/loraは、進行中の学習をキャンセルしてそのクレジットを返還し、学習済みモデルを削除して、キャラクターの学習関連のフィールドをクリアします。その後、ステータスはuntrainedになります。{ ok: true }を返し、元に戻すことはできません。以降の生成は、リファレンス画像を使う方式に戻ります。 - キャラクターのアーカイブ:キャラクターをアーカイブした場合も、進行中の学習がキャンセルされてクレジットが返還され、学習済みモデルが削除されます。
curl -X DELETE https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/lora \
-H "Authorization: Bearer $NODARO_API_KEY"クレジット
| 操作 | クレジット |
|---|---|
| 学習 | 1,650。学習が失敗した場合やキャンセルされた場合は返還されます。 |
| 再学習 | 毎回 1,650。 |
| 学習済みモデルで作る画像 | 選択したモデルの料金の代わりに、1 枚あたり 22。 |
残高と取引履歴については、クレジットを参照してください。
エラー
| ステータス | コード | 意味 |
|---|---|---|
400 | insufficient_training_images | キャラクターの異なる画像が 4 枚未満です。レスポンスの count と message に、画像の枚数が示されます。アングルや表情を追加してから、もう一度試してください。 |
400 | — | ID または selectedImageUrls の形式が正しくありません。ボディは { "message", "issues": [...] } です。 |
401 | unauthorized | トークンがないか、無効か、取り消されています。 |
402 | insufficient_credits | アカウントの残高が、1,650 クレジットに足りません。レスポンスに required と balance が含まれます。 |
403 | insufficient_scope | assets:write のない OAuth アプリのトークンです。 |
404 | not_found | あなたが所有するキャラクターの中に該当するものがないか、キャラクターがアーカイブされているか、インスタンスが Nodaro Cloud ではありません。 |
409 | already_training_or_not_found | このキャラクターの学習がすでにキュー待ちか実行中であるか、キャラクターがあなたのものではないか、アーカイブされています。 |
422 | job_blocked | デプロイのジョブポリシーが学習を拒否しました。 |
429 | — | このトークンから、1 分間に 3 回を超えて学習を開始しようとしました。 |
500 | claim_failed | 学習を確定できませんでした。何も開始されていないので、再試行してください。 |
502 | training_dispatch_failed | 学習を開始できませんでした。クレジットは返還され、ステータスは untrained になります。 |
503 | public_url_not_configured, price_not_configured | このインスタンスでは、学習が設定されていません。 |
503 | dedup_race_winner_unresolvable | 重複したリクエストが処理中で、その結果を読み取れませんでした。このリクエストは何も確保していません。再試行する前に、ステータスを読み取ってください。 |
これらのルート自体が返す拒否は、古い形式のボディを使います。コードは単なる文字列({ "error": "<code>" })で、トップレベルに message が付く場合があります。スコープ、クレジット、レート制限、ジョブポリシーによる拒否は、通常の { "error": { "code", "message" } } エンベロープを使います。SDK はどちらの形式も NodaroError.code と .message に読み込みます。
よくある質問
キャラクター学習には、写真が何枚必要ですか?
キャラクターの異なる画像が 4 枚以上必要です。対象は、承認済みのポートレート、リファレンス写真、表情、ポーズ、アングル、ライティングのバリエーションで、Nodaro はそのうち最大 20 枚を使って学習します。キャラクターシートは数に含まれません。
キャラクター学習には、何クレジットかかりますか?
学習には 1,650 クレジットかかり、再学習のたびにも 1,650 クレジットかかります。学習が失敗した場合やキャンセルされた場合は、クレジットが返還されます。学習済みモデルで生成する画像は、その後 1 枚 22 クレジットです。
学習には、どのくらい時間がかかりますか?
約 15 分です。ステータスが succeeded、failed、cancelled のいずれかになるまで、数秒ごとに GET /v1/characters/:id/training をポーリングしてください。
画像生成ノードが学習済みモデルを使うのは、どんなときですか?
プロンプトが @ で学習済みのキャラクターをちょうど 1 人メンションし、そのキャラクターが画像生成ノードに接続されているときです。学習済みのキャラクターが 2 人以上の場合、ノードは代わりに、選択したモデルをリファレンス画像とともに使います。
セルフホスティング環境で、キャラクターを学習させられますか?
いいえ。キャラクター学習は Nodaro Cloud でのみ実行でき、セルフホスティング環境にはこれらのルートがありません。セルフホスティング環境では、承認済みのポートレートとリファレンス画像で、キャラクターの一貫性を保ってください。
関連ページ
キャラクター学習
キャラクター
画像生成
キャラクターの一貫性
クレジット
最終更新