キャラクター

キャラクター API を使うと、キャラクタースタジオでできることを、すべてスクリプトから実行できます。キャラクターを作成し、ポートレートの候補を生成して、そのうち 1 つを基準となるポートレートとして承認し、表情、アングル、ポーズ、ライティングのバリエーション、モーションクリップを追加します。その後は画像ノードと動画ノードがそのキャラクターを再利用するので、同じ人物がどのショットでも同じ見た目になります。

これらのルートは、すべてのエディションで使えます。認証には Bearer トークンを使います。個人用 API トークン（ndr_…）、OAuth アプリのトークン（ndr_app_…）、Community エディションではセッショントークンのいずれかです。すべてのルートは呼び出し元に限定されており、表示や変更ができるのは自分のキャラクターだけです。認証を参照してください。

エンドポイント

キャラクターで専用のモデルを学習させるのは Nodaro Cloud の機能で、専用のルートがあります。キャラクター学習を参照してください。

キャラクターが持つ情報

キャラクターは、保存された 1 つのアイデンティティです。次のフィールドは、GET /v1/characters/:id からキャメルケース（camelCase）で返されます。

アセットバケット

各バケットには、基準となるポートレートのバリエーションが入ります。バリエーションには自由に名前を付けられます。次の表は、プリセットの名前です。

キャラクターを一覧表示する

GET /v1/characters は、自分のキャラクターを新しい順に 1 ページ分返します。nextCursor が null になるまで、ページのリクエストを続けてください。キャラクターの数がページサイズを超えるアカウントでは、1 回のレスポンスが「すべてのキャラクター」になることはありません。

CURSOR=""
while :; do
  PAGE=$(curl -s "https://app.nodaro.ai/v1/characters?limit=100${CURSOR:+&cursor=$CURSOR}" \
    -H "Authorization: Bearer $NODARO_API_KEY")
  echo "$PAGE" | jq -r '.characters[] | "\(.id) \(.name)"'
  CURSOR=$(echo "$PAGE" | jq -r '.nextCursor // empty')
  [ -z "$CURSOR" ] && break
done

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

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

const all = []
let cursor: string | undefined
do {
  const page = await client.characters.list({ limit: 100, cursor })
  all.push(...page.characters)
  cursor = page.nextCursor ?? undefined
} while (cursor)

nodaro characters list --limit 100 --json
nodaro characters list --archived

