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

ロケーション

REST でロケーションを操作します。場所の作成とアーカイブ、エスタブリッシングショット、時間帯、天候、アングルのバリエーション、360 度ビュー、モーションクリップの生成ができます。

ロケーション API を使うと、ロケーションスタジオでできることを、すべてスクリプトから実行できます。ロケーションを作成し、エスタブリッシングショットの候補を生成して、そのうち 1 つを承認します。さらに、時間帯、天候、季節、カメラアングル、ライティングのバリエーションと、ループする雰囲気のクリップを追加します。その後は画像ノードと動画ノードがそのロケーションを再利用するので、同じ路地や図書館が、どのショットでも同じ見た目になります。

これらのルートは、すべてのエディションで使えます。ただし、360 度ビューのルートには Nodaro Cloud が必要です。認証には Bearer トークンを使います。個人用 API トークン(ndr_…)、OAuth アプリのトークン(ndr_app_…)、Community エディションではセッショントークンのいずれかです。認証を参照してください。

エンドポイント

メソッドパス説明
GET/v1/locations自分のロケーションを一覧表示します。
GET/v1/locations/:id1 つのロケーションを、進行中のジョブと最近の候補とともに取得します。
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-continuationNodaro Cloud のみ。360 度の見回しビューで、次のビューを生成します。
POST/v1/generate-location-motionエスタブリッシングショットをアニメーション化して、雰囲気のクリップを作ります。
POST/v1/locations/:id/approve-main-image候補をメイン画像として承認し、ロケーションの説明を作成します。
POST/v1/locations/:id/llm-caption現在のメイン画像から、説明を作成し直します。

ロケーションが持つ情報

フィールド説明
id, name, description識別子、表示名、場所の特徴についてのメモです。
categoryindoor、outdoor、urban、nature、fantasy、sci-fi、historical、futuristic、other のいずれかです。
stylerealistic、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, previousCandidatesGET /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 false

Prop

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

assetType は、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必須。開始フレームです。
providerkling(デフォルト)、kling-turbo、kling-3.0、wan-i2v、wan-2.7-i2v、seedance-2 のいずれかです。
aspectRatio16:9(デフォルト)、1:1、3:4、9:16 のいずれかです。
refineFromVideoUrl新しいプロンプトで調整する既存のクリップです。たとえば、カメラを動かさずに霧を雨に変えるときに使います。wan-i2v など、動画から動画への生成に対応したモデルを使ってください。
attachToLocationId, attachNameロケーションと、atmosphereMotions でのクリップの名前です。
モデル開発元モードクレジット詳細
Kling 2.6Kuaishou画像から動画、テキストから動画138 から画像から動画を生成する Kling 2.6 で、動きのリアルさに優れています。長さは 5 秒または 10 秒で、ネイティブオーディオを任意で付けられます。
Kling 2.5 Turbo ProKuaishou画像から動画、テキストから動画110 からより高速な Kling で、低コストで良好な品質が得られます。終了フレームに対応しています。
Kling 3.0Kuaishou画像から動画、テキストから動画270 からプレミアムな Kling 3.0 で、長さは 3〜15 秒の間で変えられ、ネイティブオーディオに対応し、720P/1080P で出力します。
Wan 2.6 I2VAlibaba画像から動画175 から画像から動画を生成する Wan 2.6 で、720p/1080p で 5/10/15 秒の動画を作ります。
Wan 2.7 I2VAlibaba画像から動画188画像から動画を生成する Wan 2.7 で、720p/1080p で 2〜15 秒の動画を作り、開始フレームと終了フレームに対応しています。
Seedance 2Bytedance画像から動画、テキストから動画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>

ロケーションのアーカイブ、復元、削除

操作curlTypeScript SDKCLI
アーカイブDELETE /v1/locations/:idclient.locations.delete(id)nodaro locations delete <id>
復元POST /v1/locations/:id/restoreclient.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 クレジットです。

エラー

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

よくある質問

最終更新

目次