Scene Tools

Tools for saving and reusing scene presets with prompts, reference images, and default settings.

Overview

Scene presets let you bundle a prompt prefix, reference images, and generation defaults into a reusable configuration. Use scenes to quickly generate images with consistent environments, lighting, or compositions without repeating complex prompts.

When using a scene with generate_image, the scene's scene_prompt is combined with your input, and any saved reference_images are automatically included.

Key features:

Save prompt prefixes for environments (e.g., "Neon Alley", "Studio Product Shot")
Bundle up to 20 reference images per scene
Set default aspect ratio and reference mode (style or add)
Track usage statistics per scene

create_scene

Save a new scene preset.

Parameters

Parameter	Type	Required	Description
`scene_name`	string	Yes	Unique scene name (1–100 chars)
`description`	string	No	Human-readable description (max 500 chars)
`scene_prompt`	string	No	Prompt prefix for environment/lighting/camera (max 4000 chars)
`reference_image_ids`	number[]	No	Existing image IDs to include (max 20)
`reference_image_urls`	string[]	No	Public image URLs to fetch and store (max 20)
`default_reference_mode`	string	No	`style` or `add`
`preferred_aspect_ratio`	string	No	Default aspect ratio for this scene
`tags`	string[]	No	Tags for organization (max 20, each max 50 chars)

TIP

You must provide at least one of scene_prompt, reference_image_ids, or reference_image_urls.

Example

json

{
  "tool": "create_scene",
  "params": {
    "scene_name": "Neon Alley",
    "description": "Cyberpunk alley with neon lights",
    "scene_prompt": "A dark cyberpunk alley at night, wet pavement reflecting neon signs, atmospheric fog, cinematic lighting, blade runner aesthetic",
    "preferred_aspect_ratio": "16:9",
    "default_reference_mode": "style",
    "tags": ["cyberpunk", "urban", "night"]
  }
}

Response

Returns the created scene with all details including id, createdAt, and resolved reference images.

list_scenes

Browse saved scene presets.

Parameters

Parameter	Type	Required	Description
`search`	string	No	Filter by name or description (max 100 chars)
`limit`	number	No	Max results (default 50, max 100)
`offset`	number	No	Pagination offset (default 0)
`sort_by`	string	No	`name`, `created`, `used`, or `recent`

Sort Options

Value	Description
`name`	Alphabetical by scene name
`created`	Newest first
`used`	Most used first
`recent`	Recently used first

Example

json

{
  "tool": "list_scenes",
  "params": {
    "search": "cyberpunk",
    "sort_by": "used",
    "limit": 10
  }
}

Response

json