{
  "characters": [
    {
      "id": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94",
      "name": "Kira",
      "description": "young protagonist with auburn hair",
      "sourceImageUrl": "https://cdn.nodaro.ai/characters/kira-portrait.png",
      "expressions": [{ "name": "smile", "url": "https://cdn.nodaro.ai/characters/kira-smile.png" }]
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA5LTIwVDEwOjAwOjAxWiJ9"
}

カーソルは不透明な値です。サーバーから受け取った nextCursor だけを渡し、リリースをまたいで保存しないでください。形式が正しくないカーソルは、黙って最初のページに戻るのではなく、400 validation_error になります。ページをたどっている間に作成されたキャラクターは含まれません。それらを表示するには、カーソルなしで最初からやり直してください。

キャラクターを作成または更新する

POST /v1/characters は、ボディに id がない場合はキャラクターを作成し、id がある場合はそのキャラクターを更新します。作成には nodeId と name が必要です。nodeId は、キャラクターをキャンバスのノードに関連付けます。コードから作成する場合は、"scripted" のような任意のラベルを使います。

更新では、送信したフィールドだけが書き込まれます。省略したフィールドは値が保たれるので、保存によって、実行中のジョブが書き込んでいるアセットバケットが上書きされることはありません。アセットバケットは、置き換えるつもりのときだけ送信してください。

curl -X POST https://app.nodaro.ai/v1/characters \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Kira",
    "description": "young protagonist with auburn hair",
    "style": "realistic",
    "seedPrompt": "kira portrait, warm natural lighting"
  }'

const { id } = await client.characters.create({
  nodeId: 'scripted',
  name: 'Kira',
  description: 'young protagonist with auburn hair',
  style: 'realistic',
  seedPrompt: 'kira portrait, warm natural lighting',
})

await client.characters.update(id, { gender: 'female', identityLock: 'soft' })

nodaro characters create --name "Kira" \
  --description "young protagonist with auburn hair" \
  --style realistic --seed-prompt "kira portrait, warm natural lighting"

nodaro characters update <id> --gender female

{ "id": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94", "name": "Kira" }

person と wardrobe が影響するのは、キャラクター自身のポートレートとアセットの生成だけです。これらは 人物（Person）ピッカーと同じカタログを使います。ピッカーカタログを参照してください。

ワークフローの実行時には、キャラクターの下流に接続された テキストから音声（Text to Speech）ノードに、キャラクターの voice から、ボイス、ボイスの種類、推奨モデルが設定されます。テキストから音声ノード自体で設定した値が優先されます。

ポートレートの候補を生成する

POST /v1/generate-character は、候補ごとに 1 つのジョブを開始し、それらの ID をすぐに返します。各ジョブが completed になるまで、ジョブ API でポーリングしてください。

attachToCharacterId を指定すると、最初に完了した候補がキャラクターのポートレートになります。候補が 1 つだけなら、これで完了です。候補が複数ある場合は、気に入ったものを承認してください。承認すると、ポートレートが置き換わります。

curl -X POST https://app.nodaro.ai/v1/generate-character \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kira",
    "seedPrompt": "kira portrait, warm natural lighting",
    "count": 4,
    "attachToCharacterId": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94"
  }'

const { jobIds } = await client.characters.generate({
  name: 'Kira',
  seedPrompt: 'kira portrait, warm natural lighting',
  count: 4,
  attachToCharacterId: id,
})

nodaro characters generate <id> --count 4 \
  --seed-prompt "kira portrait, warm natural lighting" --watch

{
  "jobId": "a1c4e8f2-5b3d-4e6a-8f7c-2d9b1e0a3c5f",
  "jobIds": [
    "a1c4e8f2-5b3d-4e6a-8f7c-2d9b1e0a3c5f",
    "b7d2f9a1-6c4e-4a8b-9d3f-3e0c2f1b4d6a",
    "c3e5a7b9-8d1f-4c2e-a6b8-4f1d3a2c5e7b",
    "d9f1b3c5-2e4a-4d6f-b8c1-5a2e4b3d6f8c"
  ]
}

quality と resolution による料金は、画像生成（Generate Image）とまったく同じです。4K や高品質での実行は、同じモデルの基本の段階よりも高くなります。モデルが対応していない値は、拒否されずに、対応している最も近い値に変更されます。クレジットも、変更後の値に従います。これらのルートは adjustments の一覧を返しません。実際に使われた値は、GET /v1/jobs/:id で取得したジョブの input_data で確認してください。

表情、アングル、ポーズ、ライティングのバリエーションを生成する

POST /v1/generate-character-asset は、基準となるポートレートのバリエーションを 1 つ生成し、{ jobId } を返します。結果をキャラクターに追加するには、attachToCharacterId、attachToColumn、attachName の 3 つの attach フィールドをすべて送信します。ジョブが完了すると、ワーカーがそのバケットに { name: attachName, url } を追加します。

curl -X POST https://app.nodaro.ai/v1/generate-character-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kira",
    "assetType": "expressions",
    "variant": "smile",
    "attachToCharacterId": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94",
    "attachToColumn": "expressions",
    "attachName": "smile"
  }'

await client.characters.generateAsset({
  name: 'Kira',
  assetType: 'bodyAngles',
  variant: 'front',
  attachToCharacterId: id,
  attachToColumn: 'body_angles',
  attachName: 'front',
})

nodaro characters generate-asset <id> --asset-type expressions --variant smile --watch

バリエーションをキャラクターに関連付けると、realLifeRefsByVariant でそのバリエーションのキーに保存されている実際の写真が、リクエストと一緒に自動で送信されます。

キャラクターをアニメーション化する

POST /v1/generate-character-motion は、キャラクターの静止画を動画クリップにして、{ jobId } を返します。attachToCharacterId と attachName を指定すると、完成したクリップが motions バケットに追加されます。

キャラクターに関連付けて sourceImageUrl を省略した場合、Nodaro は次の順で開始フレームを選びます。

1. 送信した sourceImageUrl。常にこれが優先されます。
2. bodyAngles の front のエントリー。全身のフレームは、頭と肩のポートレートよりもはるかにうまくアニメーション化できます。
3. bodyAngles のほかのエントリー。新しいものから順に使います。
4. 基準となるポートレート。

最良のクリップを得るには、最初のモーションの前に、front の全身のアングルを生成してください。

curl -X POST https://app.nodaro.ai/v1/generate-character-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kira",
    "motionPrompt": "slow head turn left, soft smile",
    "provider": "kling",
    "attachToCharacterId": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94",
    "attachName": "head turn"
  }'

await client.characters.generateMotion({
  name: 'Kira',
  motionPrompt: 'slow head turn left, soft smile',
  provider: 'kling',
  attachToCharacterId: id,
  attachName: 'head turn',
})

