# ロケーション

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

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

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

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

## エンドポイント
| メソッド | パス | 説明 |
| --- | --- | --- |
| `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**

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

**TypeScript SDK**

```ts

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)
```

**CLI**

```bash
nodaro locations list --json
nodaro locations get <id> --json
```

## ロケーションを作成または更新する
`POST /v1/locations` は、ボディに `id` がない場合はロケーションを作成し、`id` がある場合はそのロケーションを更新します。作成には `nodeId` と `name` が必要です。キャンバスのノードがない場合は、`nodeId` に `"scripted"` のような任意のラベルを使います。

更新では、送信したフィールドだけが書き込まれ、アセットバケットが書き込まれることはありません。ロケーションの現在の `updatedAt` を `expectedUpdatedAt` として送ると、読み取った後に誰かがロケーションを変更していた場合に、更新が `409 concurrent_modification` で拒否されます。

**curl**

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

**TypeScript SDK**

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

**CLI**

```bash
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
```

<TypeTable
type={{
id: { type: 'string (uuid)', description: '更新するロケーションです。ロケーションを作成する場合は省略します。' },
nodeId: { type: 'string', description: '作成時は必須です。ロケーションが属するキャンバスのノードです。ノードがない場合は、任意のラベルを指定します。' },
name: { type: 'string', description: '作成時は必須です。' },
description: { type: 'string', description: 'その場所の特徴を、1〜3 文で書きます。' },
category: { type: 'string', description: 'indoor、outdoor、urban、nature、fantasy、sci-fi、historical、futuristic、other のいずれかです。' },
style: { type: 'string', description: 'realistic、anime、3d-pixar、illustration のいずれかです。' },
styleLock: { type: 'boolean', description: '承認済みのメイン画像からバリエーションを生成します。', default: 'true' },
referencePhotos: { type: 'array', description: '{ kind, url } 形式のムードボードの写真で、最大 20 枚です。' },
piiConsentAt: { type: 'string (ISO 8601)', description: 'リファレンス写真の権利と同意を確認した日時です。初めて写真を追加するときに設定します。' },
canonicalDescription: { type: 'string', description: '作成された説明を置き換えます。' },
sourceImageUrl: { type: 'string', description: 'メイン画像を直接設定します。' },
projectId: { type: 'string (uuid)', description: 'ロケーションを登録するプロジェクトです。' },
expectedUpdatedAt: { type: 'string (ISO 8601)', description: '更新時に使います。このタイムスタンプ以降にロケーションが変更されていた場合、409 で書き込みを拒否します。' },
}}
/>

作成すると、`{ 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**

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

**TypeScript SDK**

```ts
const { jobIds } = await client.locations.generate({
name: 'Rainy Tokyo Alley',
description: 'Neon-soaked alley with vending machines',
count: 4,
})
```

**CLI**

```bash
nodaro locations generate --name "Rainy Tokyo Alley" --count 1 \
  --attach-to-location-id <id> --watch
```

```json
{ "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）](https://nodaro.ai/docs/nodes/image/generate-image)と同じです。 |
| `attachToLocationId` | 候補が 1 つの場合に、その候補をこのロケーションに関連付けます。 |

`quality` と `resolution` は、キャラクターの場合と同じように動作します。モデルが対応していない値は、対応している最も近い値に変更され、クレジットも変更後の値に従います。実際に使われた値は、ジョブの `input_data` で確認できます。

## バリエーションを生成する
`POST /v1/generate-location-asset` は、バリエーションを 1 つ生成し、`{ jobId }` を返します。`attachToLocationId`、`attachToColumn`、`attachName` を送ると、ジョブの完了時に `{ name: attachName, url }` がバケットに追加されます。

**curl**

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

**TypeScript SDK**

```ts
await client.locations.generateAsset({
name: 'Rainy Tokyo Alley',
assetType: 'timeOfDay',
variant: 'blue hour',
attachToLocationId: id,
attachToColumn: 'time_of_day',
attachName: 'blue hour',
})
```

**CLI**

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

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

**TypeScript SDK**

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

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

**TypeScript SDK**

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

**CLI**

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

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [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 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 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. |
| [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. |
| [Wan 2.7 I2V](https://nodaro.ai/docs/models/video/wan-2-7-i2v) | Alibaba | Image to video | 188 | Wan 2.7 image-to-video — 2–15s at 720p/1080p, supports start+end frame. |
| [Seedance 2](https://nodaro.ai/docs/models/video/seedance-2) | Bytedance | Image to video, Text to video | from 230 | Seedance 2 — premium tier with native audio. Per-second pricing by resolution. |

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

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

**TypeScript SDK**

```ts
const { sourceImageUrl, canonicalDescription } =
await client.locations.approveMainImage(id, jobIds[2])
```

**CLI**

```bash
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）](https://nodaro.ai/docs/nodes/assets/location)ノードを含むワークフローをアプリとして公開すると、ロケーションはアプリの入力の 1 つになります。`"<bucket>/<variant>"`（たとえば `"weather/light-rain"`）を渡すと、その実行では、そのバリエーションがロケーションのメイン画像として使われます。バリエーション名は小文字で書き、スペースはハイフンにします。不明なバケットやバリエーションを指定した場合は、メイン画像が使われます。

## ほかの生成でロケーションを使う
ロケーションのアセットの URL を、リファレンス画像として[画像生成](https://nodaro.ai/docs/nodes/image/generate-image)や[**動画生成**（Generate Video）](https://nodaro.ai/docs/nodes/video/generate-video)に渡します。コードでは、URL を明示的に指定するのが最も簡単です。ワークフローでは、ロケーションのノードを画像ノードに接続するか、プロンプトでバリエーションをメンションします。たとえば、Old Library という名前のロケーションなら `@oldlibrary:1:weather/rain` と書きます。メンションがない場合、Nodaro はプロンプトからバリエーション名を探します。たとえば `dusk` のバリエーションがあれば、「at sunset」でそのバリエーションが選ばれます。[ロケーション](https://nodaro.ai/docs/guides/locations)を参照してください。

## 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 ツールリファレンス](https://nodaro.ai/docs/mcp/tools)を参照してください。

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

## Frequently asked questions

### Nodaro API でのロケーションとは何ですか？

ロケーションは、保存された場所です。承認済みのエスタブリッシングショット、文章による説明、そして夕暮れや雨の中の同じ通りのようなバリエーションの画像を持ちます。画像ノードと動画ノードがロケーションを再利用するため、どのショットでも場所が同じに見えます。

### 現在のエスタブリッシングショットを失わずに、新しいショットを試すにはどうすればよいですか？

ロケーションに関連付けずに、候補を複数生成します。候補を承認するまで、現在のメイン画像はそのまま残ります。GET /v1/locations/:id は、最近の候補を最大 5 件、previousCandidates に一覧表示します。

### ロケーションにリファレンス写真を追加するには、同意が必要ですか？

はい。リファレンス写真には人物が写っていることがあるため、初めて写真を追加するときに、ISO 形式のタイムスタンプである piiConsentAt を設定します。この値は、写真を使う権利と同意があることを記録します。

### ロケーションの 360 度ビューを作れますか？

Nodaro Cloud では、POST /v1/generate-surround-continuation が、前のビューからパノラマの次のビューを生成します。共有する半分はピクセル単位で正確に保たれるため、ビュー同士がぴったりつながります。ビュー 1 つにつき、画像生成 1 回分の費用がかかります。

### ロケーションをアニメーション化できるのは、どのモデルですか？

6 つの動画モデルです。プロバイダー ID は、kling（デフォルト、Kling 2.6）、kling-turbo、kling-3.0、wan-i2v、wan-2.7-i2v、seedance-2 です。クリップ 1 本の料金は、そのモデルで画像から動画を生成する料金です。