Product
Audio Ducking API: Automatically Mix Voice and Music
- Written by
- Sonilo Team
- Published
POST /v1/audio-ducking takes a voice track and a music track and returns them mixed together, with the music automatically ducked under the speech — the same effect a podcast or radio producer rides by hand, done in one API call.
Quick answer
The Sonilo Audio Ducking API is a mixing endpoint, not a generation endpoint. You send it a foreground voice track (narration, dialogue, a voiceover) and a background music track, and it returns the two combined into a single mix where the music's volume automatically drops whenever the voice is speaking and comes back up during pauses — the classic "ducking" technique used in podcasts, ads, and narrated video. It doesn't write or compose anything; it takes audio you already have (your own voice recording plus either your own music or a Sonilo-generated track) and blends it intelligently. If the voice input you provide is a video file rather than plain audio, Sonilo extracts that video's audio track to use as the voice, ducks it against the music, and re-muxes the ducked audio back into a new video file so you get a finished video out, not just an audio file.
Parameters
| Field | Type | Notes |
|---|---|---|
| voice_file | file upload (audio or video) | Foreground speech/dialogue track. Provide this or voice_url — not both. If it's a video, its audio track is extracted and used as the voice input. |
| voice_url | string (URL) | URL to an audio or video file containing the foreground speech. Provide this or voice_file — not both. Same video-extraction behavior applies. |
| music_file | file upload (audio) | Background music bed to duck under the voice. Provide this or music_url — not both. |
| music_url | string (URL) | URL to an audio file containing the background music. Provide this or music_file — not both. |
Example request
The request body is multipart/form-data, not JSON — use -F fields with curl, or the equivalent form-data helper in your language.
curl -X POST https://api.sonilo.com/v1/audio-ducking -H "Authorization: Bearer $SONILO_API_KEY" -F voice_url=https://example.com/narration.mp3 -F music_url=https://example.com/track.mp3
Audio ducking is always processed asynchronously — there's no synchronous mode. The call above returns immediately with 202 { "task_id": "...", "status": "processing" }. Poll GET /v1/tasks/{task_id} until status is "succeeded" or "failed". On success, the task includes an audio object (or a video object, if you sent a video as voice_file/voice_url) with url, content_type, and file_size for the ducked result.
Combine with music generation
Audio ducking is designed to sit downstream of a music-generation step. A common pipeline:
- Generate a background track with Sonilo's text-to-music or video-to-music endpoint.
- Take the resulting audio URL from that task and pass it straight in as music_url.
- Pass your narration, voiceover, or narrated video as voice_file or voice_url, and let the ducking endpoint automatically balance the two.
That gives you a fully generated-and-mixed soundtrack — score plus voice — from two API calls, without opening a DAW.
FAQ
Can I control the ducking strength?
Not directly. Ducking is fully automatic in the current API — there's no ducking_level, threshold, or similar parameter to tune. You send voice and music inputs and Sonilo handles how much the music attenuates under speech.
Does it work if my voice input is a video file?
Yes. If voice_file or voice_url points to a video, Sonilo extracts that video's own audio track to use as the voice input, ducks the music underneath it, and re-muxes the ducked audio back into a new video. The task result then includes a video object instead of an audio object.
What formats are accepted for voice_file and music_file?
voice_file (or voice_url) accepts either an audio file or a video file. music_file (or music_url) accepts an audio file. For the current list of supported codecs and containers, see the full API reference linked below.
Does the audio-ducking endpoint generate music, or just mix audio?
It only mixes audio you supply — it doesn't compose or generate anything itself. If you need a music track first, generate one with Sonilo's text-to-music or video-to-music endpoints, then feed that output into audio-ducking as music_url.
Related Sonilo pages
- Full API reference: https://platform.sonilo.com/docs/api/audio-ducking
- Text-to-music docs: https://platform.sonilo.com/docs/api/text-to-music
- Pricing: https://sonilo.com/pricing