nodaro characters generate-motion <id> \
  --motion-prompt "slow head turn left, soft smile" --attach-name "head turn" --watch

キャラクターをアニメーション化できるモデルは、次のとおりです。料金は、そのモデルで画像から動画を生成する料金です。

ポートレートを承認する

POST /v1/characters/:id/approve-portrait は、完了した候補を基準となるポートレートに設定します。同じ呼び出しの中で、Nodaro はポートレートを見て canonicalDescription を作成します。これは、以降のプロンプトがキャラクターを説明するために使うテキストです。この説明がないと、シーンごとにキャラクターの見た目がずっと大きく変わってしまいます。

候補は、自分の completed のジョブである必要があります。説明の作成に失敗した場合でもポートレートは設定され、canonicalDescription は null になります。その場合は、POST /v1/characters/:id/llm-caption を呼び出して、もう一度試してください。どちらのルートも、繰り返し呼び出して問題ありません。承認は無料です。llm-caption は呼び出し 1 回につき 7 クレジットかかり、失敗した呼び出し（502）の分は返還されます。

curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/approve-portrait \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "b7d2f9a1-6c4e-4a8b-9d3f-3e0c2f1b4d6a" }'

const { portraitUrl, canonicalDescription } =
  await client.characters.approvePortrait(id, jobIds[1])

if (canonicalDescription === null) {
  await client.characters.recaption(id)
}

nodaro characters approve-portrait <id> --job <jobId>
nodaro characters recaption <id>

{
  "portraitUrl": "https://cdn.nodaro.ai/characters/kira-portrait-2.png",
  "canonicalDescription": "Kira is a woman in her mid-twenties with shoulder-length auburn hair, green eyes and light freckles..."
}

llm-caption は { canonicalDescription } を返します。キャラクターにまだポートレートがない場合は 400 no_portrait を、説明を作成できなかった場合は 502 を返します。

キャラクターのアーカイブ、復元、コピー

• アーカイブ：DELETE /v1/characters/:id はキャラクターをアーカイブし、{ success: true, archived: true } を返します。キャラクターはデフォルトの一覧から外れますが、GET /v1/characters/:id では引き続き返されるので、そのキャラクターを使うワークフローはそのまま動作します。Nodaro Cloud では、アーカイブすると、進行中の学習もキャンセルされてそのクレジットが返還され、学習済みモデルが削除されます。
• 復元：POST /v1/characters/:id/restore は { id, name } を返します。同じ名前の有効なキャラクターがその時点で存在する場合、Nodaro は名前の末尾に (restored) を付け、新しい名前を返します。
• 完全な削除：キャラクターを完全に削除する API ルートはありません。エディターのライブラリにある、アーカイブの表示を使ってください。
• コピー：POST /v1/characters/:id/duplicate は、名前の末尾に (copy) が付いた新しいキャラクターの { id, name } を返します。コピーは、アセットを再生成するまで、元のキャラクターのアセットの URL を共有します。
• 使用状況：GET /v1/characters/:id/usage は { workflowCount, workflows: [{ id, name }] } を返します。キャラクターをアーカイブする前に確認してください。

一連の流れ：作成、生成、承認、バリエーションの追加

ほかの生成でキャラクターを使う

アセットができたら、その URL をリファレンス画像として、画像生成や 動画生成（Generate Video）に渡します。たとえば、expressions の smile のエントリーを読み取り、その URL をプロンプトと一緒にリファレンスとして送信します。コードでは、URL を明示的に指定するのが最も簡単です。ワークフローの接続のしかたに左右されないためです。リクエストのフィールドについては、単体のノードを実行するを参照してください。

ワークフローでは、キャラクターアセット（Character Asset）ノードを画像ノードや動画ノードに接続するか、プロンプトで @ を使ってキャラクターをメンションします（たとえば @kira:1:smile）。メンションの記法はリファレンスの役割で、全体の手法はキャラクターの一貫性で説明しています。

MCP から使う

AI アシスタントは、次のツールを通じて同じルートを使います。アーカイブと復元は、意図的に MCP では使えないようにしています。

MCP ツールリファレンスを参照してください。

クレジット

Nodaro Cloud では、キャラクターの生成に、対応するノードと同じクレジット料金がかかります。

各モデルの正確な料金は、それぞれのモデルのページに記載されています。クレジットを参照してください。

エラー

エラーは、標準のエンベロープ { "error": { "code", "message" } } で返されます。エラーを参照してください。