---
title: "Trim one take of a beat's call to a span (free)."
method: POST
path: "/trailers/{jobId}/beats/{beatIndex}/trim-take"
tags: ["Trailer"]
---

# Trim one take of a beat's call to a span (free).

`POST /trailers/{jobId}/beats/{beatIndex}/trim-take`

## Request

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

NOT metered and NOT confirmed: FREE, one call. Trims one take to the span `[keepStartSeconds, keepEndSeconds)` — "trim this take to <start>–<end>" — snapped to the take's frames and kept as a NEW take linked to it (`trimTake`); the take itself stays. Never into a spoken line: a span that cuts into a line placed on the take's speech track is refused (`trim_cuts_speech`), as is a span outside the take, shorter than the shortest a take is trimmed to, or the whole take (`trim_span_invalid`) — each before anything is queued. The trimmed take is checked again and watched, and plays over the take it came from only if it passes; its cut then plays its real, shorter length. The repair engine does the same on its own when a cut nobody asked for sits at the start or end of an otherwise good take (rule `trim_edge`, measured in the file: a hard cut or the first frame of a dissolve), and when a speaker's lips run on past the take's last line where nothing is heard (rule `trim_overrun`: cut half a second after the line as the take says it). Each take's `trimBounds` says what it may keep. Review or complete only. Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- TakeTrimRequest: Trim one take of one call to a span ("trim this take to <start>–<end>"). Free: one call, nothing priced or reserved.
  - `callId` string, required: One of this unit's call ids (from the beats or chapters read).
  - `take` integer, required: The take to trim: an accepted take of the call.
  - `keepStartSeconds` number, required: Where the kept span starts, in seconds of the take (snapped to its frames).
  - `keepEndSeconds` number, required: Where the kept span ends, in seconds of the take; must keep every spoken line whole.

## Response `200`

The trim, queued as a new take.

- TakeTrimQueued: The trim is queued as a new take. Nothing was charged; the trimmed take is checked again when it lands and plays only if it passes.
  - `jobId` string, required
  - `callId` string, required
  - `take` integer, required
  - `trimTake` integer, required: The take number the trim is recorded as.
  - `keepStartSeconds` number, required
  - `keepEndSeconds` number, required
  - `queued` boolean, required
  - `message` string, required

## 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/86e084144cef?raw)