Nodaro ドキュメントロケーション
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; limit?: number; cursor?: string }): Promise<{
locations: Location[]
nextCursor?: string | null
}>Prop
Type
const { locations } = await client.locations.list()
const page = await client.locations.list({ limit: 100 })
const next = await client.locations.list({ limit: 100, cursor: page.nextCursor ?? undefined })nextCursor が null になるまで、ページの取得を続けてください。
listArchived(params?)
アーカイブ済みのロケーションを一覧表示します。list({ archived: true }) のショートカットです。
listArchived(params?: { limit?: number; cursor?: string }): Promise<{ locations: Location[]; nextCursor?: string | null }>Prop
Type
const { locations: archived } = await client.locations.listArchived()get(id)
1 つのロケーションを、pendingJobs（まだ生成中のバリエーション）と previousCandidates（それまでのメイン画像の候補が、新しい順に最大 5 件）とともに読み取ります。それらの候補は、approveMainImage() で昇格させます。
get(id: string): Promise<LocationDetail>Prop
Type
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 }>Prop
Type
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 }>Prop
Type
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 }>Prop
Type
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 }>Prop
Type
// 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 の料金は、画像生成（Generate Image）と同じです。モデルが対応していない値は無視されます。
generateAsset(input)
ロケーションのバリエーションを 1 つ生成します（POST /v1/generate-location-asset）。attachToLocationId、attachToColumn、attachName を指定すると、ジョブが完了したときに、その結果が該当するコレクションに追加されます。
generateAsset(input: GenerateLocationAssetInput): Promise<{ jobId: string }>Prop
Type
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 }>Prop
Type
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）。動画生成（Generate Video）の画像から動画へのモードを使います。ロケーションが持つモーションのコレクションは 1 つだけなので、クリップは必ず atmosphereMotions に入り、attachToColumn はありません。
generateMotion(input: GenerateLocationMotionInput): Promise<{ jobId: string }>Prop
Type
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 }>Prop
Type
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 }>Prop
Type
const { sourceImageUrl, canonicalDescription } = await client.locations.approveMainImage(locationId, jobIds[0])説明を書けなかった場合、canonicalDescription は null になります。その場合もメイン画像は設定されるので、recaption() を呼び出してもう一度試してください。
recaption(id)
現在のメイン画像から、ロケーションの説明を書き直します。
recaption(id: string): Promise<{ canonicalDescription: string }>Prop
Type
const { canonicalDescription } = await client.locations.recaption(locationId)ロケーションにメイン画像がない場合は 400 no_source_image で失敗し、ビジョンモデルが失敗した場合は 502 で失敗します。
よくある質問
関連ページ
ロケーション
ロケーションアセット
ロケーション
キャラクター
オブジェクトとクリーチャー
最終更新