Nodaro DocsLocations
Create locations from an AI assistant, generate and approve their establishing shots, add time of day, weather and angle variants, and animate atmosphere clips.
The location tools let an assistant build and use the places in your library: a street, a room or a landscape with a locked look that stays the same in every shot. The assistant creates a location, generates and approves its establishing shot, adds variants for time of day, weather, seasons, angles and lighting, animates atmosphere clips, and passes the pictures as references to other generations. Read Locations for the same work in the app.
The lifecycle matches the character tools: create, generate a main image, approve it, then generate variants and motion from it.
list_locations
Lists your locations, newest first, with their name, description, main image, the number of variants of each kind, and their identity: canonical description, category, style and style lock. Archived locations are left out unless you ask for them.
Permission: assets:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
search | string | Part of the location's name, not case-sensitive, up to 100 characters. |
archived | boolean | true lists the archived locations instead. |
Returns: the locations. Call get_location for the picture URLs.
get_location
Returns one location in full: every time of day, weather, angle, lighting, season and atmosphere clip with its name and URL, the reference photos, and the identity fields.
Permission: assets:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
id | string | Required. The location id from list_locations. |
Returns: the location, including updatedAt for update_location, and the generations still running for it. An error when the location does not exist or is not yours.
create_location
Creates a location with its identity. It has no main image yet: generate one with generate_location next.
Permission: assets:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
name | string | Required. The display name, such as Rainy Tokyo Alley, up to 200 characters. |
description | string | Up to 2,000 characters. |
category | string | A category tag, such as interior, exterior or urban, up to 50 characters. |
style | string | A style tag, such as cinematic, documentary or noir, up to 50 characters. |
projectId, workflowId, nodeId | string | Optional links to a project, a workflow or a canvas node. Usually left out. |
Returns: the new location's id.
update_location
Changes a location's identity. Only the fields you pass are written. The variants are not editable here; the generation tools add them.
Permission: assets:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
id | string | Required. The location id. |
name, description, category, style | string | As on create_location. |
canonicalDescription | string | The scene description, up to 4,000 characters. Your text replaces the automatic caption. |
styleLock | boolean | When true, every variant generation also receives the main image as a reference, for a consistent layout. |
expectedUpdatedAt | string | The updatedAt from get_location. The change is refused when the location changed since you read it. |
Returns: a confirmation, or a conflict error when expectedUpdatedAt is out of date.
approve_main_image
Makes a finished generate_location result the location's main image, and has a vision model describe it to fill the location's canonical description.
Permission: assets:write. Credits: one short LLM run for the description.
| Parameter | Type | Notes |
|---|---|---|
location_id | string | Required. The location. |
candidate_job_id | string | Required. A completed generate_location job of yours. |
Returns: the main image URL and the description. When the description fails, the image is still set and the description is empty; run recaption_location.
recaption_location
Has the vision model describe the current main image again, and saves the new canonical description.
Permission: assets:write. Credits: one short LLM run.
| Parameter | Type | Notes |
|---|---|---|
location_id | string | Required. The location. |
Returns: the new description. 400 no_source_image when the location has no main image.
generate_location
Generates a location's establishing shot (kind: "main") or a variant (kind: "asset").
Permission: workflows:execute. Credits: the price of the image model.
| Parameter | Type | Notes |
|---|---|---|
name | string | Required. The location's name. |
kind | string | main (default) or asset. |
description, style | string | The identity, for a main image. |
category | string | indoor, outdoor, urban, nature, fantasy, sci-fi, historical, futuristic or other. |
model | string | The image model. Default nano-banana. |
asset_type | string | For asset: timeOfDay, weather, seasons, angles, lighting or custom. |
variant | string | For asset: for example dawn, noon, dusk or night; rain, snow or fog; spring to winter; aerial, street-level or wide; golden-hour, overcast or neon; or a short label of your own. |
attach_to_location_id | string | Saves the result on this location and uses its approved main image as the source. Without one, the call returns main_image_required. |
attach_to_column | string | Required with attach_to_location_id for a custom variant: time_of_day, weather, seasons, angles, lighting, atmosphere_motions, sheets or detail_closeups. |
attach_name | string | The name of the saved variant. Default: the variant. |
source_image_url | string | A source picture, when you do not attach to a location. |
Returns: a job id. For a main image, pass the job to approve_main_image when you like the result.
generate_location_motion
Animates a location into an atmosphere clip: a camera move with subtle motion in the world, such as "slow dolly-in, leaves drift across frame" or "drone fly-over, neon signs flicker".
Permission: workflows:execute. Credits: the price of the video model.
| Parameter | Type | Notes |
|---|---|---|
motion_prompt | string | Required. The camera move and the motion, up to 2,000 characters. |
source_image_url | string | Required. The first frame, usually the location's approved main image. |
name | string | Required. The location's name, used as context in the prompt. |
provider | string | kling (default), kling-turbo, kling-3.0, wan-i2v, wan-2.7-i2v or seedance-2. |
attach_to_location_id | string | Saves the clip in the location's atmosphere clips. |
attach_name | string | The name of the saved clip. |
refine_from_video_url | string | Refines an existing clip with a new prompt, as video to video, instead of starting from the image. |
canonical_description, category, style | string | Extra context for the prompt. |
Returns: a job id. The card plays the clip when it is ready.
Frequently asked questions
Related
Locations
Location Asset
Characters
Objects and creatures
Last updated on
Characters
Create characters from an AI assistant, generate and approve their portraits, add expressions, poses, angles and motion clips, and reuse them as references.
Objects and creatures
List and read your saved objects and creatures, generate images and variants, approve main images, and animate turntable and idle clips from an AI assistant.