---
title: "Edit the project-level audio timeline."
method: POST
path: "/trailers/{jobId}/storyboard/audio-timeline"
tags: ["Trailer"]
---

# Edit the project-level audio timeline.

`POST /trailers/{jobId}/storyboard/audio-timeline`

## Request

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

One endpoint, selected by `action`: add-music-layer, remove-music-layer, generate-music-clip, add-music-clip-from-library, update-music-clip, remove-music-clip, generate-sfx-cue, add-sfx-cue-from-library, update-sfx-cue, update-sfx-cues, remove-sfx-cue, set-voice-duck, set-narration-level, remake-flagged-sfx-cues (set-voice-duck takes `voiceDuckDb`: how far the music dips under the voices in dB, -18..0, or null to restore the default dip; heard in the preview and baked into the render; set-narration-level takes `sceneIndex` and `level`: a beat's narration level, 0..2 with 1 as recorded, or null to restore the default). Music clips render with the Lyria engine, so they are never blocked by the fal balance; describe the SOUND rather than naming a real artist. A sound-effect cue (generate-sfx-cue, add-sfx-cue-from-library) takes `kind` (`spot`: one event, its own length; `ambience`: a bed under the picture that, with no `lengthMs`, fills its scene from the offset or through `endSceneIndex`, repeating the effect crossfaded, at 0.2 with short fades unless set), `lengthMs` (how long it sounds, 100..3600000; longer than the effect repeats it), `fadeInMs` / `fadeOutMs` (0..60000) and `level`; `durationSeconds` is how long the effect is generated (up to 22). update-sfx-cue changes any of them, `muted` silences a cue without removing it, and null `lengthMs` / `endSceneIndex` put it back on its default span. update-sfx-cues changes or removes several cues in ONE write (a re-balance): `cues`, 1 to 40 entries, each update-sfx-cue's fields with its `cueId`, or `{ cueId, remove: true }`; the answer's `results` says what each did (one naming no cue changes nothing while the rest land). remake-flagged-sfx-cues makes every cue whose file came out too quiet, clipped or gappy again from its own words — the same kind, place, length, fades and mute — and re-levels it to its band when the new file lands, never by turning it up; healthy and unmeasured cues are untouched. Every cue's file is measured as it is placed and played levelled before its `level`, so a level is a place in the mix: the sound map's `suggestedLevels` and each cue's `targetLevel` put a bed 10–14 dB and a spot 3–8 dB under its scene's own mix. The cue in the answer, and every cue in its timeline, carries `assetLufs`, `normGainDb`, `mixLufs` and `loudnessFlag` (see the timeline read). Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `action` string, required
  - `voiceDuckDb` number, nullable: set-voice-duck's value: how far the music dips under the voices in dB (-18..0); null restores the default dip.
  - `sceneIndex` integer: set-narration-level's beat (0-based).
  - `level` number, nullable: set-narration-level's value: the beat's narration level (0..2; 1 is as recorded); null restores the default.

## Response `200`

The updated timeline, plus a shareable per-beat preview link where the change touched one beat.

- object

## 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.
- `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)