NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
REST API

キャラクター学習

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 枚で学習します。

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

一部の画像だけで学習させるには、ボディで { "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
}
フィールド内容
statusuntrained、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。

残高と取引履歴については、クレジットを参照してください。

エラー

ステータスコード意味
400insufficient_training_imagesキャラクターの異なる画像が 4 枚未満です。レスポンスの count と message に、画像の枚数が示されます。アングルや表情を追加してから、もう一度試してください。
400—ID または selectedImageUrls の形式が正しくありません。ボディは { "message", "issues": [...] } です。
401unauthorizedトークンがないか、無効か、取り消されています。
402insufficient_creditsアカウントの残高が、1,650 クレジットに足りません。レスポンスに required と balance が含まれます。
403insufficient_scopeassets:write のない OAuth アプリのトークンです。
404not_foundあなたが所有するキャラクターの中に該当するものがないか、キャラクターがアーカイブされているか、インスタンスが Nodaro Cloud ではありません。
409already_training_or_not_foundこのキャラクターの学習がすでにキュー待ちか実行中であるか、キャラクターがあなたのものではないか、アーカイブされています。
422job_blockedデプロイのジョブポリシーが学習を拒否しました。
429—このトークンから、1 分間に 3 回を超えて学習を開始しようとしました。
500claim_failed学習を確定できませんでした。何も開始されていないので、再試行してください。
502training_dispatch_failed学習を開始できませんでした。クレジットは返還され、ステータスは untrained になります。
503public_url_not_configured, price_not_configuredこのインスタンスでは、学習が設定されていません。
503dedup_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 でのみ実行でき、セルフホスティング環境にはこれらのルートがありません。セルフホスティング環境では、承認済みのポートレートとリファレンス画像で、キャラクターの一貫性を保ってください。

最終更新

目次