---
title: "Studio Scene"
method: POST
path: "/v1/apps/{listing_id}/studio/scene"
tags: ["asc-studio"]
---

# Studio Scene

`POST /v1/apps/{listing_id}/studio/scene`

## Request

- Base URL: `https://api.theagentc.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.theagentc.io/v1/apps/{listing_id}/studio/scene`
- Auth: HTTP bearer

AI themed-background scene for the Studio's Backdrop > AI scene tab
(SPEC §3.4.4). Generates ONE low-res preview-quality image (capped at
studio_gen.SCENE_MAX_W, matching creative_preview's preview-panorama
cap), blends the active theme's hexes into the prompt, and caches by
content hash under studio-scenes/{workspace_id}/ — a repeat call with the
identical (prompt, w, h, theme) never re-pays for generation.

Not credit-gated (composing is free; export is where credits get
charged, see studio_charge_export) — bounded only by a dedicated fal
sub-limiter (studio_gen.FAL_STUDIO_RATE_LIMIT_PER_MIN/_DAY) shared with
the sprite endpoint below.

## Path parameters

- `listing_id` string, uuid, required

## Request body

- StudioSceneRequest: POST /v1/apps/{listing_id}/studio/scene — SPEC §3.4.4's 'Paint scene' hook (window.ASCStudio.registerSceneGenerator). Generates ONE low-res preview-quality background at up to studio_gen.SCENE_MAX_W, cached by content hash under studio-scenes/{workspace_id}/. Not credit-gated — composing is free; only export charges credits (see StudioChargeExportRequest).
  - `prompt` string, required
  - `width` integer, required
  - `height` integer, required
  - `theme` StudioThemeHex: A subset of the Studio's Theme palette (src/lib/studio/types.ts) — just the hexes worth blending into an AI scene prompt so a generated background harmonizes with the active palette (SPEC §3.4.4).
    - `bg` string, nullable
    - `accent` string, nullable
    - `accent2` string, nullable

## Response `200`

Successful Response

- StudioSceneResponse
  - `url` string, required
  - `cached` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/theagentc/apis/the-agent-c-api.md) · [All operations](https://skmtc.dev/theagentc/apis/the-agent-c-api/llms.txt) · [OpenAPI document](https://skmtc.dev/theagentc/apis/the-agent-c-api/revisions/1c9868b44584?raw)