ロケーション
REST でロケーションを操作します。場所の作成とアーカイブ、エスタブリッシングショット、時間帯、天候、アングルのバリエーション、360 度ビュー、モーションクリップの生成ができます。
ロケーション API を使うと、ロケーションスタジオでできることを、すべてスクリプトから実行できます。ロケーションを作成し、エスタブリッシングショットの候補を生成して、そのうち 1 つを承認します。さらに、時間帯、天候、季節、カメラアングル、ライティングのバリエーションと、ループする雰囲気のクリップを追加します。その後は画像ノードと動画ノードがそのロケーションを再利用するので、同じ路地や図書館が、どのショットでも同じ見た目になります。
これらのルートは、すべてのエディションで使えます。ただし、360 度ビューのルートには Nodaro Cloud が必要です。認証には Bearer トークンを使います。個人用 API トークン(ndr_…)、OAuth アプリのトークン(ndr_app_…)、Community エディションではセッショントークンのいずれかです。認証を参照してください。
エンドポイント
| メソッド | パス | 説明 |
|---|---|---|
GET | /v1/locations | 自分のロケーションを一覧表示します。 |
GET | /v1/locations/:id | 1 つのロケーションを、進行中のジョブと最近の候補とともに取得します。 |
POST | /v1/locations | ロケーションを作成します。ボディに id がある場合は、そのロケーションを更新します。 |
DELETE | /v1/locations/:id | ロケーションをアーカイブします。アーカイブしたロケーションは復元できます。 |
DELETE | /v1/locations/:id?permanent=true | アーカイブしたロケーションとそのファイルを、完全に削除します。 |
POST | /v1/locations/:id/restore | アーカイブしたロケーションを復元します。 |
POST | /v1/generate-location | エスタブリッシングショットの候補を 1〜10 個生成します。 |
POST | /v1/generate-location-asset | 時間帯、天候、季節、アングル、ライティング、カスタムのいずれかのバリエーションを 1 つ生成します。 |
POST | /v1/generate-surround-continuation | Nodaro Cloud のみ。360 度の見回しビューで、次のビューを生成します。 |
POST | /v1/generate-location-motion | エスタブリッシングショットをアニメーション化して、雰囲気のクリップを作ります。 |
POST | /v1/locations/:id/approve-main-image | 候補をメイン画像として承認し、ロケーションの説明を作成します。 |
POST | /v1/locations/:id/llm-caption | 現在のメイン画像から、説明を作成し直します。 |
ロケーションが持つ情報
| フィールド | 説明 |
|---|---|
id, name, description | 識別子、表示名、場所の特徴についてのメモです。 |
category | indoor、outdoor、urban、nature、fantasy、sci-fi、historical、futuristic、other のいずれかです。 |
style | realistic、anime、3d-pixar、illustration のいずれかです。 |
sourceImageUrl | 基準となるエスタブリッシングショットです。候補を承認すると設定されます。 |
canonicalDescription | メイン画像の承認時に Nodaro が作成する、80〜120 語程度の見た目の説明です。それまでは空文字列です。 |
styleLock | バリエーションをメイン画像から生成するかどうかです。デフォルトは true です。 |
timeOfDay, weather, seasons, angles, lighting, atmosphereMotions | アセットバケットです。各エントリーは { name, url } で、atmosphereMotions には動画が入ります。 |
referencePhotos | ムードボードの写真で、最大 20 枚です。各写真は { kind, url } です。 |
piiConsentAt | リファレンス写真への同意を確認した日時、または null です。 |
pendingJobs, previousCandidates | GET /v1/locations/:id でのみ返されます。まだ実行中のバリエーションのジョブと、メイン画像の最近の候補(最大 5 件、新しい順)です。 |
アセットバケット
| バケット | 内容 | プリセットのバリエーション |
|---|---|---|
timeOfDay | 同じフレームを、別の時間帯で | dawn, morning, noon, afternoon, golden hour, dusk, blue hour, night, midnight |
weather | 同じフレームを、別の天候で | clear, cloudy, light rain, heavy rain, storm, snow, blizzard, fog, mist |
seasons | 同じフレームを、別の季節で | spring, summer, autumn, winter |
angles | 場所を、別のカメラアングルから | wide, medium, closeup, aerial, low-angle, eye-level, bird's-eye, dutch tilt |
lighting | 別のライティングの設定 | soft natural, harsh sunlight, golden, blue hour, neon, candlelit, cinematic, dramatic chiaroscuro |
atmosphereMotions | ループする、雰囲気のあるカメラの動き | slow dolly-in, slow pan-left, slow pan-right, push up, drone fly-over, gentle drift, parallax, static atmospheric |
リファレンス写真と同意
ムードボードは、ロケーションと一緒に受け渡されます。ロケーションを使うすべてのノードが、これらの写真を追加のリファレンスとして受け取ります。各写真の kind は、その写真が何のためのものかをモデルに伝えます。
kind | 用途 |
|---|---|
wide | 同じ場所を、より広い範囲で写した写真です。 |
interior, exterior | メイン画像が外側を写している場合の内側の写真、またはその逆です。 |
detail | 像、看板、素材など、場所を特徴づける細部です。 |
moodBoard | 配色や雰囲気です。 |
other | 上記以外のすべてです。 |
写真は最大 20 枚まで追加でき、各種類の枚数に制限はありません。
リファレンス写真には、人の顔が写っていることがあります。ロケーションに初めて写真を追加するときは、piiConsentAt にも現在の時刻を設定してください。この値は、写真を使う権利と同意があることを記録します。この値が null の間は、次に誰かがロケーションを開いたときに、エディターが同意を求めます。
ロケーションを一覧表示して取得する
GET /v1/locations は、アクティブなロケーションを返します。アーカイブしたロケーションを取得するには、archived=true を追加します。limit を指定しない場合、このルートは一覧全体を返します。limit(最大 500)を指定すると、1 ページ分と nextCursor を返します。nextCursor が null になるまで、その値を cursor として渡してください。
GET /v1/locations/:id は、アーカイブ済みかどうかにかかわらず、1 つのロケーションを返します。そのため、アーカイブしたロケーションを使うワークフローも、引き続き動作します。
curl "https://app.nodaro.ai/v1/locations?limit=100" \
-H "Authorization: Bearer $NODARO_API_KEY"
curl https://app.nodaro.ai/v1/locations/9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f \
-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 { locations } = await client.locations.list()
const alley = await client.locations.get(locations[0].id)
console.log(alley.previousCandidates)nodaro locations list --json
nodaro locations get <id> --jsonロケーションを作成または更新する
POST /v1/locations は、ボディに id がない場合はロケーションを作成し、id がある場合はそのロケーションを更新します。作成には nodeId と name が必要です。キャンバスのノードがない場合は、nodeId に "scripted" のような任意のラベルを使います。
更新では、送信したフィールドだけが書き込まれ、アセットバケットが書き込まれることはありません。ロケーションの現在の updatedAt を expectedUpdatedAt として送ると、読み取った後に誰かがロケーションを変更していた場合に、更新が 409 concurrent_modification で拒否されます。
curl -X POST https://app.nodaro.ai/v1/locations \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodeId": "scripted",
"name": "Rainy Tokyo Alley",
"description": "Neon-soaked alley with vending machines and wet pavement",
"category": "urban",
"style": "realistic"
}'const { id } = await client.locations.create({
nodeId: 'scripted',
name: 'Rainy Tokyo Alley',
description: 'Neon-soaked alley with vending machines and wet pavement',
category: 'urban',
style: 'realistic',
})
const location = await client.locations.get(id)
await client.locations.update(id, {
referencePhotos: [{ kind: 'wide', url: 'https://cdn.nodaro.ai/uploads/alley-wide.jpg' }],
piiConsentAt: new Date().toISOString(),
expectedUpdatedAt: location.updatedAt,
})nodaro locations create "Rainy Tokyo Alley" --node-id scripted \
--description "Neon-soaked alley with vending machines and wet pavement" \
--category urban --style realistic
nodaro locations update <id> --style-lock falseProp
Type
作成すると、{ id } が返されます。
スタイルの固定は、バリエーションの作り方を決めます。スタイルの固定がオン(デフォルト)の場合、すべてのバリエーションが承認済みのメイン画像から生成されるため、建物、素材、構図が同じに保たれます。スタイルの固定がオフの場合、バリエーションはテキストだけから生成され、場所が解釈し直されることがあります。
エスタブリッシングショットの候補を生成する
POST /v1/generate-location は、候補ごとに 1 つのジョブを開始し、jobIds を返します。候補が 1 つのリクエストでは、jobId も返されます。
- 候補 1 つを関連付ける:
attachToLocationIdを指定してcountを 1 にすると、ジョブの完了時に結果がメイン画像になります。 - 複数の候補:何も関連付けられません。現在のメイン画像はそのまま残り、完了した候補は
GET /v1/locations/:idのpreviousCandidatesに表示されます。気に入った候補を承認してください。 - 現在のショットを編集する:
userPromptは、その 1 回だけの指示です。たとえば「add rain and puddles」のように書きます。sourceImageUrlを指定すると、元画像が指示に沿って編集されます。指示がロケーションに保存されることはありません。
curl -X POST https://app.nodaro.ai/v1/generate-location \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Rainy Tokyo Alley",
"count": 1,
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f"
}'const { jobIds } = await client.locations.generate({
name: 'Rainy Tokyo Alley',
description: 'Neon-soaked alley with vending machines',
count: 4,
})nodaro locations generate --name "Rainy Tokyo Alley" --count 1 \
--attach-to-location-id <id> --watch{ "jobId": "4d6f8b1a-3c5e-4f7a-9b2d-6e8a1c3f5b7d", "jobIds": ["4d6f8b1a-3c5e-4f7a-9b2d-6e8a1c3f5b7d"] }| フィールド | 説明 |
|---|---|
name | 必須。ロケーションの名前です。 |
description, category, style | ロケーションの基本情報です。 |
count | 生成する候補の数で、1〜10 です。デフォルトは 1 です。 |
userPrompt | 今回の生成だけに使う指示です。保存されません。 |
sourceImageUrl | 編集する画像、または生成の起点にする画像です。 |
provider | 画像モデルの ID です。デフォルトのモデルを使う場合は省略します。 |
quality, resolution | 画像モデルの出力の段階です。料金は画像生成(Generate Image)と同じです。 |
attachToLocationId | 候補が 1 つの場合に、その候補をこのロケーションに関連付けます。 |
quality と resolution は、キャラクターの場合と同じように動作します。モデルが対応していない値は、対応している最も近い値に変更され、クレジットも変更後の値に従います。実際に使われた値は、ジョブの input_data で確認できます。
バリエーションを生成する
POST /v1/generate-location-asset は、バリエーションを 1 つ生成し、{ jobId } を返します。attachToLocationId、attachToColumn、attachName を送ると、ジョブの完了時に { name: attachName, url } がバケットに追加されます。
curl -X POST https://app.nodaro.ai/v1/generate-location-asset \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Rainy Tokyo Alley",
"assetType": "weather",
"variant": "storm",
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f",
"attachToColumn": "weather",
"attachName": "storm"
}'await client.locations.generateAsset({
name: 'Rainy Tokyo Alley',
assetType: 'timeOfDay',
variant: 'blue hour',
attachToLocationId: id,
attachToColumn: 'time_of_day',
attachName: 'blue hour',
})nodaro locations generate-asset <id> --asset-type weather --variant storm --watchassetType は、timeOfDay、weather、seasons、angles、lighting、custom のいずれかです。attachToColumn は、time_of_day、weather、seasons、angles、lighting のいずれかで、custom のバリエーションでは必ず指定します。このルートは、provider、quality、resolution、sourceImageUrl も受け付けます。
360 度ビューを作る
POST /v1/generate-surround-continuation は、見回しビューを 1 ビューずつ、たとえば 45 度ごとに組み立てます。各呼び出しは、前のビューの続きを作ります。Nodaro は、前のビューの端を新しいフレームに引き継ぎ、残りの部分だけを描きます。次に、描いた部分の露出と色を、引き継いだ部分に合わせます。引き継いだ部分はピクセル単位で正確に保たれるため、パノラマビューアーで隣り合うビューがぴったりつながります。このルートには Nodaro Cloud が必要です。ほかのエディションでは、403 edition_required が返されます。
curl -X POST https://app.nodaro.ai/v1/generate-surround-continuation \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"referenceImageUrl": "https://cdn.nodaro.ai/locations/alley-main.png",
"direction": "right",
"degrees": 45,
"provider": "nano-banana-pro",
"aspectRatio": "16:9",
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f",
"attachToColumn": "angles",
"attachName": "Surround 45°"
}'const { jobId } = await client.locations.generateSurroundContinuation({
referenceImageUrl: previousView,
direction: 'right',
degrees: 45,
provider: 'nano-banana-pro',
aspectRatio: '16:9',
attachToLocationId: id,
attachToColumn: 'angles',
attachName: 'Surround 45°',
})| フィールド | 説明 |
|---|---|
referenceImageUrl | 必須。続きを作る元になる、前のビューです。 |
direction | 必須。横に回すには right か left、縦に傾けるには up か down を指定します。 |
degrees | このビューの角度で、0〜360 です。結果と一緒に保存されます。 |
carriedFraction | 前のビューから引き継ぐフレームの割合で、0.1〜0.9 です。デフォルトは、横に回す場合は 0.5、縦に傾ける場合は細い帯状の部分です。 |
provider, aspectRatio | 画像モデルとフレームの形です。エディターは、すべてのビューがエスタブリッシングショットと一致するように、nano-banana-pro と 16:9 を使います。 |
attachToLocationId, attachToColumn, attachName | ビューを関連付けます。通常は angles バケットに関連付けます。 |
ビュー 1 つにつき、選んだ画像モデルでの生成 1 回分の費用がかかります。引き継ぎと色合わせに、別途料金はかかりません。
エスタブリッシングショットをアニメーション化する
POST /v1/generate-location-motion は、エスタブリッシングショットを、漂う霧、ゆっくりしたドリー、ドローンでの上空通過のような環境クリップに変えます。このルートは { jobId } を返します。sourceImageUrl は必須で、承認済みのメイン画像を渡します。attachToLocationId と attachName を指定すると、クリップが atmosphereMotions に追加されます。列を指定する必要はありません。
curl -X POST https://app.nodaro.ai/v1/generate-location-motion \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Rainy Tokyo Alley",
"motionPrompt": "slow dolly-in, neon signs flicker, light rain falling",
"sourceImageUrl": "https://cdn.nodaro.ai/locations/alley-main.png",
"provider": "kling",
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f",
"attachName": "neon dolly-in"
}'await client.locations.generateMotion({
name: 'Rainy Tokyo Alley',
motionPrompt: 'slow dolly-in, neon signs flicker, light rain falling',
sourceImageUrl: location.sourceImageUrl!,
provider: 'kling',
attachToLocationId: id,
attachName: 'neon dolly-in',
})nodaro locations generate-motion --name "Rainy Tokyo Alley" \
--motion-prompt "slow dolly-in, neon signs flicker, light rain falling" \
--source-image-url "https://cdn.nodaro.ai/locations/alley-main.png" \
--provider kling --attach-to-location-id <id> --attach-name "neon dolly-in" --watch| フィールド | 説明 |
|---|---|
name, motionPrompt | 必須。ロケーションの名前と、作りたい動きです。 |
sourceImageUrl | 必須。開始フレームです。 |
provider | kling(デフォルト)、kling-turbo、kling-3.0、wan-i2v、wan-2.7-i2v、seedance-2 のいずれかです。 |
aspectRatio | 16:9(デフォルト)、1:1、3:4、9:16 のいずれかです。 |
refineFromVideoUrl | 新しいプロンプトで調整する既存のクリップです。たとえば、カメラを動かさずに霧を雨に変えるときに使います。wan-i2v など、動画から動画への生成に対応したモデルを使ってください。 |
attachToLocationId, attachName | ロケーションと、atmosphereMotions でのクリップの名前です。 |
| モデル | 開発元 | モード | クレジット | 詳細 |
|---|---|---|---|---|
| Kling 2.6 | Kuaishou | 画像から動画、テキストから動画 | 138 から | 画像から動画を生成する Kling 2.6 で、動きのリアルさに優れています。長さは 5 秒または 10 秒で、ネイティブオーディオを任意で付けられます。 |
| Kling 2.5 Turbo Pro | Kuaishou | 画像から動画、テキストから動画 | 110 から | より高速な Kling で、低コストで良好な品質が得られます。終了フレームに対応しています。 |
| Kling 3.0 | Kuaishou | 画像から動画、テキストから動画 | 270 から | プレミアムな Kling 3.0 で、長さは 3〜15 秒の間で変えられ、ネイティブオーディオに対応し、720P/1080P で出力します。 |
| Wan 2.6 I2V | Alibaba | 画像から動画 | 175 から | 画像から動画を生成する Wan 2.6 で、720p/1080p で 5/10/15 秒の動画を作ります。 |
| Wan 2.7 I2V | Alibaba | 画像から動画 | 188 | 画像から動画を生成する Wan 2.7 で、720p/1080p で 2〜15 秒の動画を作り、開始フレームと終了フレームに対応しています。 |
| Seedance 2 | Bytedance | 画像から動画、テキストから動画 | 230 から | Seedance 2 は、ネイティブオーディオ付きのプレミアムなティアです。料金は解像度ごとの秒単位です。 |
メイン画像を承認する
POST /v1/locations/:id/approve-main-image に { candidateJobId } を送ると、完了した候補がメイン画像に設定され、同じ呼び出しの中で canonicalDescription が作成されます。レスポンスは { sourceImageUrl, canonicalDescription } です。
説明の作成に失敗した場合でも、メイン画像は設定され、canonicalDescription は空文字列になります。SDK では null が返されます。もう一度試すには、POST /v1/locations/:id/llm-caption を呼び出します。このルートは { canonicalDescription } を返します。説明を作成できなかった場合は 502 を、メイン画像がまだない場合は 400 no_source_image を返します。どちらのルートも、繰り返し呼び出して問題ありません。承認は無料です。llm-caption は呼び出し 1 回につき 7 クレジットかかり、失敗した呼び出し(502)の分は返還されます。
curl -X POST https://app.nodaro.ai/v1/locations/9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f/approve-main-image \
-H "Authorization: Bearer $NODARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "candidateJobId": "4d6f8b1a-3c5e-4f7a-9b2d-6e8a1c3f5b7d" }'const { sourceImageUrl, canonicalDescription } =
await client.locations.approveMainImage(id, jobIds[2])nodaro locations approve-main-image <id> --candidate-job-id <jobId>
nodaro locations recaption <id>ロケーションのアーカイブ、復元、削除
| 操作 | curl | TypeScript SDK | CLI |
|---|---|---|---|
| アーカイブ | DELETE /v1/locations/:id | client.locations.delete(id) | nodaro locations delete <id> |
| 復元 | POST /v1/locations/:id/restore | client.locations.restore(id) | nodaro locations restore <id> |
| 完全な削除 | DELETE /v1/locations/:id?permanent=true | 利用できません | 利用できません |
- アーカイブ:
{ success: true, archived: true }を返します。ロケーションはデフォルトの一覧から外れますが、ID を指定すれば引き続き読み込めます。 - 復元:
{ id, name }を返します。大文字と小文字を区別せずに同じ名前のアクティブなロケーションがある場合は、名前の末尾に(restored)が付きます。 - 完全な削除:アーカイブしたロケーションにだけ使えます(それ以外では
400 not_archivedが返されます)。ロケーションと、そのロケーションが参照するすべてのファイルを削除します。SDK と CLI には、この操作はありません。エディターのアーカイブの表示では、確認のために名前の入力を求められます。
アプリの実行時にバリエーションを選ぶ
ロケーションアセット(Location Asset)ノードを含むワークフローをアプリとして公開すると、ロケーションはアプリの入力の 1 つになります。"<bucket>/<variant>"(たとえば "weather/light-rain")を渡すと、その実行では、そのバリエーションがロケーションのメイン画像として使われます。バリエーション名は小文字で書き、スペースはハイフンにします。不明なバケットやバリエーションを指定した場合は、メイン画像が使われます。
ほかの生成でロケーションを使う
ロケーションのアセットの URL を、リファレンス画像として画像生成や動画生成(Generate Video)に渡します。コードでは、URL を明示的に指定するのが最も簡単です。ワークフローでは、ロケーションのノードを画像ノードに接続するか、プロンプトでバリエーションをメンションします。たとえば、Old Library という名前のロケーションなら @oldlibrary:1:weather/rain と書きます。メンションがない場合、Nodaro はプロンプトからバリエーション名を探します。たとえば dusk のバリエーションがあれば、「at sunset」でそのバリエーションが選ばれます。ロケーションを参照してください。
MCP から使う
| ツール | 説明 |
|---|---|
list_locations, get_location | ロケーションを探し、そのバリエーションの URL を読み取ります。 |
create_location, update_location | ロケーションを作成するか、その基本情報のフィールドを変更します。 |
generate_location | メイン画像(kind: "main")またはバリエーション(kind: "asset")を生成します。 |
generate_location_motion | メイン画像をアニメーション化します。 |
approve_main_image, recaption_location | メイン画像を承認するか、その説明を作成し直します。 |
アーカイブと復元は、意図的に MCP では使えないようにしています。MCP ツールリファレンスを参照してください。
クレジット
| ルート | Nodaro Cloud での料金 |
|---|---|
POST /v1/generate-location | 画像モデルの料金 × count です。最初のジョブが始まる前に、すべての候補の分が確保されます。 |
POST /v1/generate-location-asset | バリエーション 1 つにつき、画像モデルの料金です。 |
POST /v1/generate-surround-continuation | ビュー 1 つにつき、画像モデルの料金です。 |
POST /v1/generate-location-motion | クリップ 1 本につき、動画モデルで画像から動画を生成する料金です。 |
approve-main-image | 無料です。 |
llm-caption | 呼び出し 1 回につき 7 クレジットです。 |
エラー
| ステータス | コード | 説明 |
|---|---|---|
400 | validation_error | フィールドが不足しているか、無効です。 |
400 | not_archived | アーカイブされていないロケーションに対して、完全な削除が送信されました。 |
400 | no_source_image | ロケーションにメイン画像がない状態で、llm-caption が呼び出されました。 |
401 | unauthorized | トークンがないか、無効か、取り消されています。 |
402 | insufficient_credits | Nodaro Cloud のみ。アカウントの残高では、確保に必要なクレジットが足りません。 |
403 | edition_required | Community エディションまたは Business エディションで、360 度ビューのルートが呼び出されました。 |
404 | not_found | その ID を持つ自分のロケーションがありません。 |
409 | concurrent_modification | expectedUpdatedAt が一致しなくなりました。ロケーションを読み取り直し、変更をマージしてから再試行してください。 |
502 | — | 基準となる説明を作成できませんでした。もう一度試してください。 |
よくある質問
関連ページ
ロケーション
ロケーションアセット
キャラクター
オブジェクト
ジョブ
最終更新