# オブジェクトとクリーチャー > Nodaro の SDK を使って、TypeScript からオブジェクトとクリーチャーを作成し、メイン画像とバリエーションを生成して、アニメーション化し、クリーチャーに話をさせます。 Source: https://nodaro.ai/ja/docs/developers/sdk/objects-and-creatures **`client.objects`** は、小道具、商品、乗り物向けに、オブジェクト／小道具スタジオでできることをすべてスクリプトから行います。**`client.creatures`** は、動物やクリーチャー向けに同じことを行います。どちらも、アイテムの作成と編集、メイン画像候補の生成、その承認、バリエーションとモーションクリップの追加、そして以降のプロンプトでアイテムの一貫性を保つ説明の作成を行います。これらのメソッドは、[オブジェクト](https://nodaro.ai/docs/developers/api/objects)と[クリーチャー](https://nodaro.ai/docs/developers/api/creatures)の REST API を呼び出します。エディターでの見方については、[オブジェクトと小道具](https://nodaro.ai/docs/guides/objects)と[動物とクリーチャー](https://nodaro.ai/docs/guides/creatures)を参照してください。 ## メソッド この 2 つのリソースは、同じメソッドを持ちます。 | メソッド | 内容 | | --- | --- | | [`objects.list(params?)`](#objectslistparams)、[`creatures.list(params?)`](#creatureslistparams) | アイテムを一覧表示します | | [`objects.listArchived(params?)`](#objectslistarchivedparams) | アーカイブしたアイテムを一覧表示します | | [`objects.get(id)`](#objectsgetid) | 1 つのアイテムを、進行中のジョブとともに読み取ります | | [`objects.create(input)`](#objectscreateinput)、[`creatures.create(input)`](#creaturescreateinput) | アイテムを作成します | | [`objects.update(id, input)`](#objectsupdateid-input)、[`creatures.update(id, input)`](#creaturesupdateid-input) | アイテムを変更します | | [`objects.delete(id)` と `restore(id)`](#objectsdeleteid-and-restoreid) | アイテムをアーカイブするか、元に戻します | | [`objects.permanentDelete(id)`](#objectspermanentdeleteid) | アーカイブしたアイテムと、そのファイルを完全に削除します | | [`objects.generate(input)`](#objectsgenerateinput)、[`creatures.generate(input)`](#creaturesgenerateinput) | メイン画像の候補を生成します | | [`objects.generateAsset(input)`](#objectsgenerateassetinput)、[`creatures.generateAsset(input)`](#creaturesgenerateassetinput) | バリエーションを生成します | | [`objects.generateMotion(input)`](#objectsgeneratemotioninput)、[`creatures.generateMotion(input)`](#creaturesgeneratemotioninput) | メイン画像をアニメーション化してクリップにします | | [`objects.approveMainImage(id, candidateJobId, expectedUpdatedAt?)`](#objectsapprovemainimageid-candidatejobid-expectedupdatedat) | 候補をメイン画像にします | | [`objects.recaption(id)`](#objectsrecaptionid) | 説明を作成し直します | ## client.objects オブジェクトは、メイン画像を `sourceImageUrl` に持ち、`angles`、`materials`、`variations`、`motionClips` の 4 つのコレクション（いずれも `{ name, url }` のリストです）、`boards`、`referencePhotos`、`canonicalDescription`、`styleLock` を持ちます。`category` は、`furniture`、`vehicle`、`weapon`、`food`、`clothing`、`electronics`、`nature`、`tool`、`animal`、`other` のいずれかです。 `Object` という名前は、JavaScript のグローバルと同じです。両方が必要な場合は、別名でインポートしてください。`import type { Object as NodaroObject } from "@nodaro/sdk"` のようにします。 ### objects.list(params?) 自分のオブジェクトを一覧表示します。デフォルトでは、有効なオブジェクトだけを返します。ページングは任意です。`limit` を指定しない場合は一覧全体を、`limit`（最大 500）を指定すると 1 ページ分と `nextCursor` を取得します。 ```ts list(params?: { archived?: boolean; projectId?: string; limit?: number; cursor?: string }): Promise<{ objects: Object[] nextCursor?: string | null }> ``` ```ts const { objects } = await client.objects.list() const page = await client.objects.list({ limit: 100 }) ``` ### objects.listArchived(params?) 自分のアーカイブしたオブジェクトを一覧表示します。`list({ archived: true })` のショートカットです。`creatures.listArchived()` も同じように動作します。 ```ts listArchived(params?: { projectId?: string; limit?: number; cursor?: string }): Promise<{ objects: Object[]; nextCursor?: string | null }> ``` ```ts const { objects: archived } = await client.objects.listArchived() ``` ### objects.get(id) 1 つのオブジェクトを、`pendingJobs`（まだ生成中のバリエーション）とともに読み取ります。アーカイブしたオブジェクトは返され**ません**。`NotFoundError` がスローされます。`creatures.get()` も同じように動作します。 ```ts get(id: string): Promise ``` ```ts const object = await client.objects.get(objectId) console.log(object.sourceImageUrl, object.materials) ``` ### objects.create(input) オブジェクトを作成します。`name` と `nodeId` は必須です。キャンバスのノードがないスクリプトでは、`nodeId` に `"mcp-managed"` を渡せます。 ```ts create(input: CreateObjectInput): Promise<{ id: string }> ``` ```ts const { id: objectId } = await client.objects.create({ nodeId: "mcp-managed", name: "Antique Lantern", description: "Weathered brass lantern with hand-engraved filigree", category: "tool", style: "realistic", }) ``` ### objects.update(id, input) オブジェクトを変更します。送信したフィールドだけが書き込まれます。バリエーションのコレクションは、この呼び出しの対象ではありません。作業中に、生成ジョブがコレクションへ追加していくためです。 ```ts update(id: string, input: UpdateObjectInput): Promise<{ id: string; updatedAt: string }> ``` ', description: "リファレンスボードです。" }, selectedAssetByVariant: { type: 'Record', description: "バリエーションごとに選ばれているテイクです。" }, expectedUpdatedAt: { type: 'string', description: "自分が読み取った updatedAt の値です。それ以降にオブジェクトが変更されていた場合、更新は 409 concurrent_modification で失敗します。" }, }} /> ```ts await client.objects.update(objectId, { canonicalDescription: "A weathered brass lantern with engraved filigree and a glass chimney", expectedUpdatedAt: object.updatedAt, }) ``` `409 concurrent_modification` は、通常の `NodaroError` として返されます。オブジェクトを読み取り直し、マージしてから、もう一度試してください。 ### objects.delete(id) と restore(id) `delete()` はオブジェクトをアーカイブします。アーカイブ済みのオブジェクトに対して繰り返しても、何も変わりません。`restore()` は元に戻します。大文字と小文字を区別せずに、有効なオブジェクトの名前と一致する場合、サーバーは `(restored)` を付けて、使った名前を返します。 ```ts delete(id: string): Promise<{ success: true; archived: true }> restore(id: string): Promise<{ id: string; name: string }> ``` ```ts await client.objects.delete(objectId) const { name } = await client.objects.restore(objectId) ``` ### objects.permanentDelete(id) アーカイブしたオブジェクトと、それが参照する保存済みのすべてのファイルを削除します。アーカイブしたオブジェクトにしか使えません。有効なオブジェクトでは `400 not_archived` で失敗します。先に `delete()` でアーカイブしてください。`creatures.permanentDelete()` も同じように動作します。 ```ts permanentDelete(id: string): Promise<{ success: true; permanent: true }> ``` ```ts await client.objects.delete(objectId) await client.objects.permanentDelete(objectId) ``` Nodaro の MCP ツールには、この操作は用意されていません。そのため、AI アシスタントがオブジェクトを削除することはできません。 ### objects.generate(input) メイン画像の候補を生成します（`POST /v1/generate-object`）。`count` が 1 より大きい場合、どのジョブも開始する前に、すべてのジョブ分を確保します。そのため、途中で失敗すると、バッチ全体がロールバックされます。 ```ts generate(input: GenerateObjectInput): Promise<{ jobIds: string[]; jobId?: string }> ``` ```ts const { jobIds } = await client.objects.generate({ name: "Antique Lantern", count: 4 }) for (const jobId of jobIds) { // poll each candidate with client.jobs.getStatus(jobId) } ``` `jobIds` は常に存在し、候補ごとに 1 つの ID を持ちます。`jobId` は、候補が 1 つの場合の古いエイリアスです。`jobIds` を使ってください。`attachToObjectId` を指定して候補が 1 つの場合、ジョブが完了すると、その結果がメイン画像になります。それ以外の場合は、`approveMainImage()` で 1 つを選んでください。 ### objects.generateAsset(input) 1 つのバリエーションを生成します（`POST /v1/generate-object-asset`）。`attachToObjectId`、`attachToColumn`、`attachName` を指定すると、ジョブが完了したときに、結果がそのコレクションに追加されます。 ```ts generateAsset(input: GenerateObjectAssetInput): Promise<{ jobId: string }> ``` ```ts const { jobId } = await client.objects.generateAsset({ name: "Antique Lantern", assetType: "materials", variant: "gold", attachToObjectId: objectId, attachToColumn: "materials", attachName: "gold", }) ``` `angles`、`materials`、`variations`、`motion` では、コレクションはアセットの種類から決まります。`custom` のバリエーションでは、`attachToColumn` が必要です。 ### objects.generateMotion(input) オブジェクトの画像を、[**動画生成**](https://nodaro.ai/docs/nodes/video/generate-video)（Generate Video）の画像から動画へのモードで、クリップにアニメーション化します（`POST /v1/generate-object-motion`）。クリップは常に `motionClips` に入ります。デフォルトは商品撮影向けで、モデルは `kling-turbo`、フレームは `1:1` です。 ```ts generateMotion(input: GenerateObjectMotionInput): Promise<{ jobId: string }> ``` ```ts const { jobId } = await client.objects.generateMotion({ name: "Antique Lantern", motionPrompt: "Slow 360-degree rotation, soft golden rim light", sourceImageUrl: object.sourceImageUrl!, attachToObjectId: objectId, attachName: "rotate-360", }) ``` ### objects.approveMainImage(id, candidateJobId, expectedUpdatedAt?) `generate()` からの完了した候補を、オブジェクトのメイン画像にします。続けて、ビジョンモデルがオブジェクトの説明を作成し、このメソッドは両方を返します。 ```ts approveMainImage(id: string, candidateJobId: string, expectedUpdatedAt?: string): Promise<{ sourceImageUrl: string canonicalDescription: string | null }> ``` ```ts const { sourceImageUrl, canonicalDescription } = await client.objects.approveMainImage(objectId, jobIds[0]) ``` 説明を作成できなかった場合、`canonicalDescription` は `null` になります。メイン画像は設定されたままなので、もう一度試すには `recaption()` を呼び出してください。 ### objects.recaption(id) 現在のメイン画像から、オブジェクトの説明を作成し直します。この呼び出しは繰り返しても安全で、同時実行制御用のトークンは必要ありません。 ```ts recaption(id: string): Promise<{ canonicalDescription: string }> ``` ```ts const { canonicalDescription } = await client.objects.recaption(objectId) ``` オブジェクトにメイン画像がない場合は `400 main_image_required` で、ビジョンモデルが失敗した場合は 502 で失敗します。 ## client.creatures クリーチャーは、動物や空想上の生き物です。オブジェクトと同じように動作しますが、4 つの違いがあります。 - **`species`** は、`dragon` や `wolf` などの自由記述のタイプで、メイン画像のプロンプトの主題になります。`category` も自由記述です。 - **`poses`** が `materials` の代わりになるため、コレクションは `angles`、`poses`、`variations`、`motionClips` です。バリエーションの種類は `angles`、`poses`、`variations`、`custom` です。 - **`boards`** は、最大 24 枚の名前付きの**クリーチャーボード**（Creature Board）を保持します。クリーチャーボードは、[**画像生成**](https://nodaro.ai/docs/nodes/image/generate-image)（Generate Image）の**クリーチャーボード**プリセットで作る、情報量の多いリファレンスシートです。このリストは自分で管理するもので、`create()` と `update()` は、リスト全体を置き換えます。 - **`voice`** を設定すると、そのクリーチャーは話せるようになります。キャラクターのボイスと同じ形で、`{ voiceId, voiceName, traits, voiceType?, previewUrl?, ttsProvider? }` です。取り除くには `voice: null` を渡します。 `creatures.listArchived()`、`get()`、`delete()`、`restore()`、`permanentDelete()`、`approveMainImage()`、`recaption()` は、同じ引数を取り、上のオブジェクトのメソッドと同じように動作します。 ### creatures.list(params?) ```ts list(params?: { archived?: boolean; projectId?: string; limit?: number; cursor?: string }): Promise<{ creatures: Creature[] nextCursor?: string | null }> ``` ```ts const { creatures } = await client.creatures.list() ``` ### creatures.create(input) ```ts create(input: CreateCreatureInput): Promise<{ id: string }> ``` ```ts const { id: creatureId } = await client.creatures.create({ nodeId: "mcp-managed", name: "Biscuit", species: "ginger cat", style: "realistic", }) ``` ### creatures.update(id, input) `nodeId` を除く `create()` のフィールドに加え、`boards`、`selectedAssetByVariant`、`expectedUpdatedAt` を取ります。送信したフィールドだけが書き込まれます。 ```ts update(id: string, input: UpdateCreatureInput): Promise<{ id: string; updatedAt: string }> ``` ', description: "クリーチャーボードで、最大 24 枚です。リスト全体が置き換わります。" }, voice: { type: 'CreatureVoice | null', description: "ボイスです。null にすると解除されます。" }, expectedUpdatedAt: { type: 'string', description: "自分が読み取った updatedAt の値です。新しい変更を上書きしないためのものです。" }, }} /> ```ts await client.creatures.update(creatureId, { voice: { voiceId: chosenVoiceId, voiceName: "Aria", traits: "smug, unhurried" }, }) ``` ### creatures.generate(input) メイン画像の候補を生成します。`objects.generate()` のフィールドに加えて `species` を取り、`{ jobIds }` を返します。 ```ts generate(input: GenerateCreatureInput): Promise<{ jobIds: string[]; jobId?: string }> ``` ```ts const { jobIds } = await client.creatures.generate({ name: "Biscuit", species: "ginger cat", count: 4 }) ``` ### creatures.generateAsset(input) 1 つのバリエーションを生成します。`attachToCreatureId` がある点を除き、`objects.generateAsset()` と同じように動作します。 ```ts generateAsset(input: GenerateCreatureAssetInput): Promise<{ jobId: string }> ``` ```ts await client.creatures.generateAsset({ name: "Biscuit", assetType: "poses", variant: "sitting", attachToCreatureId: creatureId, attachToColumn: "poses", attachName: "sitting", }) ``` ### creatures.generateMotion(input) クリーチャーの画像をクリップにアニメーション化します。同じデフォルト（`kling-turbo` と `1:1`）で `objects.generateMotion()` と同じように動作し、クリップを `motionClips` に追加します。 ```ts generateMotion(input: GenerateCreatureMotionInput): Promise<{ jobId: string }> ``` ```ts await client.creatures.generateMotion({ name: "Biscuit", motionPrompt: "The cat stretches, then yawns", sourceImageUrl: creature.sourceImageUrl!, attachToCreatureId: creatureId, }) ``` ## クリーチャーに話をさせる 音声に、クリーチャー専用のメソッドは必要ありません。クリーチャーのボイスでセリフをレンダリングし、それをクリーチャーの画像にリップシンクします。 ```ts const creature = await client.creatures.get(creatureId) // 1. Speak the line in the creature's voice const speech = await client.nodes.runAndWait("text-to-speech", { text: "I knocked the vase off the shelf. I regret nothing.", voice: creature.voice!.voiceId, provider: creature.voice!.ttsProvider, voiceType: creature.voice!.voiceType, }) // 2. Lip-sync the audio onto the creature's main image const clip = await client.nodes.runAndWait("lip-sync", { imageUrl: creature.sourceImageUrl!, audioUrl: speech.audioUrl, provider: "kling-avatar", }) console.log(clip.videoUrl) ``` [**リップシンク**](https://nodaro.ai/docs/nodes/video/lip-sync)（Lip Sync）ノードは、既存の動画を吹き替えることもできます。`videoUrl` と、動画に対応したモデルを渡します。`volcengine-lipsync` は、吹き替えに使えるモデルの中でいちばん料金が安く、複数の話者を扱える唯一のモデルです。 ```ts const dub = await client.nodes.runAndWait("lip-sync", { videoUrl: "https://example.com/scene.mp4", audioUrl: "https://example.com/new-vocal.mp3", provider: "volcengine-lipsync", mode: "basic", // for complex scenes openScenedet: true, // several speakers: scene and speaker detection audioDurationSec: 42, // sets the per-second price; without it, you pay for 5 minutes }) ``` クリーチャーをリファレンスとしてショットに組み込むには、`@nodaro/shared` の `toConnectedReference({ kind: "creature", id, name, url, description })` でリファレンスを作ります。画像生成が、クリーチャーの体のつくり、模様、色を保つ一文を追加します。[リファレンス](https://nodaro.ai/docs/developers/sdk/nodes#references)を参照してください。 ## Frequently asked questions ### Nodaro のオブジェクトとクリーチャーの違いは何ですか？ オブジェクトは、小道具、商品、乗り物で、アングル、素材、バリエーションの画像を持ちます。クリーチャーは、動物や空想上の生き物で、アングル、ポーズ、バリエーションの画像に加えて、種族、リファレンスボード、任意のボイスを持ちます。 ### オブジェクトのメイン画像の候補を生成するには、どうすればよいですか？ name と count を指定して client.objects.generate を呼び出します。常に jobIds が返され、候補ごとに 1 つの ID が入ります。完了したら、client.objects.approveMainImage で 1 つを承認します。 ### SDK でオブジェクトを完全に削除できますか？ できます。2 段階の手順です。まず delete() でアーカイブし、次に permanentDelete() を呼び出します。これは、オブジェクトと、それが参照するすべてのファイルを削除します。有効なオブジェクトに対しては、400 not_archived で拒否されます。 ### クリーチャーに話をさせるには、どうすればよいですか？ テキストから音声（Text to Speech）ノードとクリーチャーのボイスで音声をレンダリングし、次に、クリーチャーのメイン画像とその音声で、リップシンク（Lip Sync）ノードを実行します。