---
title: "Change one scene's theater."
method: POST
path: "/artifacts/{artifactId}/theater-scene"
tags: ["Artifacts"]
---

# Change one scene's theater.

`POST /artifacts/{artifactId}/theater-scene`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/theater-scene`
- Auth: HTTP bearer

Sets one scene's text reveal, look (`visualStyle`), transition, backdrop prompt and media, and atmospheric FX cues (a list replaces the scene's cues; `[]` clears them). Fields left out are kept. The same save as the Table Read page's per-scene controls and Slug's update_scene_theater. Free: renders nothing. Requires `Idempotency-Key`. Scope: `artifact:publish`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TableReadTheaterSceneRequest: One scene's theater. Fields left out are kept.
  - `sceneIndex` integer, required
  - `textRevealStyle` 'fade' | 'drift' | 'spotlight'
  - `summary` string: A short note on the scene's theater treatment.
  - `backdropPrompt` string: The backdrop prompt: the setting only, no characters, no on-screen text.
  - `mediaPreference` 'image' | 'video'
  - `transitionType` 'crossfade' | 'spotlight' | 'curtain' | 'drift' | 'hard-cut'
  - `transitionDurationMs` number
  - `transitionPrompt` string: How the scene arrives from the one before it.
  - `visualStyle` TableReadVisualStyle: A theater look: gradient, colors, filter, animation, lighting, texture and intensity.
    - `bgGradient` string
    - `ambientColor` string
    - `textColor` string
    - `accentColor` string
    - `shadowColor` string
    - `filter` string
    - `animation` string
    - `lighting` string
    - `texture` string
    - `intensity` number
    - `textRevealStyle` 'fade' | 'drift' | 'spotlight': How on-screen text appears.
  - `fxCues` TableReadFxCue[]: Replaces the scene's FX cues; [] clears them.
    - `id` string
    - `entryIndex` integer, required: The line the effect fires on.
    - `kind` 'light-flash' | 'hot-white' | 'strobe' | 'pulse' | 'color-wash' | 'texture-shift' | 'fabric-tear' | 'blood-splatter' | 'lightning' | 'weather' | 'darkness' | 'shroud' | 'ember' | 'vignette-pulse', required
    - `origin` 'tl' | 'tr' | 'bl' | 'br' | 'top' | 'bottom' | 'left' | 'right' | 'edges' | 'full', required: The corner or edge it comes from, every edge, or the full frame.
    - `color` string: Hex tint, e.g. "#ef4444".
    - `intensity` number
    - `durationMs` number: How long it plays (150–8000 ms).
    - `delayMs` number: Delay after the line before it starts (0–6000 ms).
    - `easing` 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'

## Response `200`

The scene's theater as it now stands.

- TableReadTheaterSceneResponse
  - `artifactId` string, required
  - `scene` object, required
    - `sceneIndex` integer, required
    - `heading` string, required
    - `textRevealStyle` string, nullable, required
    - `backdropPrompt` string, nullable, required
    - `transitionType` string, nullable, required
    - `transitionDurationMs` number, nullable, required
    - `fxCues` TableReadFxCue[], nullable, required
      - `id` string
      - `entryIndex` integer, required: The line the effect fires on.
      - `kind` 'light-flash' | 'hot-white' | 'strobe' | 'pulse' | 'color-wash' | 'texture-shift' | 'fabric-tear' | 'blood-splatter' | 'lightning' | 'weather' | 'darkness' | 'shroud' | 'ember' | 'vignette-pulse', required
      - `origin` 'tl' | 'tr' | 'bl' | 'br' | 'top' | 'bottom' | 'left' | 'right' | 'edges' | 'full', required: The corner or edge it comes from, every edge, or the full frame.
      - `color` string: Hex tint, e.g. "#ef4444".
      - `intensity` number
      - `durationMs` number: How long it plays (150–8000 ms).
      - `delayMs` number: Delay after the line before it starts (0–6000 ms).
      - `easing` 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear'

## Other responses

- `400`: Request payload failed validation. The error message names the offending field.
- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The story artifact does not exist or is owned by another account.
- `409`: The artifact is not in a state where this operation is valid yet (e.g. requesting an MP4 render before the share link exists).
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)