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

クリーチャー

REST API で動物やクリーチャーを作成、管理します。メイン画像と、アングル、ポーズ、バリエーションの各画像、モーションクリップを生成し、クリーチャーにボイスを設定できます。

クリーチャー API は、見た目を固定した動物や、人間以外の生き物を管理します。たとえば、ペット、ドラゴン、マスコットです。クリーチャーは、承認済みのメイン画像、作成された説明、バリエーションの画像を持ちます。画像ノードと動画ノードがクリーチャーを再利用するので、どのショットでも同じ見た目になります。クリーチャーはオブジェクトと同じように動作し、自由入力の species、名前付きのボード、任意のボイスの 3 つが加わります。

これらのルートは、すべてのエディションで使え、Bearer トークンで認証します。個人用 API トークン(ndr_…)、OAuth アプリのトークン(ndr_app_…)、Community エディションではセッショントークンのいずれかです。認証を参照してください。CLI には、クリーチャー用のコマンドがありません。REST、SDK、MCP を使ってください。

エンドポイント

メソッドパス説明
GET/v1/creatures自分のクリーチャーを一覧表示します。
GET/v1/creatures/:id1 つのクリーチャーを、進行中のジョブとともに取得します。
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 のいずれかです。
pendingJobsGET /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必須。クリーチャーの名前、動き、開始フレームです。
providerkling-turbo(デフォルト)、kling、kling-3.0、minimax、hailuo-2.3、wan-i2v、seedance、bytedance-lite のいずれかです。
durationクリップの長さ(秒)です。モデルが提供している長さを指定する必要があります。省略すると、モデルのデフォルトになります。
aspectRatio1:1(デフォルト)、3:4、16:9、9:16、4:3 のいずれかです。
refineFromVideoUrl画像から作り直す代わりに、新しいプロンプトで調整する既存のクリップです。
attachToCreatureId, attachNameクリーチャーと、motionClips でのクリップの名前です。
モデル開発元モードクレジット詳細
Kling 2.5 Turbo ProKuaishou画像から動画、テキストから動画110 からより高速な Kling で、低コストで良好な品質が得られます。終了フレームに対応しています。
Kling 2.6Kuaishou画像から動画、テキストから動画138 から画像から動画を生成する Kling 2.6 で、動きのリアルさに優れています。長さは 5 秒または 10 秒で、ネイティブオーディオを任意で付けられます。
Kling 3.0Kuaishou画像から動画、テキストから動画270 からプレミアムな Kling 3.0 で、長さは 3〜15 秒の間で変えられ、ネイティブオーディオに対応し、720P/1080P で出力します。
Hailuo 02 I2V ProMiniMax画像から動画、テキストから動画143Hailuo 02 Pro は、フォトリアルな動きに優れ、クリップの長さは 5 秒固定です。終了フレームに対応しています。
Hailuo 2.3 StandardMiniMax画像から動画75 からHailuo 2.3 のより安価なティアで、基本的な品質は良好です。
Wan 2.6 I2VAlibaba画像から動画175 から画像から動画を生成する Wan 2.6 で、720p/1080p で 5/10/15 秒の動画を作ります。
Bytedance Lite I2VBytedance画像から動画、テキストから動画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)

クリーチャーのアーカイブ、復元、削除

操作curlTypeScript SDK
アーカイブDELETE /v1/creatures/:idclient.creatures.delete(id)
復元POST /v1/creatures/:id/restoreclient.creatures.restore(id)
完全に削除DELETE /v1/creatures/:id?permanent=trueclient.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 クレジットかかり、失敗した呼び出しの分は返還されます。

エラー

ステータスコード説明
400validation_errorフィールドが不足しているか、無効です。または、duration がモデルの提供する長さではありません。
400not_archivedアーカイブされていないクリーチャーに対して、完全な削除が送信されました。
400main_image_requiredクリーチャーにメイン画像がない状態で、llm-caption が呼び出されました。
401unauthorizedトークンがないか、無効か、取り消されています。
402insufficient_creditsNodaro Cloud のみ。アカウントの残高では、確保に必要なクレジットが足りません。
404not_foundその ID を持つ、自分の有効なクリーチャーがありません。
409concurrent_modificationexpectedUpdatedAt が一致しなくなっています。クリーチャーを読み取り直し、変更をマージしてから再試行してください。
502—基準となる説明を作成できませんでした。もう一度試してください。

よくある質問

最終更新

目次