Talking head video background music: a bed under the voice

Background music for a talking head or UGC-style video should sit well under the voice, mixed in once the speech exists, so every word stays clear. On a Sume avatar video, add the bed through an avatar video preview: its package.soundtrack either generates music from a text prompt or mixes in a track you link, at a volume from 0.05 to 0.4 (default 0.15). For a clip already in your workspace's media, a Timeline 1.0 soundtrack adds a fade-out and ducking.

Fields and limits come from the Sume API reference, Avatar video previews, Timeline 1.0, and Music 1.0, read on 2026-09-27. Anything described as current behavior is read from Sume's code.

Does a Sume talking head video come with music?

Not by default. In current code, the prompt behind each avatar clip asks for none: it includes "No subtitles. No background music." Music is a step you add, either through the avatar video preview or afterwards.

How do I add music in the avatar video request?

Put package.soundtrack on an avatar video preview, then call generate-video on the preview's id. The preview stores the package and applies it only at generate-video; preview stills are never muxed. Do not send package to POST /v1/avatar-1.0/talking-video: in current code that route refuses it with 400 invalid_request, even though the reference lists it. Avatar video previews covers the preview flow.

curl -X POST https://api.sume.com/v1/avatar-video-previews \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: host-intro-bgm-001" \
  -d '{
    "avatar_handle": "product_host",
    "script": "Three things to know before you pick a travel mug.",
    "package": {
      "soundtrack": {
        "prompt": "Warm lo-fi beat, soft Rhodes, 80 BPM. Instrumental, no vocals, no spoken word.",
        "volume": 0.12
      }
    }
  }'

Where does the music come from?

soundtrack takes exactly one of two sources:

• prompt (up to 5,000 characters): Sume generates the bed with Music 1.0 and reserves a Music 1.0 estimate on top of the video. The Music 1.0 docs say it is retiring gradually, with every request now resolving through the Music Router, and suggest closing the prompt with "Instrumental, no vocals.", adding "no spoken word" under narration.
• audio_url: a track already at a public HTTPS URL. Sume mirrors it into its own media storage when it can, then mixes it in, with no music reservation. Localhost and private URLs are refused, and a dead link is only caught at generate-video, where it soft-fails.

How loud should the music be, and can it duck?

volume is a linear level for the bed under speech, from 0.05 to 0.4, with 0.15 as the default; start there and adjust by ear. It is the only level control in package.soundtrack, which has no fade or duck field. When the bed should dip while someone talks or fade out at the end, mix it in a Timeline 1.0 render, whose default of −16 dB the reference calls "a bed level under a spine":

What if the music step fails?

The video still arrives. A soundtrack or mux failure soft-fails and keeps the furthest successful video: the captioned cut if you also asked for captions and they worked, otherwise the clean talking head. GET /v1/avatar-videos/{id} reports package.soundtrack.status as skipped, pending, ready, or failed, and a failure carries a public_reason such as soundtrack_unavailable or music_generation_failed.

Can I add music to a talking head video I already have?

Only if it is already on Sume: Timeline 1.0 takes only your workspace's media.sume.com media, such as an earlier Sume job's output. In that render, the clip's voice, extracted with audio detach, is the spine, the clip fills the picture, and the soundtrack goes underneath with the fields above. Add background music to a video with an API walks through that render.