---
title: "Replace the deck's black interludes."
method: POST
path: "/pitch-decks/{jobId}/interludes"
tags: ["Pitch Deck"]
---

# Replace the deck's black interludes.

`POST /pitch-decks/{jobId}/interludes`

## Request

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

Replaces the deck's black interludes with the list given (`[]` removes them all; the chapters read returns the current ones as `interludes`). A black interlude is a beat of pure black between two chapters (0.5 to 2 seconds), keyed by the chapter it follows (`afterChapterIndex`), that may carry one sound (a breath, a bell) or one short line heard over the dark, 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. The whole list is validated: each follows a chapter the plan has and never the last one, at most one after any chapter, 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

- PitchDeckInterludesUpdateRequest
  - `interludes` PitchDeckInterludeInput[], required: Every interlude the deck should have; [] removes them all.
    - `afterChapterIndex` integer, required: The chapter the black follows — never the last chapter, at most one interlude after any chapter. The chapter's `chapterIndex`, exactly as the chapters read returns it: a key, not a position — a plan may key its chapters from 0 or from 1. A person's "chapter 2" is the chapter whose `chapterNumber` is 2; pass that chapter's `chapterIndex`.
    - `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).
    - `sound` string: One sound heard in the dark, never music.

## Response `200`

The deck's interludes, as saved.

- PitchDeckInterludesUpdateAck
  - `success` true, required
  - `jobId` string, required
  - `interludes` PitchDeckInterlude[], required
    - `afterChapterIndex` integer, required: The `chapterIndex` of the chapter the black follows.
    - `afterChapterNumber` integer, nullable, required: The place of that chapter in the deck, from 1: "after chapter 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. 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.
  - `reassembling` boolean, required: True when the master is re-assembled for the change (a deck 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.

## 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 pitch deck exists and the request is well-formed, but the deck, its chapter, its cast or its plates are not in a state that allows it (`pitch_deck_state_invalid`), and nothing was reserved: a plan approved outside draft, a take chosen, a chapter edited or rendered outside review/complete, an export before the finish, a finish while a call has no selected take or a footage chapter has not rendered, a text-only chapter asked for footage, a changed chapter asked for one call, a delivery class changed mid-pass, a render the compile blocked, or a finish while the master failed its video coverage (`pitch_deck_video_coverage_failed`, with `details.videoCoverage`). `details.refusal` is `{ code, action, fix }` (see PitchDeckRefusalDetails): `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 chapter a blocked compile could not render. The identical request succeeds once the deck 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/86e084144cef?raw)