--- title: "Set the deck's title sequence." method: POST path: "/pitch-decks/{jobId}/title-sequence" tags: ["Pitch Deck"] --- # Set the deck's title sequence. `POST /pitch-decks/{jobId}/title-sequence` ## Request - Base URL: `https://docs.sleeperhit.studio/api/v1` - URL: `https://docs.sleeperhit.studio/api/v1/pitch-decks/{jobId}/title-sequence` - Auth: HTTP bearer Sets the deck's title sequence whole (`null` removes it; the chapters read returns the current one as `titleSequence`, with what each flash cut goes to and each person's name super, `supers`). A deck's title sequence opens its master, before the first chapter: optionally an epigraph (`epigraph`: its words and where they are from) and a source credit (`sourceCredit`), each quiet on black and held long enough to read; then flash cuts of six to ten frames to the people it names (`cast`, in order; `inShadow` darkens one), each the person's LIVING PORTRAIT — looking into the lens, still, breathing, rendered for the flash (priced first, its own step) — and until it is made a still, silent close from the deck's own takes or another rendered deck of the project (free), never one in which anyone speaks or moves; a still canon portrait image only when the writer asks for one (`flashSource: 'portrait'`); then the title (`title`, one word, in capitals) in a bold sans on black. The flash cuts and the title run `seconds` (3 to 5). With `nameSupers: true` each flash cut carries the person's NAME in the TITLE'S LOOK — the face and colour the title is drawn in (blood red, the heavy condensed sans, when the title is directed so), uppercase, large enough to read at 480p — on the bell beat with the face, set in the black BESIDE the picture (or over the top of it), never over the face: LABEL is the first word of the person's canon name in capitals unless their cast entry sets `label`, and `role` (up to 40 characters, optional) is a smaller line under it; a person `inShadow` gets no name unless their `label` is set (the shadow withholds who they are); how the names look and where they sit is directed with `titleElement: nameSupers`. With `beatGrid: true` the intros cut on the bell's beat: from the sequence's first frame a beat every `beatSeconds` (0.5 to 4; 2 when left out), each flash cut starting on a beat and holding exactly one beat (the one in shadow too), the title on the next beat for `titleBeats` beats (1 to 8; 2 when left out) — their seconds are then derived (beats × beatSeconds), and a score composed to the deck strikes its bell on every intro and on the title. Saving it is free: nothing is rendered for it (a motion close is its own priced step). `enabled: false` keeps it without playing it. How its words look and move is directed separately (`titleElement` on the direct-text-motion call; read back as `textMotion`), and a save keeps those directions. Validated whole: a one-word title, nobody named twice, and everyone in the cast canon when the project has one (400 otherwise). Free. On a draft plan the changed plan is queued for plan coverage again (`planCoverage`: the story judge reads the title); in review or complete the master is re-assembled with it (`reassembling`). Refused while a render or finish pass runs (409). Requires `Idempotency-Key`. Scope: `story:write`. ## Headers - `Idempotency-Key` string, required ## Request body - PitchDeckTitleSequenceUpdateRequest - `titleSequence` PitchDeckTitleSequence, required: A deck's title sequence opens its master, before the first chapter: optionally an epigraph (`epigraph`: its words and where they are from) and a source credit (`sourceCredit`), each quiet on black and held long enough to read; then flash cuts of six to ten frames to the people it names (`cast`, in order; `inShadow` darkens one), each the person's LIVING PORTRAIT — looking into the lens, still, breathing, rendered for the flash (priced first, its own step) — and until it is made a still, silent close from the deck's own takes or another rendered deck of the project (free), never one in which anyone speaks or moves; a still canon portrait image only when the writer asks for one (`flashSource: 'portrait'`); then the title (`title`, one word, in capitals) in a bold sans on black. The flash cuts and the title run `seconds` (3 to 5). With `nameSupers: true` each flash cut carries the person's NAME in the TITLE'S LOOK — the face and colour the title is drawn in (blood red, the heavy condensed sans, when the title is directed so), uppercase, large enough to read at 480p — on the bell beat with the face, set in the black BESIDE the picture (or over the top of it), never over the face: LABEL is the first word of the person's canon name in capitals unless their cast entry sets `label`, and `role` (up to 40 characters, optional) is a smaller line under it; a person `inShadow` gets no name unless their `label` is set (the shadow withholds who they are); how the names look and where they sit is directed with `titleElement: nameSupers`. With `beatGrid: true` the intros cut on the bell's beat: from the sequence's first frame a beat every `beatSeconds` (0.5 to 4; 2 when left out), each flash cut starting on a beat and holding exactly one beat (the one in shadow too), the title on the next beat for `titleBeats` beats (1 to 8; 2 when left out) — their seconds are then derived (beats × beatSeconds), and a score composed to the deck strikes its bell on every intro and on the title. Saving it is free: nothing is rendered for it (a motion close is its own priced step). `enabled: false` keeps it without playing it. How its words look and move is directed separately (`titleElement` on the direct-text-motion call; read back as `textMotion`), and a save keeps those directions. - `enabled` boolean, required: Whether the deck opens on it. False keeps it without playing it. - `title` string, required: One word, shown in capitals ("KARAMAZOV"). - `cast` object[], required: Who the flash cuts go to, in order: the father first, then each son, the one in shadow last. Each must be in the cast canon when the project has one. - `name` string, required: An exact canon cast name, or an alias the canon lists. - `inShadow` boolean: Show them in shadow: a dark flash, the face half-lost. A person in shadow gets no name super unless their `label` is set. - `role` string: A smaller line under their name ("the father"), shown when `nameSupers` is on. Leave it out for the name alone (the default). - `label` string: The name their super shows, set in capitals, instead of the first word of their canon name ("GRUSHENKA"). Setting it is also what gives a person in shadow a super. - `flashSource` 'deck' | 'project' | 'motion' | 'portrait': Where their flash cut is taken from first: `motion` (their living portrait: into the lens, still, breathing, rendered for the flash, priced first), `deck` (a still, silent close from this deck's shots), `project` (a still, silent close from another rendered deck of the project, free) or `portrait` (their STILL portrait image — only when the writer asks for one). Left out: their living portrait, else a still, silent close from this deck, then the project; a close in which anyone speaks or moves is never used. - `seconds` number, required: How long the flash cuts and the title run. - `epigraph` object: An epigraph shown first, alone on black, held long enough to read (about 3 words a second, at least 4 s). - `text` string, required: Its words, exactly as the source gives them. - `attribution` string: Where the words are from ("John 12:24"). - `sourceCredit` string: A credit shown after the epigraph and before the title ("From the novel by Fyodor Dostoevsky"). - `nameSupers` boolean: Name each face: every flash cut carries the person's name (`LABEL`, e.g. "FYODOR", with a smaller `role` line under it when one is given) in the title's look — its face and colour, uppercase — beside the picture (or over the top of it), never over the face; directed with `titleElement: nameSupers`. A person in shadow gets none unless their `label` is set. Off when left out. Free. - `beatGrid` boolean: Cut the intros on the bell's beat: from the sequence's first frame a beat every `beatSeconds`, each flash cut starting on a beat and holding exactly one beat (the one in shadow too), the title on the next beat for `titleBeats` beats. Their seconds are then derived (beats × beatSeconds; `seconds` is not used), and a score composed to the deck strikes its bell on every intro and on the title. Off when left out. Free. - `beatSeconds` number: The bell's beat in seconds (0.5 to 4; 2 when left out), kept to the millisecond. - `titleBeats` integer: On the grid, how many whole beats the title holds (1 to 8; 2 when left out — 4 s on a 2 s bell, long enough for a score to give the title its own section). ## Response `200` The deck's title sequence, as saved. - PitchDeckTitleSequenceUpdateAck - `success` true, required - `jobId` string, required - `titleSequence` PitchDeckTitleSequenceView, required: A deck's title sequence opens its master, before the first chapter: optionally an epigraph (`epigraph`: its words and where they are from) and a source credit (`sourceCredit`), each quiet on black and held long enough to read; then flash cuts of six to ten frames to the people it names (`cast`, in order; `inShadow` darkens one), each the person's LIVING PORTRAIT — looking into the lens, still, breathing, rendered for the flash (priced first, its own step) — and until it is made a still, silent close from the deck's own takes or another rendered deck of the project (free), never one in which anyone speaks or moves; a still canon portrait image only when the writer asks for one (`flashSource: 'portrait'`); then the title (`title`, one word, in capitals) in a bold sans on black. The flash cuts and the title run `seconds` (3 to 5). With `nameSupers: true` each flash cut carries the person's NAME in the TITLE'S LOOK — the face and colour the title is drawn in (blood red, the heavy condensed sans, when the title is directed so), uppercase, large enough to read at 480p — on the bell beat with the face, set in the black BESIDE the picture (or over the top of it), never over the face: LABEL is the first word of the person's canon name in capitals unless their cast entry sets `label`, and `role` (up to 40 characters, optional) is a smaller line under it; a person `inShadow` gets no name unless their `label` is set (the shadow withholds who they are); how the names look and where they sit is directed with `titleElement: nameSupers`. With `beatGrid: true` the intros cut on the bell's beat: from the sequence's first frame a beat every `beatSeconds` (0.5 to 4; 2 when left out), each flash cut starting on a beat and holding exactly one beat (the one in shadow too), the title on the next beat for `titleBeats` beats (1 to 8; 2 when left out) — their seconds are then derived (beats × beatSeconds), and a score composed to the deck strikes its bell on every intro and on the title. Saving it is free: nothing is rendered for it (a motion close is its own priced step). `enabled: false` keeps it without playing it. How its words look and move is directed separately (`titleElement` on the direct-text-motion call; read back as `textMotion`), and a save keeps those directions. - `enabled` boolean, required: Whether the deck opens on it. False keeps it without playing it. - `title` string, required: One word, shown in capitals ("KARAMAZOV"). - `cast` object[], required: Who the flash cuts go to, in order: the father first, then each son, the one in shadow last. Each must be in the cast canon when the project has one. - `name` string, required: An exact canon cast name, or an alias the canon lists. - `inShadow` boolean: Show them in shadow: a dark flash, the face half-lost. A person in shadow gets no name super unless their `label` is set. - `role` string: A smaller line under their name ("the father"), shown when `nameSupers` is on. Leave it out for the name alone (the default). - `label` string: The name their super shows, set in capitals, instead of the first word of their canon name ("GRUSHENKA"). Setting it is also what gives a person in shadow a super. - `flashSource` 'deck' | 'project' | 'motion' | 'portrait': Where their flash cut is taken from first: `motion` (their living portrait: into the lens, still, breathing, rendered for the flash, priced first), `deck` (a still, silent close from this deck's shots), `project` (a still, silent close from another rendered deck of the project, free) or `portrait` (their STILL portrait image — only when the writer asks for one). Left out: their living portrait, else a still, silent close from this deck, then the project; a close in which anyone speaks or moves is never used. - `seconds` number, required: How long the flash cuts and the title run. - `epigraph` object: An epigraph shown first, alone on black, held long enough to read (about 3 words a second, at least 4 s). - `text` string, required: Its words, exactly as the source gives them. - `attribution` string: Where the words are from ("John 12:24"). - `sourceCredit` string: A credit shown after the epigraph and before the title ("From the novel by Fyodor Dostoevsky"). - `nameSupers` boolean, required: Whether the flash cuts carry name supers (false when the sequence leaves it out). - `beatGrid` boolean: Cut the intros on the bell's beat: from the sequence's first frame a beat every `beatSeconds`, each flash cut starting on a beat and holding exactly one beat (the one in shadow too), the title on the next beat for `titleBeats` beats. Their seconds are then derived (beats × beatSeconds; `seconds` is not used), and a score composed to the deck strikes its bell on every intro and on the title. Off when left out. Free. - `beatSeconds` number: The bell's beat in seconds (0.5 to 4; 2 when left out), kept to the millisecond. - `titleBeats` integer: On the grid, how many whole beats the title holds (1 to 8; 2 when left out — 4 s on a 2 s bell, long enough for a score to give the title its own section). - `playing` boolean, required: True when it plays in the master (enabled, with a title, someone to cut to, and a chapter after it). - `textMotion` object: How its words look and move, as directed (absent for words in the sequence's own type). Set by POST /pitch-decks/{jobId}/storyboard/direct-text-motion with a `titleElement`, never by a save of the sequence (which keeps them). The title sequence's words are directed like a chapter's text, in the writer's own words, through the same direct-text-motion call with a `titleElement` instead of a `chapterIndex`: `title` ("KARAMAZOV huge, blood red, a stark sans, the ends cut off by the frame"), `epigraph` ("a subtle background behind the verse: grain, a candle's flicker, a few falling seeds"), `sourceCredit`, or `nameSupers` (every name alike: its face, its colour, and where it sits — beside the face on the left or the right, over the top of the picture, or under it; never over a face). The director compiles the sentence into a motion-text spec — the face (the show's, or a bundled grotesque or condensed grotesque), the colour, the size (up to edge to edge, wider than the frame so the frame cuts the first and last letters), how it moves, and a seeded background behind it (film grain, a breathing vignette, a flickering warm light, banks of fog rolling across the frame, slowly falling motes), as quiet or as strong and moving as asked ("the same fog as the verse, but stronger"), held under the words' own brightness (behind the blood-red title it is a haze of the same red) — and saves it with the sentence on the title sequence (`textMotion`). The words stay the sequence's: a direction says how they look, never what they say. `clear: true` puts an element back in the sequence's own type. Free: an LLM call, no credits; a rendered deck's master is stitched again with it, and nothing else renders (no chapter, no shot). A save of the title sequence keeps every direction (an element whose words are removed loses its own). - `title` PitchDeckTitleTextMotion: One of the title sequence's words, directed: the writer's sentence and the motion-text spec compiled from it, which the master executes. - `direction` string, required: The writer's own words for how it looks and moves. - `spec` object, required: The motion-text spec: version, layers (each a text, atmosphere, particle… layer with its face, fit, colours and keyframed steps). - `epigraph` PitchDeckTitleTextMotion: One of the title sequence's words, directed: the writer's sentence and the motion-text spec compiled from it, which the master executes. - `direction` string, required: The writer's own words for how it looks and moves. - `spec` object, required: The motion-text spec: version, layers (each a text, atmosphere, particle… layer with its face, fit, colours and keyframed steps). - `sourceCredit` PitchDeckTitleTextMotion: One of the title sequence's words, directed: the writer's sentence and the motion-text spec compiled from it, which the master executes. - `direction` string, required: The writer's own words for how it looks and moves. - `spec` object, required: The motion-text spec: version, layers (each a text, atmosphere, particle… layer with its face, fit, colours and keyframed steps). - `nameSupers` PitchDeckTitleTextMotion: One of the title sequence's words, directed: the writer's sentence and the motion-text spec compiled from it, which the master executes. - `direction` string, required: The writer's own words for how it looks and moves. - `spec` object, required: The motion-text spec: version, layers (each a text, atmosphere, particle… layer with its face, fit, colours and keyframed steps). - `beatTimeline` object, nullable, required: The bell beat grid (null when `beatGrid` is off): the beat, the derived length of the flash cuts and the title (`beats` × `beatSeconds` = `seconds`), and where each intro and the title land — the beat each starts on, its frames, and its start in the sequence and in the master (frames and seconds; the master's are null while the sequence does not play). - `beatSeconds` number, required - `titleBeats` integer, required: How many beats the title holds (2 when the sequence leaves `titleBeats` out). - `fps` integer, required - `beats` integer, required: The intros (one beat each) and the title's beats. - `seconds` number, required: The derived length of the flash cuts and the title. - `intros` object[], required - `name` string, required - `beat` integer, required: The beat it starts on (beat 0 is the sequence's first frame). - `frames` integer, required: How long it holds: exactly one beat. - `sequenceFrame` integer, required - `sequenceSeconds` number, required - `masterFrame` integer, nullable, required - `masterSeconds` number, nullable, required - `title` object, required - `beat` integer, required - `beats` integer, required: Whole beats the title holds. - `frames` integer, required - `sequenceFrame` integer, required - `sequenceSeconds` number, required - `masterFrame` integer, nullable, required - `masterSeconds` number, nullable, required - `supers` object[], required: Each person's name super as the plan resolves it now, from the cast canon, in the cast's order. - `name` string, required - `text` string, nullable, required: How the super reads (`LABEL · role`, or `LABEL`), or null when they get none (supers off, or in shadow without a label). - `durationMs` integer, required: How long it runs in the master, its cards included. - `flashes` object[], required: What each flash cut goes to, once an assembly has resolved them (empty before the first). Every intro is a LIVING PORTRAIT (owner, 2026-10-07: "They should just be looking at the camera and breathing but not in motion … we don't want them to be speaking unless we're using words"). Each person's flash is, in order: their living portrait (`source: motion`: one short WAN shot rendered for the flash from their cast portrait, the person looking straight into the lens, still, breathing, an occasional blink, lips closed, lit and graded like the deck, 480p, a few seconds, PRICED FIRST through the motion-close step and never spent silently; one another deck of the project made is reused free); until one is made, a STILL, SILENT close of them from the deck's own cut (`source: cut`, free) or another rendered deck of the project (`source: reuse`, free; `fromDeck` names it), with `needsMotionClose: true` while their living portrait is not made. A close stands in only when nobody speaks on camera in its shot, the mouth check and the take watcher saw no mouth move there, the person is alone, and its picture measured still (no walk, gesture, turn or camera move) — in motion means speaking with words, and a flash plays the score, never a line, so a close in which anyone speaks or moves never opens an intro. A person `inShadow` stays in shadow, as still. A cast entry's `flashSource` (`motion`, `deck`, `project` or `portrait`) puts that source first; `portrait` is their still canon portrait image, used only when asked for. With neither, `source` is `missing` with `needsMotionClose: true`: their beat stays black, and `motionClosesNeeded` prices the living portrait that would fill it. - `name` string, required - `inShadow` boolean, required - `source` 'cut' | 'reuse' | 'motion' | 'portrait' | 'missing', required: `motion`: their living portrait; `cut`: a still, silent close from the deck's own cut; `reuse`: a still, silent close from another rendered deck of the project (free); `portrait`: their still portrait image (only when asked for); `missing`: nothing to cut to (the beat stays black; the note says what to do). - `moving` boolean, required: True when the flash is footage (a living portrait or a close), not a still image. - `url` string, nullable, required - `startSeconds` number, nullable, required: Where in its video the flash starts (a moving flash). - `chapterNumber` integer, nullable, required: The chapter of this deck the close comes from, by its place in the deck from 1 (a `cut` flash). - `framing` string, nullable, required - `note` string, nullable, required - `nameSuper` string, nullable, required: The name this flash cut carried when the master was last assembled (with its role after a ` · ` when one is given), or null. - `fromDeck` object, nullable, required: The other deck of the project a reused close (or a reused motion close) is from. - `jobId` string, required - `chapterNumber` integer, nullable, required: Its chapter's place in that deck (null for a motion close). - `needsMotionClose` boolean, required: True when their living portrait is not made: it is what would fill their beat, or replace the still close standing in. - `motionCloses` object[], required: The living portraits rendered (or on their way) for the intros. A motion close is a person's LIVING PORTRAIT for their title intro: one WAN shot of their face and shoulders from their cast portrait, the person looking straight into the lens and holding still — breath, an occasional blink, lips closed — lit and graded like the deck (its Series Bible's look), at 480p, silent, 3 seconds on the 2 s bell (the flash's beat plus room), in shadow when the sequence keeps them in shadow. PRICED FIRST — TWO CALLS on the API and the CLI, two tools on MCP and in chat (quote_render_pitch_deck_title_motion_closes, then render_pitch_deck_title_motion_closes): without `confirmed` it prices every person whose intro is not yet their living portrait (`motionClosesNeeded` in the read: about 6 people × 3 s at 480p for a father and his sons), or the people named in `names` (a new take of someone who has one is priced again), and spends nothing; with `confirmed: true` it reserves exactly those lines and renders them. Allowed while the deck is in review or complete. When each lands it is checked like a take (a file that decodes, silent, its length) and the master is re-assembled with it, free; a render that fails or is refused is released (nothing charged). Read each one back as `titleSequence.motionCloses` (`livingPortrait` false: a moving close made before 2026-10-07, which no longer opens an intro). - `name` string, required - `take` integer, required - `status` 'queued' | 'rendering' | 'accepted' | 'failed', required: `accepted`: it plays; `failed`: released, nothing charged. - `url` string, nullable, required - `seconds` number, required - `credits` number, required - `inShadow` boolean, required - `failure` string, nullable, required - `requestedAt` string, date-time, required - `livingPortrait` boolean, required: True for a living portrait; false for a moving close made before 2026-10-07, which no longer opens an intro. - `motionClosesNeeded` object[], required: Whose intro is not yet their living portrait (nothing fills their beat, or a still close stands in), with the price of each. Empty when every intro opens on one. - `name` string, required - `seconds` number, required - `credits` number, required - `renderable` boolean, required: False when they have no cast portrait to render from (give them one first). - `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/4534f5d25540?raw)