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

オブジェクト

小道具と商品を REST で操作します。オブジェクトの作成とアーカイブ、メイン画像、素材とアングルのバリエーション、モーションクリップの生成、メイン画像の承認ができます。

オブジェクト API を使うと、オブジェクト/小道具スタジオが小道具と商品に対して行うことを、すべてスクリプトから実行できます。オブジェクトを作成し、メイン画像の候補を生成して、そのうち 1 つを承認し、アングル、素材、バリエーションの画像とモーションクリップを追加します。その後は画像ノードと動画ノードがそのオブジェクトを再利用するので、同じランタン、車、椅子がどのショットでも同じ見た目になります。

これらのルートは、すべてのエディションで使えます。認証にはベアラートークンを使います。個人用 API トークン(ndr_…)、OAuth アプリのトークン(ndr_app_…)、Community エディションではセッショントークンのいずれかです。すべてのルートは呼び出し元に限定されています。認証を参照してください。

エンドポイント

メソッドパス説明
GET/v1/objects自分のオブジェクトを一覧表示します。
GET/v1/objects/:id1 つのオブジェクトを、進行中のジョブとともに取得します。
POST/v1/objectsオブジェクトを作成します。ボディに id がある場合は、そのオブジェクトを更新します。
DELETE/v1/objects/:idオブジェクトをアーカイブします。復元できます。
DELETE/v1/objects/:id?permanent=trueアーカイブしたオブジェクトと、そのファイルを完全に削除します。
POST/v1/objects/:id/restoreアーカイブしたオブジェクトを復元します。
POST/v1/generate-objectメイン画像の候補を生成します。
POST/v1/generate-object-assetアングル、素材、variations バケットの画像、またはカスタムバリエーションを 1 つ生成します。
POST/v1/generate-object-motionメイン画像をアニメーション化して、モーションクリップにします。
POST/v1/objects/:id/approve-main-image候補をメイン画像として承認し、オブジェクトの説明を作成します。
POST/v1/objects/:id/llm-caption現在のメイン画像から、説明を作成し直します。

オブジェクトが持つ情報

フィールド内容
id、name、description識別子、表示名、アイデンティティのメモです。
categoryfurniture、vehicle、weapon、food、clothing、electronics、nature、tool、animal、other のいずれかです。
stylerealistic、anime、3d-pixar、illustration のいずれかです。
sourceImageUrl基準となるメイン画像です。候補を承認すると設定されます。
canonicalDescriptionメイン画像の承認時に Nodaro が作成する、80〜120 語程度の見た目の説明です。それまでは空の文字列です。
styleLockバリエーションをメイン画像から生成するかどうかです。デフォルトは true です。
angles、materials、variations、motionClipsアセットバケットです。各エントリーは { name, url } です。motionClips には動画が入ります。
referencePhotos最大 20 枚のムードボード写真で、それぞれ { kind, url } の形式です。
pendingJobsGET /v1/objects/:id を取得した場合のみ。このオブジェクトについて、まだ実行中のバリエーションのジョブです。

アセットバケット

バケット内容プリセットのバリエーション
angles別の視点から見たオブジェクトfront, side, top, back, three-quarter, detail, in-context, exploded, perspective
materials別の素材のオブジェクトwood, metal, glass, plastic, fabric, stone, ceramic, leather, paper, gold, silver, copper, marble
variations別の状態やスタイルclean, weathered, damaged, ornate, minimal, broken, antique, futuristic, holographic, dirty, polished
motionClipsループするカメラワークのクリップrotate-360, hover, spin-slow, parallax, pulse, drift, dolly-around, push-in, drone-orbit

リファレンス写真

ムードボードは、オブジェクトと一緒に渡されます。オブジェクトを使うすべてのノードは、画像を接続していなくても、これらの写真を追加のリファレンスとして受け取ります。各写真の kind が、その写真が何のためのものかをモデルに伝えます。

kind用途
frontすっきりした正面図です。
side側面図です。乗り物、家具、武器で役立ちます。
detail特徴的な部分のクローズアップです。彫刻やヒンジなどです。
context実際に置かれた、持たれた、取り付けられた状態のオブジェクトです。大きさの目安になります。
moodBoard配色や雰囲気です。
otherそれ以外のものです。

写真は最大 20 枚まで追加でき、各種類の枚数に制限はありません。主役の小道具や看板商品では、最初の生成の前に 3〜6 枚の写真を追加してください。最初の結果が、はるかに忠実になります。

