Duck background music under a voiceover with the Timeline API

To duck music under a voiceover with Sume, render with Timeline 1.0 and add a soundtrack whose duck_db is between 0 and 20. The voiceover is the render's audio spine, the soundtrack is the music bed, and duck_db sets how far the bed dips while the spine speaks. It needs a real spine: duck_db with audio.mode: "silence" is refused as duck_requires_audio_spine.

Fields come from the Timeline 1.0 docs, read 2026-09-29. The docs do not say how the dip is shaped in time, so listen to a short render before you set a value for a whole batch.

What does the request look like?

Every URL must already be a media.sume.com file in your workspace (import first with POST /v1/media-imports). Idempotency-Key is required.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: duck-001" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
      "duration_seconds": 24
    },
    "soundtrack": {
      "url": "https://media.sume.com/artifacts/artf_demo/bed.mp3",
      "loop": true,
      "duck_db": 12,
      "fade_out_seconds": 2
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 0, "duration": 24 }
    ]
  }'

Which soundtrack fields exist?

What does it cost?

The render is $0.10 per output minute, reserved as ceil(audio.duration_seconds / 60) minutes; a 24 second render reserves one. The docs note no provider inference is involved, only worker ffmpeg. You can call POST /v1/timeline-1.0/plan first: it is unbilled and returns billable_minutes and estimated_cost_usd_micros without creating a job.

What else can trip it?

• soundtrack_fade_exceeds_output: the fade is longer than the spine.
• video[0].start must be 0, or the render fails with timeline_must_start_at_zero.
• Off-host URLs are rejected as unsupported_media_source.

How do I make the voiceover spine?

If your voiceover is several audio files, list them in audio.parts[] (at most 20, joined gaplessly in the sample domain with no re-synthesis) when they are only needed inside this render. If you need one reusable file, POST /v1/timeline-1.0/audio with operation: "concat" joins up to 20 parts for $0.01 per job and returns the offsets to line your video[].start values up against.