# Audio Ducking API

Canonical docs: https://platform.sonilo.com/docs/api/audio-ducking
Source path: /es/docs/api/audio-ducking
Runtime API host: https://api.sonilo.com/v1

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Endpoint

POST /v1/audio-ducking

## Summary

Mix foreground speech or narration with background music by lowering music under voice and returning a post-production output.

## Use This For

- Ducking music under narration for videos, ads, tutorials, podcasts, and social clips.
- Combining voice_file or voice_url with music_file or music_url.
- Agent-built audio post-production workflows that submit a job and poll for the output_url.

## Request

Content type: multipart/form-data

- `voice_file` (file; optional): Voice/narration audio or video file upload. Provide either `voice_file` or `voice_url`, not both. If this is a video file, its own audio track is used as the voice input and the output is a new video with the mixed audio track; a video with no audio track is rejected. Max file size is governed by your account's upload limit (`max_upload_size_mb`, default 300MB); duration is capped at 6 min.
- `voice_url` (string; optional): URL to a voice/narration audio or video file. Provide either `voice_file` or `voice_url`, not both. Must be a public `http://` or `https://` URL; private/internal addresses are rejected.
- `music_file` (file; optional): Background music audio file upload. Provide either `music_file` or `music_url`, not both. Should be audio; if a video file is provided, only its audio track is used and the video content is ignored.
- `music_url` (string; optional): URL to a background music audio file. Provide either `music_file` or `music_url`, not both. Must be a public `http://` or `https://` URL; private/internal addresses are rejected.

Machine-readable schema: https://platform.sonilo.com/openapi.json

### Usage notes

- Provide exactly one of voice_file or voice_url, and exactly one of music_file or music_url.

## Response And Errors

- 202 returns task_id and status=processing.
- Poll GET /v1/tasks/{task_id} every 2-3 seconds until status is succeeded, failed, or canceled.
- On success, use output_url or audio.url from the task response.
- 401, 402, 403, 404, and 429 have the same auth, balance, permission, not-found, and Retry-After meanings as other endpoints.

## Example

```bash
curl -X POST "https://api.sonilo.com/v1/audio-ducking" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "voice_file=@voice.wav" \
  -F "music_file=@music.wav"
```

## Shared Error Handling

- 401 auth_invalid: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits before rerunning; do not create fake audio.
- 403 forbidden: the key is valid but the account or service permission is missing.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 429 rate_limit_exceeded: honor Retry-After and retry with backoff.

## Endpoint Vocabulary

- GET /v1/account/services
- GET /v1/account/usage
- POST /v1/text-to-music
- POST /v1/video-to-music
- POST /v1/video-to-video-music
- POST /v1/audio-ducking
- POST /v1/text-to-sfx
- POST /v1/video-to-sfx
- POST /v1/video-to-video-sfx
- POST /v1/video-to-sound
- POST /v1/video-to-video-sound
- GET /v1/tasks/{task_id}