オブジェクトを一覧表示する

GET /v1/objects は、自分のアクティブなオブジェクトを新しい順に返します。アーカイブを見るには archived=true を、1 つのプロジェクトに絞るには projectId を追加します。limit を指定しない場合、ルートは全件を返します。limit(最大 500)を指定すると、1 ページ分と nextCursor を返すので、null になるまで cursor として渡し続けてください。

curl "https://app.nodaro.ai/v1/objects?limit=100" \
  -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 page = await client.objects.list({ limit: 100 })
const next = await client.objects.list({ limit: 100, cursor: page.nextCursor! })
const { objects: archived } = await client.objects.listArchived()
nodaro objects list --json
nodaro objects list --archived

GET /v1/objects/:id は、pendingJobs を含む 1 つのオブジェクトを返します。アーカイブされたオブジェクトは 404 not_found を返します。これは、存在しないオブジェクトと同じ応答です。

オブジェクトを作成または更新する

POST /v1/objects は、ボディに id がない場合はオブジェクトを作成し、id がある場合はそのオブジェクトを更新します。作成には nodeId と name が必要です。キャンバスのノードがない場合は、nodeId に "scripted" のような任意のラベルを使います。

更新では、送信したフィールドだけが書き込まれます。アセットバケットは更新では書き込まれないため、保存によって、ジョブが追加中のバリエーションが上書きされることはありません。オブジェクトの現在の updatedAt を expectedUpdatedAt として送信すると、読み取った後にほかの誰かがオブジェクトを変更していた場合に更新を拒否できます。その場合、ルートは 409 concurrent_modification を返します。

curl -X POST https://app.nodaro.ai/v1/objects \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Antique Lantern",
    "description": "Weathered brass lantern with hand-engraved filigree",
    "category": "tool",
    "style": "realistic"
  }'
const { id } = await client.objects.create({
  nodeId: 'scripted',
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  category: 'tool',
  style: 'realistic',
})

const object = await client.objects.get(id)
await client.objects.update(id, { styleLock: false, expectedUpdatedAt: object.updatedAt })
nodaro objects create "Antique Lantern" --node-id scripted \
  --description "Weathered brass lantern with hand-engraved filigree" \
  --category tool --style realistic

nodaro objects update <id> --style-lock false

作成は { id } を返します。更新は { id, updatedAt } を返します。

Prop

Type

スタイルの固定が変えるもの

  • オン(デフォルト)。すべてのアングル、素材、バリエーションが、承認済みのメイン画像から生成されます。どれも、プロポーション、シルエット、特徴的な部分を保ちます。オブジェクトを使うノードは、基準となる説明も受け取ります。どのショットでも同じアイテムに見せたいものに使います。
  • オフ。バリエーションはテキストだけから生成されます。ノードは基準となる説明を受け取りますが、目安として扱われるだけなので、モデルがデザインを解釈し直すことがあります。別の案を検討したり、見た目を比較したりするときに使います。

メイン画像の候補を生成する

POST /v1/generate-object は、候補ごとに 1 つのジョブを開始し、候補ごとの ID を含む jobIds をすぐに返します。候補が 1 つだけのリクエストでは、jobId も返されます。ジョブはジョブ API でポーリングしてください。

attachToObjectId と count に 1 を指定すると、ジョブが完了したときに、結果がオブジェクトのメイン画像になります。候補が複数の場合は、何もアタッチされません。気に入ったものを承認してください。

curl -X POST https://app.nodaro.ai/v1/generate-object \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Antique Lantern", "count": 4 }'
const { jobIds } = await client.objects.generate({
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  count: 4,
})
nodaro objects generate --name "Antique Lantern" --count 1 \
  --attach-to-object-id <id> --watch
{
  "jobIds": [
    "5e2a8c1f-3b7d-4f9a-a6c2-8d1e4b7f0a3c",
    "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d",
    "7a4c1e3b-5d9f-4b2c-c8e4-1f3a6d9b2c5e",
    "8b5d2f4c-6e1a-4c3d-d9f5-2a4b7e1c3d6f"
  ]
}
フィールド説明
name必須。オブジェクトの名前で、1〜200 文字です。
descriptionアイデンティティのメモで、最大 2,000 文字です。
category、styleオブジェクトのカテゴリーと、ビジュアルスタイルです。
count生成する候補の数で、1〜10 です。デフォルトは 1 です。
provider画像モデルの ID です。省略すると、デフォルトのモデルを使います。
seedPromptHintプロンプトに組み込むプロンプトの断片で、最大 2,000 文字です。たとえば、素材(Material)ピッカーの antique brass です。
sourceImageUrl元にする画像です。
aspectRatioメイン画像のフレームです。
attachToObjectId、expectedUpdatedAt候補 1 つをこのオブジェクトにアタッチします。オブジェクトが変更されていない場合のみアタッチするよう指定することもできます。