{
  "scenes": [
    {
      "id": 5,
      "sceneName": "Neon Alley",
      "description": "Cyberpunk alley with neon lights",
      "imageCount": 3,
      "defaultReferenceMode": "style",
      "preferredAspectRatio": "16:9",
      "timesUsed": 42,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "lastUsedAt": "2024-01-20T14:22:00.000Z",
      "thumbnailUrl": "https://pub-xxx.r2.dev/.../thumb.jpg"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0,
  "hasMore": false
}

get_scene

Fetch full details of a scene preset including all reference images.

Parameters

Provide either scene_id or scene_name.

Parameter	Type	Required	Description
`scene_id`	number	No	Scene ID to retrieve
`scene_name`	string	No	Scene name to retrieve (1–100 chars)

Example

json

{
  "tool": "get_scene",
  "params": {
    "scene_name": "Neon Alley"
  }
}

Response

json

{
  "id": 5,
  "sceneName": "Neon Alley",
  "description": "Cyberpunk alley with neon lights",
  "scenePrompt": "A dark cyberpunk alley at night...",
  "referenceImages": [
    {
      "id": 101,
      "r2Key": "tenant/2024-01-15/image-xxx.png",
      "url": "https://pub-xxx.r2.dev/.../image.png",
      "thumbnailUrl": "https://pub-xxx.r2.dev/.../thumb.jpg"
    }
  ],
  "defaultReferenceMode": "style",
  "preferredAspectRatio": "16:9",
  "tags": ["cyberpunk", "urban", "night"],
  "timesUsed": 42,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-18T09:15:00.000Z",
  "lastUsedAt": "2024-01-20T14:22:00.000Z"
}

update_scene

Modify an existing scene preset.

Parameters

Provide scene_id or scene_name, plus at least one field to change.

Parameter	Type	Required	Description
`scene_id`	number	No	Scene ID to update
`scene_name`	string	No	Scene name to update
`new_scene_name`	string	No	Rename the scene (1–100 chars)
`description`	string \| null	No	New description (null clears)
`scene_prompt`	string \| null	No	New prompt prefix (null clears)
`reference_image_ids`	number[]	No	Replace reference images (max 20)
`reference_image_urls`	string[]	No	Fetch/store and add to references (max 20)
`default_reference_mode`	string \| null	No	`style`, `add`, or null to clear
`preferred_aspect_ratio`	string \| null	No	New aspect ratio (null clears)
`tags`	string[] \| null	No	Replace tags (null clears)

WARNING

The scene must maintain at least a prompt or reference images. You cannot clear both.

Example

json

{
  "tool": "update_scene",
  "params": {
    "scene_name": "Neon Alley",
    "new_scene_name": "Cyberpunk Alley",
    "tags": ["cyberpunk", "urban", "night", "rain"]
  }
}

delete_scene

Delete a scene preset. Reference images remain in your library.

Parameters

Provide either scene_id or scene_name.

Parameter	Type	Required	Description
`scene_id`	number	No	Scene ID to delete
`scene_name`	string	No	Scene name to delete (1–100 chars)

Example

json

{
  "tool": "delete_scene",
  "params": {
    "scene_id": 5
  }
}

Response

json

{
  "deleted": true,
  "sceneId": 5,
  "sceneName": "Neon Alley",
  "imageCount": 3
}

Using Scenes in Generation

Once you've created a scene, reference it in generate_image:

json

{
  "tool": "generate_image",
  "params": {
    "prompt": "A lone figure walking with an umbrella",
    "scene_name": "Neon Alley"
  }
}

Or use multiple scenes:

json

{
  "tool": "generate_image",
  "params": {
    "prompt": "A hero standing confidently",
    "scene_ids": [5, 12]
  }
}

The scene's scene_prompt is prepended to your prompt, and reference images are included automatically with the scene's default_reference_mode.

Best Practices

1. Use Descriptive Names

✅ "Studio Product Shot - White Background"
✅ "Sunset Beach - Golden Hour"
✅ "Office Interior - Modern Minimalist"

❌ "Scene 1"
❌ "Test"

2. Leverage Reference Images

Add 2-5 reference images that exemplify the scene's visual style. These help maintain consistency across generations.

3. Set Appropriate Defaults

Use style reference mode for aesthetic/color matching
Use add reference mode when elements should appear in the scene
Set preferred_aspect_ratio based on typical use case

4. Organize with Tags

Use consistent tags across scenes to enable easy filtering:

Environment: indoor, outdoor, urban, nature
Mood: dramatic, peaceful, energetic
Style: photorealistic, anime, watercolor

Scene Tools ​

Overview ​

create_scene ​

Parameters ​

Example ​

Response ​

list_scenes ​

Parameters ​

Sort Options ​

Example ​

Response ​

get_scene ​

Parameters ​

Example ​

Response ​

update_scene ​

Parameters ​

Example ​

delete_scene ​

Parameters ​

Example ​

Response ​

Using Scenes in Generation ​

Best Practices ​

1. Use Descriptive Names ​

2. Leverage Reference Images ​

3. Set Appropriate Defaults ​

4. Organize with Tags ​

Scene Tools

Overview

create_scene

Parameters

Example

Response

list_scenes

Parameters

Sort Options

Example

Response

get_scene

Parameters

Example

Response

update_scene

Parameters

Example

delete_scene

Parameters

Example

Response

Using Scenes in Generation

Best Practices

1. Use Descriptive Names

2. Leverage Reference Images

3. Set Appropriate Defaults

4. Organize with Tags