# ロケーション

> AI アシスタントからロケーションを作成し、エスタブリッシングショットを生成して承認します。時間帯、天候、アングルのバリエーションを追加し、雰囲気のクリップも作れます。

Source: https://nodaro.ai/ja/docs/mcp/tools/locations

**ロケーションのツール**を使うと、アシスタントは、ライブラリにある場所を作成して使えます。ロケーションとは、通り、部屋、風景など、見た目が固定された場所で、どのショットでも同じ姿を保ちます。アシスタントは、ロケーションを作成し、エスタブリッシングショットを生成して承認し、時間帯、天候、季節、アングル、ライティングのバリエーションを追加します。さらに、雰囲気のクリップをアニメーションで作り、その画像をリファレンスとしてほかの生成に渡します。アプリで同じ作業をする方法は、[ロケーション](https://nodaro.ai/docs/guides/locations)を参照してください。

ライフサイクルは、[キャラクターのツール](https://nodaro.ai/docs/mcp/tools/characters)と同じです。作成し、メイン画像を生成して承認し、その画像からバリエーションとモーションを生成します。

## `list_locations`
自分のロケーションを、新しい順に一覧表示します。各ロケーションの名前、説明、メイン画像、種類ごとのバリエーションの数、基本情報（基準となる説明、カテゴリー、スタイル、スタイルの固定）が含まれます。アーカイブしたロケーションは、指定しない限り含まれません。

**権限**：`assets:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `search` | string | ロケーション名の一部で、大文字と小文字は区別されません。最大 100 文字です。 |
| `archived` | boolean | `true` にすると、代わりにアーカイブしたロケーションを一覧表示します。 |

**戻り値**：ロケーションの一覧です。画像の URL を取得するには、`get_location` を呼び出します。

## `get_location`
1 つのロケーションのすべての情報を返します。内容は、すべての時間帯、天候、アングル、ライティング、季節のバリエーションと雰囲気のクリップ（それぞれの名前と URL 付き）、リファレンス写真、基本情報の項目です。

**権限**：`assets:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `id` | string | **必須**。`list_locations` で取得したロケーション ID です。 |

**戻り値**：ロケーションです。`update_location` で使う `updatedAt` と、そのロケーションでまだ実行中の生成も含まれます。ロケーションが存在しない場合や自分のものでない場合は、エラーが返されます。

## `create_location`
基本情報を指定してロケーションを作成します。作成した時点ではメイン画像がないので、次に `generate_location` でメイン画像を生成します。

**権限**：`assets:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `name` | string | **必須**。`Rainy Tokyo Alley` のような表示名で、最大 200 文字です。 |
| `description` | string | 最大 2,000 文字です。 |
| `category` | string | カテゴリーのタグで、最大 50 文字です。たとえば `interior`、`exterior`、`urban` です。 |
| `style` | string | スタイルのタグで、最大 50 文字です。たとえば `cinematic`、`documentary`、`noir` です。 |
| `projectId`、`workflowId`、`nodeId` | string | プロジェクト、ワークフロー、キャンバス上のノードへの任意のリンクです。通常は省略します。 |

**戻り値**：新しいロケーションの ID です。

## `update_location`
ロケーションの基本情報を変更します。書き込まれるのは、指定したフィールドだけです。バリエーションはここでは編集できません。バリエーションは生成ツールが追加します。

**権限**：`assets:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `id` | string | **必須**。ロケーション ID です。 |
| `name`、`description`、`category`、`style` | string | `create_location` と同じです。 |
| `canonicalDescription` | string | シーンの説明で、最大 4,000 文字です。自動で作られたキャプションが、このテキストに置き換わります。 |
| `styleLock` | boolean | `true` にすると、バリエーションを生成するたびにメイン画像もリファレンスとして渡され、レイアウトが一貫します。 |
| `expectedUpdatedAt` | string | `get_location` で取得した `updatedAt` です。読み取った後にロケーションが変更されていた場合、変更は拒否されます。 |

**戻り値**：確認メッセージです。`expectedUpdatedAt` が古い場合は、競合エラーが返されます。

## `approve_main_image`
完了した `generate_location` の結果をロケーションのメイン画像にし、ビジョンモデルにその画像を説明させて、ロケーションの基準となる説明を埋めます。

**権限**：`assets:write`。**クレジット**：説明を書くための、短い LLM の実行 1 回分です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `location_id` | string | **必須**。対象のロケーションです。 |
| `candidate_job_id` | string | **必須**。完了した自分の `generate_location` ジョブです。 |

**戻り値**：メイン画像の URL と説明です。説明の生成に失敗した場合でも画像は設定され、説明は空になります。その場合は `recaption_location` を実行します。

## `recaption_location`
ビジョンモデルに現在のメイン画像をもう一度説明させ、新しい基準となる説明を保存します。

**権限**：`assets:write`。**クレジット**：短い LLM の実行 1 回分です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `location_id` | string | **必須**。対象のロケーションです。 |

**戻り値**：新しい説明です。ロケーションにメイン画像がない場合は、`400 no_source_image` が返されます。

## `generate_location`
ロケーションのエスタブリッシングショット（`kind: "main"`）、またはバリエーション（`kind: "asset"`）を生成します。

**権限**：`workflows:execute`。**クレジット**：画像モデルの料金です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `name` | string | **必須**。ロケーションの名前です。 |
| `kind` | string | `main`（デフォルト）または `asset` です。 |
| `description`、`style` | string | メイン画像用の基本情報です。 |
| `category` | string | `indoor`、`outdoor`、`urban`、`nature`、`fantasy`、`sci-fi`、`historical`、`futuristic`、`other` のいずれかです。 |
| `model` | string | 画像モデルです。デフォルトは `nano-banana` です。 |
| `asset_type` | string | `asset` の場合に指定します。`timeOfDay`、`weather`、`seasons`、`angles`、`lighting`、`custom` のいずれかです。 |
| `variant` | string | `asset` の場合のバリエーションです。たとえば `dawn`、`noon`、`dusk`、`night`／`rain`、`snow`、`fog`／`spring`〜`winter`／`aerial`、`street-level`、`wide`／`golden-hour`、`overcast`、`neon` です。自分で付けた短いラベルも使えます。 |
| `attach_to_location_id` | string | 結果をこのロケーションに保存し、その承認済みのメイン画像を元画像として使います。承認済みのメイン画像がない場合、呼び出しは `main_image_required` を返します。 |
| `attach_to_column` | string | `custom` のバリエーションで `attach_to_location_id` を指定する場合は必須です。`time_of_day`、`weather`、`seasons`、`angles`、`lighting`、`atmosphere_motions`、`sheets`、`detail_closeups` のいずれかです。 |
| `attach_name` | string | 保存するバリエーションの名前です。デフォルトは `variant` の値です。 |
| `source_image_url` | string | ロケーションに保存しない場合の元画像です。 |

**戻り値**：ジョブ ID です。メイン画像の場合は、結果が気に入ったら、そのジョブを `approve_main_image` に渡します。

## `generate_location_motion`
ロケーションをアニメーション化して、雰囲気のクリップを作ります。雰囲気のクリップとは、カメラの動きに、その場所の中のさりげない動きを加えたものです。たとえば「slow dolly-in, leaves drift across frame」や「drone fly-over, neon signs flicker」のようなクリップです。

**権限**：`workflows:execute`。**クレジット**：動画モデルの料金です。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `motion_prompt` | string | **必須**。カメラの動きと、画面内の動きで、最大 2,000 文字です。 |
| `source_image_url` | string | **必須**。最初のフレームで、通常はロケーションの承認済みのメイン画像です。 |
| `name` | string | **必須**。ロケーションの名前で、プロンプトの文脈として使われます。 |
| `provider` | string | `kling`（デフォルト）、`kling-turbo`、`kling-3.0`、`wan-i2v`、`wan-2.7-i2v`、`seedance-2` のいずれかです。 |
| `attach_to_location_id` | string | クリップを、ロケーションの雰囲気のクリップに保存します。 |
| `attach_name` | string | 保存するクリップの名前です。 |
| `refine_from_video_url` | string | 画像から始める代わりに、既存のクリップを新しいプロンプトで調整します（動画から動画への生成）。 |
| `canonical_description`、`category`、`style` | string | プロンプトに加える追加の文脈です。 |

**戻り値**：ジョブ ID です。クリップの準備ができると、カードで再生されます。

## Frequently asked questions

### すべてのショットで同じ場所を保つにはどうすればよいですか？

ロケーションを作成し、エスタブリッシングショットを 1 枚メイン画像として承認して、その画像からバリエーションを生成します。その場所が映るすべての画像と動画に、メイン画像かバリエーションをリファレンスとして渡します。

### ロケーションには、どんなバリエーションがありますか？

時間帯、天候、季節、カメラアングル、ライティングに加えて、自分で名前を付けるカスタムバリエーションがあります。どれも承認済みのメイン画像から生成され、ロケーションに保存されます。

### styleLock は何をしますか？

styleLock をオンにすると、バリエーションを生成するたびにメイン画像もリファレンスとして渡されます。そのため、バリエーションの間で場所のレイアウトが一貫します。

### 雰囲気のクリップを、最初からやり直さずに調整するにはどうすればよいですか？

refine_from_video_url にそのクリップを指定し、新しいプロンプト（たとえば、霧の代わりに小雨が降る同じショット）を付けて、generate_location_motion をもう一度呼び出します。そのクリップに対して、動画から動画への生成が実行されます。