ロケーション

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

ライフサイクルは、キャラクターのツールと同じです。作成し、メイン画像を生成して承認し、その画像からバリエーションとモーションを生成します。

list_locations

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

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

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

get_location

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

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

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

create_location

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

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

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

update_location

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

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

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

approve_main_image

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

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

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

recaption_location

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

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

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

generate_location

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

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

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

generate_location_motion

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

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

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