---
title: "Write one scene's atmospheric FX cues from its lines."
method: POST
path: "/artifacts/{artifactId}/theater-fx-cues"
tags: ["Artifacts"]
---

# Write one scene's atmospheric FX cues from its lines.

`POST /artifacts/{artifactId}/theater-fx-cues`

## Request

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

Writes a bounded set of atmospheric, non-text FX cues (light bursts, washes, weather, darkness) for one scene from its own lines and mood, replacing the cues it had. Synchronous. While the project's gate is closed it is refused with 409 `project_precondition_failed` before anything is written. Requires `Idempotency-Key`. Scope: `artifact:publish`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TableReadFxCuesRequest
  - `sceneIndex` integer, required

## Response `200`

The scene's new FX cues.

- TableReadFxCuesResponse
  - `artifactId` string, required
  - `sceneIndex` integer, required
  - `fxCues` TableReadFxCue[], 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)