Scenes API

Endpoints for managing reusable scene presets with prompts, reference images, and generation defaults.

Overview

The Scenes API enables creating and managing reusable scene configurations that bundle prompt prefixes, reference images, and default settings. Use scenes to quickly generate images with consistent environments, lighting, or compositions.

List Scenes

Retrieve all saved scene presets with pagination and search.

GET /api/scenes

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Items per page (max: 100)
offset	integer	0	Pagination offset
search	string	-	Search name/description
sort_by	string	name	name, created, used, recent

Request

curl -X GET "https://gobananasai.com/api/scenes?sort_by=used&limit=20" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": [
    {
      "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"
    },
    {
      "id": 8,
      "sceneName": "Studio Product Shot",
      "description": "Clean white background for products",
      "imageCount": 2,
      "defaultReferenceMode": "add",
      "preferredAspectRatio": "square",
      "timesUsed": 28,
      "createdAt": "2024-01-10T08:15:00.000Z",
      "lastUsedAt": "2024-01-19T16:45:00.000Z",
      "thumbnailUrl": "https://pub-xxx.r2.dev/.../thumb.jpg"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Get Scene

Retrieve full details for a specific scene preset.

GET /api/scenes/:identifier

The identifier can be either a numeric ID or the scene name (URL-encoded).

Request

curl -X GET "https://gobananasai.com/api/scenes/5" \
  -H "X-API-Key: sk_live_xxx"

Or by name:

curl -X GET "https://gobananasai.com/api/scenes/Neon%20Alley" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": {
    "id": 5,
    "sceneName": "Neon Alley",
    "description": "Cyberpunk alley with neon lights",
    "scenePrompt": "A dark cyberpunk alley at night, wet pavement reflecting neon signs, atmospheric fog, cinematic lighting, blade runner aesthetic",
    "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"
      },
      {
        "id": 105,
        "r2Key": "tenant/2024-01-15/image-yyy.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"
  }
}

Create Scene

Save a new scene preset.

POST /api/scenes

Request Body

Field	Type	Required	Description
scene_name	string	Yes	Unique name (1-100 chars)
description	string	No	Human-readable description (max: 500)
scene_prompt	string	No	Prompt prefix (max: 4000)
reference_image_ids	integer[]	No	Up to 20 existing image IDs
reference_image_urls	string[]	No	Up to 20 public URLs to fetch
default_reference_mode	string	No	style or add
preferred_aspect_ratio	string	No	Default aspect ratio
tags	string[]	No	Up to 20 tags (each max 50 chars)

Note

At least one of scene_prompt, reference_image_ids, or reference_image_urls must be provided.

Request

curl -X POST "https://gobananasai.com/api/scenes" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scene_name": "Sunset Beach",
    "description": "Golden hour beach scene for lifestyle shots",
    "scene_prompt": "A beautiful sandy beach at sunset, golden hour lighting, warm orange and pink sky, gentle waves, palm trees in silhouette, tropical paradise atmosphere",
    "preferred_aspect_ratio": "16:9",
    "default_reference_mode": "style",
    "tags": ["beach", "sunset", "tropical", "lifestyle"]
  }'

Response

{
  "data": {
    "id": 12,
    "sceneName": "Sunset Beach",
    "description": "Golden hour beach scene for lifestyle shots",
    "scenePrompt": "A beautiful sandy beach at sunset, golden hour lighting, warm orange and pink sky, gentle waves, palm trees in silhouette, tropical paradise atmosphere",
    "referenceImages": [],
    "defaultReferenceMode": "style",
    "preferredAspectRatio": "16:9",
    "tags": ["beach", "sunset", "tropical", "lifestyle"],
    "timesUsed": 0,
    "createdAt": "2024-01-20T15:00:00.000Z",
    "updatedAt": "2024-01-20T15:00:00.000Z",
    "lastUsedAt": null
  }
}

Update Scene

Modify an existing scene preset.

PATCH /api/scenes/:identifier

The identifier can be either a numeric ID or the scene name.

Request Body

All fields are optional. Only provided fields are updated. Pass null to clear optional fields.

Field	Type	Description
new_scene_name	string	Rename the scene
description	string | null	New description (null clears)
scene_prompt	string | null	New prompt (null clears)
reference_image_ids	integer[]	Replace reference images
reference_image_urls	string[]	Fetch and add new references
default_reference_mode	string | null	style, add, or null
preferred_aspect_ratio	string | null	New aspect ratio (null clears)
tags	string[] | null	Replace tags (null clears)

WARNING

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

Request

curl -X PATCH "https://gobananasai.com/api/scenes/12" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "new_scene_name": "Tropical Sunset Beach",
    "reference_image_ids": [150, 152, 155],
    "tags": ["beach", "sunset", "tropical", "lifestyle", "golden-hour"]
  }'

Response

{
  "data": {
    "id": 12,
    "sceneName": "Tropical Sunset Beach",
    "description": "Golden hour beach scene for lifestyle shots",
    "scenePrompt": "A beautiful sandy beach at sunset...",
    "referenceImages": [
      { "id": 150, "url": "https://pub-xxx.r2.dev/...", "thumbnailUrl": "..." },
      { "id": 152, "url": "https://pub-xxx.r2.dev/...", "thumbnailUrl": "..." },
      { "id": 155, "url": "https://pub-xxx.r2.dev/...", "thumbnailUrl": "..." }
    ],
    "defaultReferenceMode": "style",
    "preferredAspectRatio": "16:9",
    "tags": ["beach", "sunset", "tropical", "lifestyle", "golden-hour"],
    "timesUsed": 0,
    "createdAt": "2024-01-20T15:00:00.000Z",
    "updatedAt": "2024-01-20T15:30:00.000Z",
    "lastUsedAt": null
  }
}

Delete Scene

Remove a scene preset from the library.

DELETE /api/scenes/:identifier

Request

curl -X DELETE "https://gobananasai.com/api/scenes/12" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": {
    "deleted": true,
    "sceneId": 12,
    "sceneName": "Tropical Sunset Beach",
    "imageCount": 3
  }
}

Note

Deleting a scene does not delete the reference images. They remain in your image library.

Error Responses

400 Invalid Payload

{
  "error": "Invalid scene preset payload",
  "details": ["Provide at least one of scene_prompt, reference_image_ids, or reference_image_urls"]
}

400 Duplicate Name

{
  "error": "Scene preset \"Neon Alley\" already exists. Use a different name or update the existing scene."
}

400 Invalid Reference Images

{
  "error": "Reference image 999 not found or does not belong to this tenant"
}

404 Scene Not Found

{
  "error": "Scene preset with ID 999 not found for this tenant"
}

400 Cannot Clear Both Prompt and References

{
  "error": "Scene preset must include at least a prompt or reference images"
}

Using Scenes with MCP

Scenes created via the REST API are available in MCP tools:

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

Or by ID:

{
  "tool": "generate_image",
  "params": {
    "prompt": "A sports car",
    "scene_id": 5
  }
}

Next Steps

• Search Presets API →
• Characters API →
• Style Presets API →