ロケーション
TypeScript からロケーションを作成し、エスタブリッシングショットを生成して承認し、時間帯、天候、季節、アングル、モーションのバリエーションを追加します。
client.locations は、ロケーションスタジオが行うことすべてをスクリプトから操作します。ロケーションの作成と編集、エスタブリッシングショットの候補の生成、その 1 枚をメイン画像として承認、時間帯、天候、季節、アングル、ライティングのバリエーションと雰囲気のクリップの追加です。ロケーションは、メイン画像、バリエーションのコレクション、リファレンス写真、そして説明文を保持するため、以降のどのショットにも同じ場所を映せます。これらのメソッドは、ロケーションの REST API を呼び出します。エディターでの見え方については、ロケーションを参照してください。
メソッド
| メソッド | 内容 |
|---|---|
list(params?) | ロケーションを一覧表示します |
listArchived(params?) | アーカイブ済みのロケーションを一覧表示します |
get(id) | 1 つのロケーションを、進行中のジョブとともに読み取ります |
create(input) | ロケーションを作成します |
update(id, input) | ロケーションを変更します |
delete(id) と restore(id) | ロケーションをアーカイブするか、元に戻します |
generate(input) | エスタブリッシングショットの候補を生成します |
generateAsset(input) | 時間帯、天候、季節、アングル、ライティングのバリエーションを生成します |
generateSurroundContinuation(input) | 360 度のリングの次のビューを生成します |
generateMotion(input) | メイン画像をアニメーション化し、雰囲気のクリップにします |
removeAsset(id, data) | バリエーションのコレクションから 1 件を削除します |
approveMainImage(id, candidateJobId) | 候補をメイン画像にします |
recaption(id) | ロケーションの説明文を書き直します |
client.locations
list(params?)
ロケーションを一覧表示します。デフォルトでは、有効なロケーションだけが返されます。ページングは省略できます。limit を指定しない場合はリスト全体が返り、カーソルは付きません。limit(最大 500)を指定すると、1 ページ分の結果と nextCursor が返ります。
list(params?: { archived?: boolean; q?: string; limit?: number; cursor?: string }): Promise<{
locations: Location[]
nextCursor?: string | null
}>プロパティ
型
const { locations } = await client.locations.list()
const { locations: cafes } = await client.locations.list({ q: "café" })
const page = await client.locations.list({ limit: 100 })
const next = await client.locations.list({ limit: 100, cursor: page.nextCursor ?? undefined })nextCursor が null になるまで、ページの取得を続けてください。q の検索ルールはキャラクターのページにあります。最初の 5 語だけが使われ、%、_、* はワイルドカードになりません。各 cursor と一緒に同じ q を送ってください。
listArchived(params?)
アーカイブ済みのロケーションを一覧表示します。list({ archived: true }) のショートカットです。
listArchived(params?: { limit?: number; cursor?: string }): Promise<{ locations: Location[]; nextCursor?: string | null }>プロパティ
型
const { locations: archived } = await client.locations.listArchived()get(id)
1 つのロケーションを、pendingJobs(まだ生成中のバリエーション)と previousCandidates(それまでのメイン画像の候補が、新しい順に最大 5 件)とともに読み取ります。それらの候補は、approveMainImage() で昇格させます。
get(id: string): Promise<LocationDetail>プロパティ
型
const location = await client.locations.get(locationId)
console.log(location.sourceImageUrl, location.weather, location.atmosphereMotions)アーカイブ済みのロケーションも、ID を指定すれば読み取れるので、それを参照するワークフローのノードは、そのまま読み込めます。Location は、メイン画像を sourceImageUrl に持ち、6 つのコレクション(timeOfDay、weather、seasons、angles、lighting、atmosphereMotions。それぞれ { name, url } のリストです)、boards、referencePhotos、canonicalDescription、styleLock、updatedAt を持ちます。
create(input)
ロケーションを作成します。name と nodeId は必須です。キャンバスのノードを持たないスクリプトは、nodeId に "mcp-managed" を渡せます。
create(input: CreateLocationInput): Promise<{ id: string }>プロパティ
型
const { id: locationId } = await client.locations.create({
nodeId: "mcp-managed",
name: "Rainy Tokyo Alley",
description: "Neon-soaked alley with vending machines",
category: "urban",
style: "realistic",
})update(id, input)
ロケーションを変更します。書き込まれるのは、送信したフィールドだけです。バリエーションのコレクションは、この呼び出しの対象ではありません。作業中も生成ジョブがそこに追加していくためです。コレクションには generateAsset() と removeAsset() を使ってください。
update(id: string, input: UpdateLocationInput): Promise<{ id: string; updatedAt: string }>プロパティ
型
await client.locations.update(locationId, {
canonicalDescription: "A narrow, rain-soaked alley lit by neon signs",
styleLock: false,
piiConsentAt: new Date().toISOString(),
expectedUpdatedAt: location.updatedAt,
})409 concurrent_modification は、その code を持つ、通常の NodaroError として届きます。ロケーションをもう一度読み取り、変更をマージしてから再試行してください。
delete(id) と restore(id)
delete() はロケーションをアーカイブし、restore() は元に戻します。完全な削除は、Nodaro のアプリ上でしか行えません。元に戻した名前が、大文字と小文字を区別せずに有効なロケーションの名前と一致する場合、サーバーは (restored) を追加し、実際に使った名前を返します。
delete(id: string): Promise<{ success: true; archived: true }>
restore(id: string): Promise<{ id: string; name: string }>プロパティ
型
await client.locations.delete(locationId)
const { name } = await client.locations.restore(locationId)generate(input)
エスタブリッシングショットの候補を生成します(POST /v1/generate-location)。count が 1 より大きい場合、実行が始まる前に、すべてのジョブの分が確保されます。そのため、途中で失敗すると、そのバッチ全体が取り消されます。
generate(input: GenerateLocationInput): Promise<{ jobIds: string[]; jobId?: string }>プロパティ
型
// One candidate, written to the location when it completes
const { jobIds: [jobId] } = await client.locations.generate({
name: "Rainy Tokyo Alley",
description: "Neon-soaked alley with vending machines",
attachToLocationId: locationId,
})
// Four candidates to choose from
const { jobIds } = await client.locations.generate({ name: "Rainy Tokyo Alley", count: 4 })attachToLocationId を指定し、count が 1 の場合、ジョブが完了すると、その結果がメイン画像になります。それ以外の場合は、approveMainImage() で候補を選んでください。quality と resolution の料金は、画像生成と同じです。一覧にある値のうち、モデルが対応していないものも拒否されません。Nodaro は代わりにモデルが対応している値を使い、モデルにその設定がない場合は設定を外します。クレジットは実際に使われた値に従い、その値はジョブの input_data で確認できます。
generateAsset(input)
ロケーションのバリエーションを 1 つ生成します(POST /v1/generate-location-asset)。attachToLocationId、attachToColumn、attachName を指定すると、ジョブが完了したときに、その結果が該当するコレクションに追加されます。
generateAsset(input: GenerateLocationAssetInput): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.locations.generateAsset({
name: "Rainy Tokyo Alley",
assetType: "weather",
variant: "storm",
attachToLocationId: locationId,
attachToColumn: "weather",
attachName: "storm",
})generateSurroundContinuation(input)
前のビューの続きとして、360 度のリングの次のビューを生成します(POST /v1/generate-surround-continuation)。サーバーは前のビューの半分をそのまま保ち、残りの半分を描き、色を合わせます。そのため、隣接するビューは境目なくつながります。このメソッドは Nodaro Cloud で動作します。ほかのエディションでは、処理を始める前に 403 edition_required を返し、SDK はこれを ForbiddenError としてスローします。
generateSurroundContinuation(input: GenerateSurroundContinuationInput): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.locations.generateSurroundContinuation({
referenceImageUrl: previousRingView,
direction: "right",
degrees: 45,
provider: "nano-banana-pro",
aspectRatio: "16:9",
attachToLocationId: locationId,
attachToColumn: "angles",
attachName: "Surround 45°",
})generateMotion(input)
ロケーションの画像をアニメーション化し、雰囲気のクリップにします(POST /v1/generate-location-motion)。動画生成の画像から動画へのモードを使います。ロケーションが持つモーションのコレクションは 1 つだけなので、クリップは必ず atmosphereMotions に入り、attachToColumn はありません。
generateMotion(input: GenerateLocationMotionInput): Promise<{ jobId: string }>プロパティ
型
const { jobId } = await client.locations.generateMotion({
name: "Rainy Tokyo Alley",
motionPrompt: "Slow dolly-in, neon signs flicker, light rain falling",
sourceImageUrl: location.sourceImageUrl!,
provider: "kling",
attachToLocationId: locationId,
attachName: "neon dolly-in",
})removeAsset(id, data)
バリエーションのコレクションから 1 件を削除します(POST /v1/locations/:id/remove-asset)。その url を持つエントリーは、まとめて 1 回の操作ですべて削除されます。たとえば、360 度のビューを再生成する前などに使います。
removeAsset(id: string, data: { column: LocationAttachColumn; url: string }): Promise<{ removed: true }>プロパティ
型
await client.locations.removeAsset(locationId, { column: "angles", url: oldViewUrl })URL がそのコレクションにない場合、またはロケーションが自分のものではない場合は、NotFoundError をスローします。
approveMainImage(id, candidateJobId)
generate() で完了した候補を、ロケーションのメイン画像にします。続いてビジョンモデルがロケーションの説明を書き、このメソッドはその両方を返します。
approveMainImage(id: string, candidateJobId: string): Promise<{ sourceImageUrl: string; canonicalDescription: string | null }>プロパティ
型
const { sourceImageUrl, canonicalDescription } = await client.locations.approveMainImage(locationId, jobIds[0])説明を書けなかった場合、canonicalDescription は null になります。その場合もメイン画像は設定されるので、recaption() を呼び出してもう一度試してください。
recaption(id)
現在のメイン画像から、ロケーションの説明を書き直します。
recaption(id: string): Promise<{ canonicalDescription: string }>プロパティ
型
const { canonicalDescription } = await client.locations.recaption(locationId)ロケーションにメイン画像がない場合は 400 no_source_image で失敗し、ビジョンモデルが失敗した場合は 502 で失敗します。
よくある質問
Nodaro の SDK でロケーションを作成するには、どうすればよいですか?
nodeId と name を指定して client.locations.create を呼び出し、client.locations.generate でエスタブリッシングショットを生成し、client.locations.approveMainImage で 1 枚を承認します。
ロケーションには、どのようなバリエーションを生成できますか?
generateAsset で、時間帯、天候、季節、アングル、ライティングのバリエーションに加えて、カスタムバリエーションを生成できます。generateMotion では、雰囲気のクリップを生成できます。Nodaro Cloud では、generateSurroundContinuation で 360 度のビューを追加できます。
ほかの人が変更したロケーションを、上書きしないようにするには、どうすればよいですか?
読み取った updatedAt の値を expectedUpdatedAt として client.locations.update に渡します。その間にロケーションが変更されていた場合、呼び出しは 409 concurrent_modification で失敗します。もう一度読み取ってマージし、再試行してください。
SDK で、ロケーションを完全に削除できますか?
できません。delete はロケーションをアーカイブし、restore は元に戻します。完全な削除は、Nodaro のアプリ上でしかできません。
関連ページ
ロケーション
ロケーションアセット
ロケーション
キャラクター
オブジェクトとクリーチャー
最終更新