seedPromptHint は、generate-object-asset と generate-object-motion でも使えます。乗り物や素材などのカタログの選択肢を、ピッカーノードを接続せずにプロンプトへ組み込めます。

バリエーションを生成する

POST /v1/generate-object-asset は、1 つのバリエーションを生成し、{ jobId } を返します。ジョブが完了したときにバケットへ { name: attachName, url } を追加するには、attachToObjectId、attachToColumn、attachName を送信します。

curl -X POST https://app.nodaro.ai/v1/generate-object-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "assetType": "materials",
    "variant": "gold",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachToColumn": "materials",
    "attachName": "gold"
  }'
await client.objects.generateAsset({
  name: 'Antique Lantern',
  assetType: 'variations',
  variant: 'weathered',
  attachToObjectId: id,
  attachToColumn: 'variations',
  attachName: 'weathered',
})
nodaro objects generate-asset --asset-type materials --variant gold \
  --attach-to-object-id <id> --attach-to-column materials --watch
フィールド説明
name必須。オブジェクトの名前です。
assetType必須。angles、materials、variations、custom のいずれかです。
variant必須。生成するバリエーションで、1〜100 文字です。
descriptionこのバリエーションの説明で、最大 1,000 文字です。オブジェクトにアタッチする際にこれを省略すると、Nodaro がオブジェクトの基準となる説明とバリエーション名から作成します。自分で指定すると、この自動作成をスキップします。
provider、sourceImageUrl、aspectRatio画像モデル、元にする画像、フレームです。
attachToObjectId、attachToColumn、attachName結果の保存先です。attachToColumn は angles、materials、variations のいずれかで、custom のバリエーションでは必ず指定します。

メイン画像をアニメーション化する

POST /v1/generate-object-motion は、オブジェクトの画像を、ゆっくりとした回転、浮遊、ドローン周回などの短いカメラワークのクリップにします。クリップは、B ロールや、長い動画の出発点として使えます。ルートは { jobId } を返します。

sourceImageUrl は必須です。フォールバックはないため、承認済みのメイン画像を渡してください。attachToObjectId と attachName を指定すると、完了時にクリップが motionClips に追加されます。列を指定する必要はありません。

curl -X POST https://app.nodaro.ai/v1/generate-object-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "motionPrompt": "slow 360 rotation, soft golden rim light",
    "sourceImageUrl": "https://cdn.nodaro.ai/objects/lantern-main.png",
    "provider": "kling-turbo",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachName": "rotate-360"
  }'
const lantern = await client.objects.get(id)

await client.objects.generateMotion({
  name: 'Antique Lantern',
  motionPrompt: 'slow 360 rotation, soft golden rim light',
  sourceImageUrl: lantern.sourceImageUrl!,
  provider: 'kling-turbo',
  attachToObjectId: id,
  attachName: 'rotate-360',
})
nodaro objects generate-motion --name "Antique Lantern" \
  --motion-prompt "slow 360 rotation, soft golden rim light" \
  --source-image-url "https://cdn.nodaro.ai/objects/lantern-main.png" \
  --provider kling-turbo --attach-to-object-id <id> --attach-name "rotate-360" --watch
フィールド説明
name、motionPrompt必須。オブジェクトの名前と、作り出す動きです。
sourceImageUrl必須。開始フレームです。
providerkling-turbo(デフォルト)、kling、kling-3.0、minimax、hailuo-2.3、wan-i2v、seedance、bytedance-lite のいずれかです。
aspectRatio1:1(デフォルト。中央に配置された商品フレーム)、3:4、16:9、9:16、4:3 のいずれかです。
refineFromVideoUrl画像からやり直す代わりに、新しいプロンプトで調整する既存のクリップです。構図は保たれます。wan-i2v など、動画から動画への変換に対応したモデルを使ってください。
attachToObjectId、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 の最も安価な動画ティアです。

メイン画像を承認する

POST /v1/objects/:id/approve-main-image は、完了した候補をメイン画像に設定し、同じ呼び出しの中で canonicalDescription を作成します。これは、以降のプロンプトがオブジェクトを説明するために使うテキストです。ボディは { candidateJobId, expectedUpdatedAt? } で、候補は自分の completed のジョブである必要があります。

