Trailer

Make a trailer from the project's app captures alone, with no screenplay (free).

A capture-only trailer is a NEW draft trailer for the whole project with no screenplay behind it: its beats play the project's app captures exactly as recorded (and title cards), never filmed footage. Creating it is free. captureId seeds beat 1 with a ready capture, the whole of it or the stretch captureKeep keeps (a capture longer than 30 seconds opens on a kept stretch of 4 to 30 seconds); without one, beat 1 is a title card with the trailer's title. Add a beat per capture (insert a beat, then refine it with compositionKind: 'capture' and the captureId). Approving the plan needs at least one capture beat and renders nothing: it assembles the cut from the captures, and only a title card's text layer is ever priced. A beat that would be filmed is refused (trailer_capture_only): there is no screenplay to film from. captureOnly: true is required (a planned trailer is made from a story plan). captureId is checked before anything is stored, with the stretch captureKeep keeps of it when one is sent (a capture longer than 30 seconds opens on a kept stretch of 4 to 30 seconds; captureKeep without captureId is 400): a capture that is not the project's, not ready, a raw master, playing outside 4 to 30 seconds, a kept stretch that does not fit it, or in another shape than aspectRatio is refused with 409 trailer_state_invalid (details.refusal.code names the problem: trailer_capture_raw, trailer_capture_length, trailer_capture_keep_range, trailer_capture_keep_cuts_result, trailer_capture_shape, trailer_capture_not_ready, trailer_capture_rejected) or 404 capture_not_found, and no trailer is made. NOT metered and NOT confirmed. Requires Idempotency-Key. Scope: story:write. Only a product project whose workspace gate is open makes one, as the Videos page offers it only then: a story project is refused with 409 project_not_product, and a product project whose product Bible is not complete or whose product coverage has not passed with 409 project_precondition_failed (details.stage names the stage), before anything is stored.

post/story-projects/{projectId}/trailers

Request

  • Base URL: https://docs.sleeperhit.studio/api/v1
  • URL: https://docs.sleeperhit.studio/api/v1/story-projects/{projectId}/trailers
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Customer-generated stable identifier for safe retries of idempotent POST requests.

Request body

captureOnlytrue required

Always true: the trailer plays the project's app captures alone. A planned trailer is made from a story plan.

titlestring required

The trailer's name.

aspectRatio'16:9' | '9:16' | '1:1'

The shape it plays at. Every capture it plays must have this shape.

captureIdstring

A ready app capture of the project (an edit, never a raw master; playing 4 to 30 seconds — the whole capture, or the stretch captureKeep keeps; in aspectRatio) to play as beat 1. Omitted: beat 1 is a title card with the title.

Response

The new draft trailer.

jobIdstring required

The NEW draft trailer. Every trailer tool takes this id from here on.

projectIdstring required
status'draft' required
titlestring required

The trailer's name.

aspectRatio'16:9' | '9:16' | '1:1' required
audioPolicystring required

narrate (the default): a beat's narration line is spoken once a narrator is chosen.

beatsinteger required

How many beats it starts with.

captureBeatsinteger required

How many of them play an app capture.

planCoverage'not_needed' required

A trailer with no screenplay is never scored by plan coverage; its cut is reviewed once it is made.

nextStep'approve_trailer_plan' required
reviewUrlstring nullable required

A logged-in deep link that opens the trailer on the project's Videos page.

conversationIdstring nullable required

The Slug conversation that governs the trailer. It is made with its Slug conversation already bound (conversationId): Slug inserts, refines and approves its beats in that conversation without the Videos page being opened first. A workspace whose plan does not include a video's conversation gets none (conversationId null): the video is edited on the Videos page, the Story API, MCP or the CLI.

credits0 required

Always 0: making it renders and reserves nothing.

notestring required

What was made and what happens next, in one paragraph to read out.

Changes

No recorded changes to this operation across all 2 revisions of this API.