# クリーチャー

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

Source: https://nodaro.ai/ja/docs/developers/api/creatures

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

これらのルートは、すべてのエディションで使え、Bearer トークンで認証します。個人用 API トークン（`ndr_…`）、OAuth アプリのトークン（`ndr_app_…`）、Community エディションではセッショントークンのいずれかです。[認証](https://nodaro.ai/docs/developers/api/authentication)を参照してください。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**

```bash
curl "https://app.nodaro.ai/v1/creatures?limit=50" \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

**TypeScript SDK**

```ts

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**

```bash
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"
}'
```

**TypeScript SDK**

```ts
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' },
})
```

<TypeTable
type={{
id: { type: 'string (uuid)', description: '更新するクリーチャーです。クリーチャーを作成する場合は省略します。' },
nodeId: { type: 'string', description: '作成時は必須です。クリーチャーが属するキャンバスのノードです。ノードがない場合は、任意のラベルを指定します。' },
name: { type: 'string', description: '作成時は必須です。' },
species: { type: 'string', description: 'クリーチャーが何であるかを、自由入力のテキストで指定します。' },
description: { type: 'string', description: 'クリーチャーの際立った特徴です。' },
category: { type: 'string', description: '自由入力のテキストです。' },
style: { type: 'string', description: 'realistic、anime、3d-pixar、illustration のいずれかです。' },
styleLock: { type: 'boolean', description: '承認済みのメイン画像から、バリエーションを生成します。', default: 'true' },
referencePhotos: { type: 'array', description: '最大 20 枚の { kind, url } 形式の、ムードボード用の写真です。' },
voice: { type: 'object | null', description: '{ voiceId, voiceName, traits, voiceType?, ttsProvider? } の形式です。更新時に null を送信すると、ボイスが解除されます。' },
boards: { type: 'array', description: '更新時のみ。最大 24 枚の { name, url } 形式のボードです。一覧全体を置き換えます。' },
canonicalDescription: { type: 'string', description: '作成された説明を置き換えます。' },
projectId: { type: 'string (uuid)', description: 'クリーチャーを所属させるプロジェクトです。' },
expectedUpdatedAt: { type: 'string (ISO 8601)', description: '更新時に使います。このタイムスタンプ以降にクリーチャーが変更されていた場合、書き込みを 409 で拒否します。' },
}}
/>

### ボード
ボードは、1 つの見た目やムードについてまとめた、クリーチャーの情報量の多いリファレンスシートです。[**画像生成**](https://nodaro.ai/docs/nodes/image/generate-image)（Generate Image）の `generate-image/creature-board` プリセットでボードをレンダリングし、その URL を `boards` に保存します。[プリセット](https://nodaro.ai/docs/developers/api/presets)と[リファレンスボード](https://nodaro.ai/docs/guides/reference-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**

```bash
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"
}'
```

**TypeScript SDK**

```ts
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` | 両方 | プロンプトに組み込む、プロンプトの断片です。たとえば、[**動物**](https://nodaro.ai/docs/nodes/creative-controls/animal)（Animal）ピッカーで選んだ内容です。 |

## メイン画像をアニメーション化する
`POST /v1/generate-creature-motion` は、クリーチャーの画像を、待機ループ、忍び歩き、攻撃などのクリップにして、`{ jobId }` を返します。`sourceImageUrl` は必須です。`attachToCreatureId` と `attachName` を指定すると、クリップが `motionClips` に追加されます。

**curl**

```bash
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"
}'
```

**TypeScript SDK**

```ts
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` でのクリップの名前です。 |

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [Kling 2.5 Turbo Pro](https://nodaro.ai/docs/models/video/kling-2-5-turbo-pro) | Kuaishou | Image to video, Text to video | from 110 | Faster Kling — good quality at lower cost. Supports end frame. |
| [Kling 2.6](https://nodaro.ai/docs/models/video/kling-2-6) | Kuaishou | Image to video, Text to video | from 138 | Kling 2.6 I2V — strong motion realism. 5s/10s, optional native audio. |
| [Kling 3.0](https://nodaro.ai/docs/models/video/kling-3-0) | Kuaishou | Image to video, Text to video | from 270 | Premium Kling 3.0 — variable 3-15s duration, native audio, 720P/1080P. |
| [Hailuo 02 I2V Pro](https://nodaro.ai/docs/models/video/hailuo-02-i2v-pro) | MiniMax | Image to video, Text to video | 143 | Hailuo 02 Pro — strong photoreal motion, fixed 5-second clips. Supports end frame. |
| [Hailuo 2.3 Standard](https://nodaro.ai/docs/models/video/hailuo-2-3-standard) | MiniMax | Image to video | from 75 | Cheaper Hailuo 2.3 tier — good baseline quality. |
| [Wan 2.6 I2V](https://nodaro.ai/docs/models/video/wan-2-6-i2v) | Alibaba | Image to video | from 175 | Wan 2.6 image-to-video — 5/10/15s at 720p/1080p. |
| [Bytedance Lite I2V](https://nodaro.ai/docs/models/video/bytedance-lite-i2v) | Bytedance | Image to video, Text to video | 57 | Cheapest Bytedance video tier with end-frame support. |

## メイン画像を承認する
`{ 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**

```bash
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" }'
```

**TypeScript SDK**

```ts
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`）、クリーチャーと、そのクリーチャーが参照するすべてのファイルを削除します。

## クリーチャーに話をさせる
クリーチャー専用のルートは必要ありません。クリーチャーのボイスで音声をレンダリングし、その音声をメイン画像にリップシンクします。

### 音声をレンダリングする
[**テキストから音声**](https://nodaro.ai/docs/nodes/audio/text-to-speech)（Text to Speech）を実行します。クリーチャーの `voice.voiceId` を `voice` として渡し、`voice.ttsProvider` と `voice.voiceType` が設定されていれば、それらも渡します。

### メイン画像をリップシンクする
[**リップシンク**](https://nodaro.ai/docs/nodes/video/lip-sync)（Lip Sync）を実行します。クリーチャーの `sourceImageUrl` を `imageUrl` として、音声を `audioUrl` として渡します。

```ts
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>` ルートを直接呼び出す方法については、[単体のノードを実行する](https://nodaro.ai/docs/developers/api/nodes)を参照してください。

## クリーチャーをショットに登場させる
[画像生成](https://nodaro.ai/docs/nodes/image/generate-image)では、`source: "wired-creature"` を指定した構造化リファレンスとして、クリーチャーを渡します。クリーチャーは自動で添付され、その体のつくり、模様、色を保つ文言が加えられます。プロンプトで、クリーチャーの名前を書くこともできます。`@ember:1` と入力すると、その位置にクリーチャーが配置されます。役割を付けると、画像から何を取り出すかを選べます。たとえば `@ember:1:markings` です。役割は `creature`、`anatomy`、`markings`、`pose`、`color`、`style` です。

```json
{
"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" }
]
}
```

ワークフローでは、代わりに [**動物／クリーチャーアセット**](https://nodaro.ai/docs/nodes/assets/creature)（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 ツールリファレンス](https://nodaro.ai/docs/mcp/tools)を参照してください。

## クレジット
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` | — | 基準となる説明を作成できませんでした。もう一度試してください。 |

## Frequently asked questions

### クリーチャーとオブジェクトの違いは何ですか？

クリーチャーは、動物や人間以外の生き物です。自由入力の種族、素材の代わりとなるポーズのバケット、名前付きのボード、任意のボイスを持ちます。それ以外はオブジェクトと同じように動作し、作成、生成、承認、アーカイブのルートも同じです。

### クリーチャーに話をさせるにはどうすればよいですか？

クリーチャーにボイスを設定し、そのボイスを使って、テキストから音声（Text to Speech）ノードで音声をレンダリングします。次に、クリーチャーのメイン画像と音声で、リップシンク（Lip Sync）を実行します。クリーチャー専用のルートは必要ありません。

### クリーチャーをアニメーション化できるモデルはどれですか？

オブジェクトと同じ 8 つの動画モデルです。プロバイダー ID は、kling-turbo（デフォルト）、kling、kling-3.0、minimax、hailuo-2.3、wan-i2v、seedance、bytedance-lite です。クリップ 1 本の料金は、そのモデルで画像から動画を生成する料金です。

### クリーチャー用の CLI コマンドはありますか？

いいえ。REST のルート、TypeScript SDK（client.creatures）、MCP のクリーチャー用ツールを使ってください。