ルートは { sourceImageUrl, canonicalDescription } を返します。説明の作成に失敗した場合でも、メイン画像は設定され、canonicalDescription は空の文字列になります。SDK は、代わりに null を返します。もう一度試すには、POST /v1/objects/:id/llm-caption を呼び出します。このルートは { canonicalDescription } を返し、説明を作成できなかった場合は 502 を、メイン画像がまだない場合は 400 main_image_required を返します。expectedUpdatedAt は受け付けません。繰り返し呼び出しても問題ありません。

curl -X POST https://app.nodaro.ai/v1/objects/2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d" }'
const approved = await client.objects.approveMainImage(id, jobIds[1])
if (approved.canonicalDescription === null) {
  await client.objects.recaption(id)
}
nodaro objects approve-main-image <id> --candidate-job-id <jobId>
nodaro objects recaption <id>

オブジェクトのアーカイブ、復元、削除

操作curlTypeScript SDKCLI
アーカイブDELETE /v1/objects/:idclient.objects.delete(id)nodaro objects delete <id>
復元POST /v1/objects/:id/restoreclient.objects.restore(id)nodaro objects restore <id>
完全な削除DELETE /v1/objects/:id?permanent=trueclient.objects.permanentDelete(id)nodaro objects delete <id> --permanent
  • アーカイブ:{ success: true, archived: true } を返します。アーカイブ済みのオブジェクトをアーカイブしても、何も変わりません。
  • 復元:{ id, name } を返します。大文字と小文字を区別せずに同じ名前のアクティブなオブジェクトがある場合、Nodaro は名前の末尾に (restored) を付け、新しい名前を返します。
  • 完全な削除:{ success: true, permanent: true } を返し、オブジェクトと、それが参照するすべてのファイルを削除します。メイン画像、バリエーション、クリップ、リファレンス写真です。アーカイブされたオブジェクトにしか使えません。アクティブなオブジェクトに使うと 400 not_archived が返されます。先にアーカイブしてから削除してください。

アプリを実行するときにバリエーションを選ぶ

オブジェクト/小道具アセット(Object/Props Asset)ノードを含むワークフローをアプリとして公開すると、オブジェクトはアプリの入力の 1 つになります。その実行でバリエーションをオブジェクトのメイン画像として使うには、"<bucket>/<variant>" を渡します。たとえば "materials/gold" です。バリエーション名は、小文字にしてスペースをハイフンに変えて書きます。polished-brass は、Polished Brass という名前のバリエーションに一致します。不明なバケットやバリエーションは、メイン画像にフォールバックします。アプリの実行については、ワークフローを参照してください。

ほかの生成でオブジェクトを使う

オブジェクトのアセット URL を、画像生成(Generate Image)や動画生成(Generate Video)にリファレンス画像として渡します。コードでは、明示的な URL がいちばん簡単な方法です。ワークフローでは、オブジェクトノードを画像ノードに接続するか、プロンプトでバリエーションをメンションします。たとえば、Lantern という名前のオブジェクトでは @lantern:1:materials/gold です。メンションせずにオブジェクトを接続した場合、Nodaro はプロンプト内のバリエーション名も探します。「gold finish」は materials/gold を選びます。オブジェクトを参照してください。

MCP から使う

ツール説明
list_objects、get_objectオブジェクトを探し、そのバリエーションの URL を読み取ります。
generate_objectメイン画像またはバリエーションを生成します。
approve_object_main_image、recaption_objectメイン画像を承認するか、その説明を作成し直します。
generate_object_motionメイン画像をアニメーション化します。

オブジェクトの作成、更新、アーカイブ、復元、削除を行う MCP ツールはありません。generate_object が作成を行い、それ以外の変更は REST、SDK、CLI で行います。MCP ツールリファレンスを参照してください。

クレジット

ルートNodaro Cloud での料金
POST /v1/generate-object画像モデルの料金 × count です。最初のジョブが始まる前に、すべての候補の分が確保されます。
POST /v1/generate-object-assetバリエーション 1 つにつき、画像モデルの料金です。
POST /v1/generate-object-motionクリップ 1 本につき、動画モデルで画像から動画を生成する料金です。
approve-main-image無料です。
llm-caption呼び出し 1 回につき 7 クレジットです。

エラー

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

よくある質問

最終更新

目次