---
title: "Replace the trailer's black interludes."
method: POST
path: "/trailers/{jobId}/interludes"
tags: ["Trailer"]
---

# Replace the trailer's black interludes.

`POST /trailers/{jobId}/interludes`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/trailers/{jobId}/interludes`
- Auth: HTTP bearer

Replaces the trailer's black interludes with the list given (`[]` removes them all; the beats read returns the current ones as `interludes`). A black interlude is a beat of pure black between two beats of the trailer (0.5 to 2 seconds), keyed by the beat it follows (`afterBeatIndex`, the beat's place from 0; at most one after any beat and never after the last), that may carry one sound (a breath, a bell) or one short line heard over the dark (at most 12 words), the narrator's or a character's own, always as a voice-over. It costs no render: the master draws the black and voices its line and its sound at no charge. Inserting, moving or removing a beat moves each black with the beat it follows. A whole list replaces the trailer's (an empty list removes them all); on a rendered trailer the master is stitched again with it, free. The whole list is validated: each follows a beat the plan has and never the last one, at most one after any beat, a line of at most 12 words, and a cast speaker who has a voice (400 otherwise). Free. On a draft plan the changed plan is queued for plan coverage again (`planCoverage`); in review or complete the master is re-assembled with the black, its lines and its sounds (`reassembling`). Refused while a render or finish pass runs (409). Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TrailerInterludesUpdateRequest
  - `interludes` TrailerInterludeInput[], required: Every interlude the trailer should have; [] removes them all.
    - `afterBeatIndex` integer, required: The beat the black follows (its `beatIndex`, from 0) — never the last beat, at most one interlude after any beat.
    - `seconds` number, required: How long the screen holds black (a line over it holds it as long as the line needs).
    - `line` string: One short sentence heard over the black (at most 12 words).
    - `speaker` string, nullable: Who says `line`: an exact canon cast name with a voice, or NARRATOR (the default: the trailer's narrator).
    - `sound` string: One sound heard in the dark, never music.

## Response `200`

The trailer's interludes, as saved.

- TrailerInterludesUpdateAck
  - `success` true, required
  - `jobId` string, required
  - `interludes` TrailerInterlude[], required
    - `afterBeatIndex` integer, required: The `beatIndex` of the beat the black follows (its place in the trailer, from 0).
    - `afterBeatNumber` integer, required: The place of that beat in the trailer, from 1: "after beat 3".
    - `seconds` number, required: How long the black holds, as planned.
    - `line` string: The words heard over the black, when it carries a line.
    - `speaker` string: Who says `line`: a canon cast name, or NARRATOR (the trailer's narrator). Always heard as a voice-over.
    - `sound` string: The one sound heard in the dark, when it carries one.
    - `durationMs` integer, required: How long it holds black in the master: its seconds, or as long as its voiced line needs (at most 5 s).
    - `audioUrl` string, nullable, required: The voiced line, once an assembly has made it for the line as it stands.
    - `soundUrl` string, nullable, required: The sound, once an assembly has made it for the sound as it stands.
    - `error` string, nullable, required: Why its line or its sound could not be made, when one could not (a narrator line on a trailer with no narrator, a cast member with no voice, a sound with a voice in it).
  - `reassembling` boolean, required: True when the master is re-assembled for the change (a trailer in review or complete; free).
  - `planCoverage` 'queued' | 'current' | 'failed' | 'null', nullable, required: On a draft: the changed plan's coverage (`queued` for the latest edit). Null otherwise.
  - `masterHold` TrailerMasterHold: On a rendered trailer with no screenplay, a blank beat holds its video: nothing rebuilds it until each blank beat is a capture beat or a title card, or removed (then it is rebuilt, free); the answer's `masterHold` names the beats and the fix, and the export is refused with it (`trailer_capture_only`).
    - `blankBeats` integer[], required: The blank beats, numbered from 1.
    - `message` string, required: The sentence to show: the beats, that the video keeps playing, and the fix.

## 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 named project or source does not exist or is owned by another account.
- `409`: The trailer exists and the request is well-formed, but the trailer, its beat, its cast or its plates are not in a state that allows it (`trailer_state_invalid`), and nothing was reserved: a plan approved outside draft, a take chosen or a beat rendered outside review/complete, an export before the finish, a finish while a call has no selected take, a narrated cut with no narrator, a render the compile blocked, or a finish while the master failed its video coverage (`trailer_video_coverage_failed`, with `details.videoCoverage`). `details.refusal` is `{ code, action, fix }` (see TrailerRefusalDetails): `action` is what unblocks it — `recast_figure`, `add_signature_items`, `recast_voice` or `remake_location_plate` — and `fix` names the MCP tool and CLI command that take it; `details.blocked[]` lists every beat a blocked compile could not render. The identical request succeeds once the trailer is put right.
- `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)