クリーチャー
REST API で動物やクリーチャーを作成、管理します。メイン画像と、アングル、ポーズ、バリエーションの各画像、モーションクリップを生成し、クリーチャーにボイスを設定できます。
クリーチャー API は、見た目を固定した動物や、人間以外の生き物を管理します。たとえば、ペット、ドラゴン、マスコットです。クリーチャーは、承認済みのメイン画像、作成された説明、バリエーションの画像を持ちます。画像ノードと動画ノードがクリーチャーを再利用するので、どのショットでも同じ見た目になります。クリーチャーはオブジェクトと同じように動作し、自由入力の species、名前付きのボード、任意のボイスの 3 つが加わります。
これらのルートは、すべてのエディションで使え、Bearer トークンで認証します。個人用 API トークン(ndr_…)、OAuth アプリのトークン(ndr_app_…)、Community エディションではセッショントークンのいずれかです。認証を参照してください。CLI には、クリーチャー用のコマンドがありません。REST、SDK、MCP を使ってください。
エンドポイント
| メソッド | パス | 説明 |
|---|---|---|
GET | /v1/creatures | 自分のクリーチャーを一覧表示します。 |
GET | /v1/creatures/:id | 1 つのクリーチャーを、進行中のジョブとともに取得します。 |
POST | /v1/creatures | クリーチャーを作成します。ボディに id がある場合は、そのクリーチャーを更新します。 |
DELETE | /v1/creatures/:id | クリーチャーをアーカイブします。アーカイブしたクリーチャーは復元できます。 |
DELETE | /v1/creatures/:id?permanent=true | アーカイブしたクリーチャーとそのファイルを、完全に削除します。 |
POST | /v1/creatures/:id/restore | アーカイブしたクリーチャーを復元します。 |
POST | /v1/generate-creature | メイン画像の候補を 1〜10 枚生成します。 |
POST | /v1/generate-creature-asset | アングル、ポーズ、バリエーション、カスタムバリエーションを 1 つ生成します。 |
POST | /v1/generate-creature-motion | メイン画像をアニメーション化して、モーションクリップを作ります。 |
POST | /v1/creatures/:id/approve-main-image | 候補をメイン画像として承認し、クリーチャーの説明を作成します。 |
POST | /v1/creatures/:id/llm-caption | 現在のメイン画像から、説明を作成し直します。 |
クリーチャーが持つ情報
| フィールド | 説明 |
|---|---|
id, name, description | 識別子、表示名、クリーチャーの特徴についてのメモです。 |
species | 自由入力のテキストです。たとえば dragon、wolf、tabby cat です。メイン画像のプロンプトの主題になります。 |
category, style | 自由入力のカテゴリーと、ビジュアルスタイルです。スタイルは realistic、anime、3d-pixar、illustration のいずれかです。 |
sourceImageUrl | 基準となるメイン画像です。候補を承認すると設定されます。 |
canonicalDescription | メイン画像の承認時に Nodaro が作成する、80〜120 語程度の見た目の説明です。 |
styleLock | バリエーションをメイン画像から生成するかどうかです。デフォルトは true です。 |
angles, poses, variations, motionClips | アセットバケットです。各エントリーは { name, url } で、motionClips には動画が入ります。 |
boards | 最大 24 枚の名前付きのボードです。ボードは、見た目やムードごとに 1 枚ずつ作る、情報量の多いリファレンスシートです。 |
voice | クリーチャーのボイス、または null です。 |
referencePhotos | 最大 20 枚の、ムードボード用の写真です。それぞれ { kind, url } の形式です。kind は front、side、detail、context、moodBoard、other のいずれかです。 |
pendingJobs | GET /v1/creatures/:id のみ。まだ実行中のバリエーションのジョブです。 |
クリーチャーを一覧表示して読み取る
GET /v1/creatures は、自分の有効なクリーチャーを返します。パラメーターはオブジェクトの一覧と同じで、archived=true、projectId、任意の limit(最大 500)と cursor です。limit を指定しない場合は、一覧全体が返されます。指定した場合は、1 ページ分と nextCursor が返されます。nextCursor が null になるまで、その値を渡してください。
GET /v1/creatures/:id は、1 つのクリーチャーを返します。アーカイブしたクリーチャーでは、404 not_found が返されます。
curl "https://app.nodaro.ai/v1/creatures?limit=50" \
-H "Authorization: Bearer $NODARO_API_KEY"import { createClient, StaticTokenAuth } from '@nodaro/sdk'
const client = createClient({
baseUrl: 'https://app.nodaro.ai',
auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})
const { creatures, nextCursor } = await client.creatures.list({ limit: 50 })
const { creatures: archived } = await client.creatures.listArchived()クリーチャーを作成または更新する
POST /v1/creatures は、ボディに id がない場合はクリーチャーを作成し、id がある場合はそのクリーチャーを更新します。作成には nodeId と name が必要です。キャンバスのノードがない場合は、nodeId に "scripted" のような任意のラベルを使います。作成では { id } が、更新では { id, updatedAt } が返されます。
更新では、送信したフィールドだけが書き込まれます。アセットバケットが更新で書き込まれることはありませんが、boards は自分で設定できます。置き換えるには、一覧全体を送信します。expectedUpdatedAt を送信すると、読み取った後に誰かがクリーチャーを変更していた場合に、更新が 409 concurrent_modification で拒否されます。
curl -X POST https://app.nodaro.ai/v1/creatures \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodeId": "scripted",
"name": "Ember",
"species": "red dragon",
"description": "Young dragon with copper scales and a chipped left horn",
"style": "realistic"
}'const { id } = await client.creatures.create({
nodeId: 'scripted',
name: 'Ember',
species: 'red dragon',
description: 'Young dragon with copper scales and a chipped left horn',
style: 'realistic',
})
await client.creatures.update(id, {
voice: { voiceId: 'Callum', voiceName: 'Callum', traits: 'gravelly, slow', voiceType: 'premade' },
})Prop
Type
ボード
ボードは、1 つの見た目やムードについてまとめた、クリーチャーの情報量の多いリファレンスシートです。画像生成(Generate Image)の generate-image/creature-board プリセットでボードをレンダリングし、その URL を boards に保存します。プリセットとリファレンスボードを参照してください。
メイン画像とバリエーションを生成する
POST /v1/generate-creature は、候補ごとに 1 つのジョブを開始し、jobIds を返します。候補が 1 つのリクエストでは、jobId も返されます。attachToCreatureId を指定して count を 1 にすると、ジョブの完了時に結果がメイン画像になります。候補が複数ある場合は、何も関連付けられません。気に入った候補を承認してください。
POST /v1/generate-creature-asset は、バリエーションを 1 つ生成し、{ jobId } を返します。assetType は angles、poses、variations、custom のいずれかです。結果をバケットに追加するには、attachToCreatureId、attachToColumn(angles、poses、variations のいずれか)、attachName を送信します。custom のバリエーションでは、列を必ず指定します。
curl -X POST https://app.nodaro.ai/v1/generate-creature \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ember",
"species": "red dragon",
"count": 1,
"attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a"
}'
curl -X POST https://app.nodaro.ai/v1/generate-creature-asset \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ember",
"assetType": "poses",
"variant": "wings spread",
"attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
"attachToColumn": "poses",
"attachName": "wings spread"
}'const { jobIds } = await client.creatures.generate({
name: 'Ember',
species: 'red dragon',
count: 4,
})
await client.creatures.generateAsset({
name: 'Ember',
assetType: 'poses',
variant: 'wings spread',
attachToCreatureId: id,
attachToColumn: 'poses',
attachName: 'wings spread',
})| フィールド | ルート | 説明 |
|---|---|---|
name | 両方 | 必須。クリーチャーの名前です。 |
species, description, category, style | 両方 | クリーチャーの基本情報です。 |
count | メイン画像 | 生成する候補の数で、1〜10 です。デフォルトは 1 です。 |
assetType, variant | バリエーション | 必須。バリエーションの種類と名前です。 |
provider | 両方 | 画像モデルの ID です。省略すると、デフォルトのモデルを使います。 |
sourceImageUrl | 両方 | 元にする画像、またはバリエーションの元にする画像です。 |
seedPromptHint | 両方 | プロンプトに組み込む、プロンプトの断片です。たとえば、動物(Animal)ピッカーで選んだ内容です。 |
メイン画像をアニメーション化する
POST /v1/generate-creature-motion は、クリーチャーの画像を、待機ループ、忍び歩き、攻撃などのクリップにして、{ jobId } を返します。sourceImageUrl は必須です。attachToCreatureId と attachName を指定すると、クリップが motionClips に追加されます。
curl -X POST https://app.nodaro.ai/v1/generate-creature-motion \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ember",
"motionPrompt": "slow idle breathing, tail sways, smoke curls from the nostrils",
"sourceImageUrl": "https://cdn.nodaro.ai/creatures/ember-main.png",
"attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
"attachName": "idle"
}'await client.creatures.generateMotion({
name: 'Ember',
motionPrompt: 'slow idle breathing, tail sways, smoke curls from the nostrils',
sourceImageUrl: ember.sourceImageUrl!,
provider: 'kling-turbo',
duration: 5,
attachToCreatureId: id,
attachName: 'idle',
})| フィールド | 説明 |
|---|---|
name, motionPrompt, sourceImageUrl | 必須。クリーチャーの名前、動き、開始フレームです。 |
provider | kling-turbo(デフォルト)、kling、kling-3.0、minimax、hailuo-2.3、wan-i2v、seedance、bytedance-lite のいずれかです。 |
duration | クリップの長さ(秒)です。モデルが提供している長さを指定する必要があります。省略すると、モデルのデフォルトになります。 |
aspectRatio | 1:1(デフォルト)、3:4、16:9、9:16、4:3 のいずれかです。 |
refineFromVideoUrl | 画像から作り直す代わりに、新しいプロンプトで調整する既存のクリップです。 |
attachToCreatureId, attachName | クリーチャーと、motionClips でのクリップの名前です。 |
| モデル | 開発元 | モード | クレジット | 詳細 |
|---|---|---|---|---|
| Kling 2.5 Turbo Pro | Kuaishou | 画像から動画、テキストから動画 | 110 から | より高速な Kling で、低コストで良好な品質が得られます。終了フレームに対応しています。 |
| Kling 2.6 | Kuaishou | 画像から動画、テキストから動画 | 138 から | 画像から動画を生成する Kling 2.6 で、動きのリアルさに優れています。長さは 5 秒または 10 秒で、ネイティブオーディオを任意で付けられます。 |
| Kling 3.0 | Kuaishou | 画像から動画、テキストから動画 | 270 から | プレミアムな Kling 3.0 で、長さは 3〜15 秒の間で変えられ、ネイティブオーディオに対応し、720P/1080P で出力します。 |
| Hailuo 02 I2V Pro | MiniMax | 画像から動画、テキストから動画 | 143 | Hailuo 02 Pro は、フォトリアルな動きに優れ、クリップの長さは 5 秒固定です。終了フレームに対応しています。 |
| Hailuo 2.3 Standard | MiniMax | 画像から動画 | 75 から | Hailuo 2.3 のより安価なティアで、基本的な品質は良好です。 |
| Wan 2.6 I2V | Alibaba | 画像から動画 | 175 から | 画像から動画を生成する Wan 2.6 で、720p/1080p で 5/10/15 秒の動画を作ります。 |
| Bytedance Lite I2V | Bytedance | 画像から動画、テキストから動画 | 57 | 終了フレームに対応した、Bytedance の最も安価な動画ティアです。 |
メイン画像を承認する
{ candidateJobId, expectedUpdatedAt? } を指定して POST /v1/creatures/:id/approve-main-image を呼び出すと、完了した候補がメイン画像に設定され、同じ呼び出しの中で canonicalDescription が作成されます。レスポンスは { sourceImageUrl, canonicalDescription } です。説明の作成に失敗した場合でもメイン画像は設定され、説明は空になります。SDK では null が返されます。
POST /v1/creatures/:id/llm-caption は、説明を作成し直して、{ canonicalDescription } を返します。説明を作成できない場合は 502 を、まだメイン画像がない場合は 400 main_image_required を返します。どちらのルートも、繰り返し呼び出して問題ありません。承認は無料です。llm-caption は呼び出し 1 回につき 7 クレジットかかり、失敗した呼び出し(502)の分は返還されます。
curl -X POST https://app.nodaro.ai/v1/creatures/0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a/approve-main-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "candidateJobId": "1c9e7a5b-3d2f-4c8e-9a4b-8f6d2e1a4c3b" }'const ember = await client.creatures.get(id)
const approved = await client.creatures.approveMainImage(id, jobIds[0], ember.updatedAt)
if (approved.canonicalDescription === null) await client.creatures.recaption(id)クリーチャーのアーカイブ、復元、削除
| 操作 | curl | TypeScript SDK |
|---|---|---|
| アーカイブ | DELETE /v1/creatures/:id | client.creatures.delete(id) |
| 復元 | POST /v1/creatures/:id/restore | client.creatures.restore(id) |
| 完全に削除 | DELETE /v1/creatures/:id?permanent=true | client.creatures.permanentDelete(id) |
アーカイブは { success: true, archived: true } を返し、繰り返しても何も変わりません。復元は { id, name } を返します。同じ名前の有効なクリーチャーがある場合は、名前の末尾に (restored) が付きます。完全な削除は、アーカイブしたクリーチャーにだけ使え(それ以外では 400 not_archived)、クリーチャーと、そのクリーチャーが参照するすべてのファイルを削除します。
クリーチャーに話をさせる
クリーチャー専用のルートは必要ありません。クリーチャーのボイスで音声をレンダリングし、その音声をメイン画像にリップシンクします。
音声をレンダリングする
テキストから音声(Text to Speech)を実行します。クリーチャーの voice.voiceId を voice として渡し、voice.ttsProvider と voice.voiceType が設定されていれば、それらも渡します。
メイン画像をリップシンクする
リップシンク(Lip Sync)を実行します。クリーチャーの sourceImageUrl を imageUrl として、音声を audioUrl として渡します。
const speech = await client.nodes.runAndWait('text-to-speech', {
text: 'I knocked the vase off the shelf. I regret nothing.',
voice: ember.voice!.voiceId,
provider: ember.voice!.ttsProvider,
voiceType: ember.voice!.voiceType,
})
const clip = await client.nodes.runAndWait('lip-sync', {
imageUrl: ember.sourceImageUrl!,
audioUrl: speech.audioUrl,
provider: 'kling-avatar',
})nodes.runAndWait と、POST /v1/<node-type> ルートを直接呼び出す方法については、単体のノードを実行するを参照してください。
クリーチャーをショットに登場させる
画像生成では、source: "wired-creature" を指定した構造化リファレンスとして、クリーチャーを渡します。クリーチャーは自動で添付され、その体のつくり、模様、色を保つ文言が加えられます。プロンプトで、クリーチャーの名前を書くこともできます。@ember:1 と入力すると、その位置にクリーチャーが配置されます。役割を付けると、画像から何を取り出すかを選べます。たとえば @ember:1:markings です。役割は creature、anatomy、markings、pose、color、style です。
{
"prompt": "a wide shot of @ember:1 landing on the castle wall",
"connectedReferences": [
{ "id": "cr-1", "defaultName": "Ember", "source": "wired-creature", "url": "https://cdn.nodaro.ai/creatures/ember-main.png" }
]
}ワークフローでは、代わりに 動物/クリーチャーアセット(Animal/Creature Asset)ノードを、画像ノードや動画ノードに接続します。
MCP から使う
| ツール | 説明 |
|---|---|
list_creatures, get_creature | クリーチャーを探し、そのバリエーションの URL とボイスを読み取ります。 |
generate_creature | メイン画像(kind: "main")またはバリエーション(kind: "asset")を生成します。 |
approve_creature_main_image, recaption_creature | メイン画像を承認するか、その説明を作成し直します。 |
generate_creature_motion | メイン画像をアニメーション化します。 |
MCP ツールリファレンスを参照してください。
クレジット
Nodaro Cloud では、メイン画像のリクエストの料金は、画像モデルの料金 × count です。この料金は、最初のジョブが始まる前に確保されます。バリエーションの料金は画像モデルの料金、モーションクリップの料金は、動画モデルで画像から動画を生成する料金です。承認と、承認時に作成される説明は無料です。llm-caption は呼び出し 1 回につき 7 クレジットかかり、失敗した呼び出しの分は返還されます。
エラー
| ステータス | コード | 説明 |
|---|---|---|
400 | validation_error | フィールドが不足しているか、無効です。または、duration がモデルの提供する長さではありません。 |
400 | not_archived | アーカイブされていないクリーチャーに対して、完全な削除が送信されました。 |
400 | main_image_required | クリーチャーにメイン画像がない状態で、llm-caption が呼び出されました。 |
401 | unauthorized | トークンがないか、無効か、取り消されています。 |
402 | insufficient_credits | Nodaro Cloud のみ。アカウントの残高では、確保に必要なクレジットが足りません。 |
404 | not_found | その ID を持つ、自分の有効なクリーチャーがありません。 |
409 | concurrent_modification | expectedUpdatedAt が一致しなくなっています。クリーチャーを読み取り直し、変更をマージしてから再試行してください。 |
502 | — | 基準となる説明を作成できませんでした。もう一度試してください。 |
よくある質問
関連ページ
動物とクリーチャー
動物/クリーチャーアセット
オブジェクト
キャラクター
リップシンク
最終更新