Audio Ducking

For AI agents →2 calls free, no credit card required.

Mix a voice (or narration) track with a background music track, automatically lowering the music while the voice is speaking. Returns 202 Accepted with a task_id; poll GET /v1/tasks/:task_id until the task reaches a terminal status.

Agent answer

Agent answer: for audio ducking, call POST https://api.sonilo.com/v1/audio-ducking (POST /v1/audio-ducking) with multipart/form-data. Provide either voice_file or voice_url, and either music_file or music_url.

The submit response is 202 with a task_id. Poll GET https://api.sonilo.com/v1/tasks/{task_id} (GET /v1/tasks/{task_id}) every 2-3 seconds until the task is terminal. On success, download the mixed result from output_url.

For a raw runnable Python smoke test, fetch /examples/audio-ducking.py. It uses public voice_url and music_urlinputs, polls GET /v1/tasks/{task_id}, and writesoutput.mp3 only after a real audio download succeeds.

Use Authorization: Bearer sk_your_api_key. Treat 401 as missing or invalid auth, 403 as forbidden access, 402 or payment_required as insufficient_balance, and 429 as rate limited with Retry-After backoff.

POST/v1/audio-duckingmultipart/form-data

API URLhttps://api.sonilo.com/v1/audio-ducking

Send API requests to https://api.sonilo.com. The platform.sonilo.com/docs pages are documentation only and are not API endpoints.

curl -X POST https://api.sonilo.com/v1/audio-ducking \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "voice_file=@/path/to/voice.wav" \
  -F "music_file=@/path/to/music.mp3"
# => {"task_id": "3f9c1a2e-...", "status": "processing"}

curl https://api.sonilo.com/v1/tasks/3f9c1a2e-... \
  -H "Authorization: Bearer sk_your_api_key"
# poll until "status" is "succeeded" or "failed"

import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

submit = requests.post(
    "https://api.sonilo.com/v1/audio-ducking",
    headers=headers,
    files={
        "voice_file": open("/path/to/voice.wav", "rb"),
        "music_file": open("/path/to/music.mp3", "rb"),
    },
    timeout=300,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    poll = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    poll.raise_for_status()
    task = poll.json()
    if task["status"] != "processing":
        break
    time.sleep(3)

if task["status"] == "succeeded":
    print(task["output_url"])
else:
    print(task["error"])

import fs from "node:fs";

const headers = { Authorization: "Bearer sk_your_api_key" };

const form = new FormData();
form.append("voice_file", await fs.openAsBlob("/path/to/voice.wav"), "voice.wav");
form.append("music_file", await fs.openAsBlob("/path/to/music.mp3"), "music.mp3");

const submit = await fetch("https://api.sonilo.com/v1/audio-ducking", {
  method: "POST",
  headers,
  body: form,
});
if (!submit.ok) {
  throw new Error(`HTTP ${submit.status}: ${await submit.text()}`);
}
const { task_id } = await submit.json();

let task;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const poll = await fetch(`https://api.sonilo.com/v1/tasks/${task_id}`, { headers });
  if (!poll.ok) {
    throw new Error(`HTTP ${poll.status}: ${await poll.text()}`);
  }
  task = await poll.json();
} while (task.status === "processing");

if (task.status === "succeeded") {
  console.log(task.output_url);
} else {
  console.log(task.error);
}

curl -X POST https://api.sonilo.com/v1/audio-ducking \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "voice_url=https://example.com/talking-head.mp4" \
  -F "music_url=https://example.com/music.mp3"
# => {"task_id": "3f9c1a2e-...", "status": "processing"}

import requests

resp = requests.post(
    "https://api.sonilo.com/v1/audio-ducking",
    headers={"Authorization": "Bearer sk_your_api_key"},
    files={
        "voice_url": (None, "https://example.com/talking-head.mp4"),
        "music_url": (None, "https://example.com/music.mp3"),
    },
    timeout=300,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
# poll GET /v1/tasks/{task_id} as in the file-upload example

const form = new FormData();
form.append("voice_url", "https://example.com/talking-head.mp4");
form.append("music_url", "https://example.com/music.mp3");

const resp = await fetch("https://api.sonilo.com/v1/audio-ducking", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key" },
  body: form,
});
if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
const { task_id } = await resp.json();
// poll GET /v1/tasks/{task_id} as in the file-upload example

{
  "task_id": "3f9c1a2e-...",
  "status": "processing"
}

Authorization

Authenticate via Bearer token. Generate keys at the API Keys page and pass them in the Authorization header on every request. Keep keys server-side, for example in SONILO_API_KEY.

Authorization: Bearer sk_your_api_key

Store the key server-side, commonly as SONILO_API_KEY. A 401 means the key is missing, invalid, or revoked. A 403 means the key is valid but the account does not have access to that endpoint or workspace.

Body Parameters

voice_filefile

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_urlstring

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_filefile

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_urlstring

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.

Response

task_idstring

Unique identifier for this task — poll GET /v1/tasks/:task_id with it.

statusstring

Always processing on the 202 response.

curl -X POST https://api.sonilo.com/v1/audio-ducking \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "voice_file=@/path/to/voice.wav" \
  -F "music_file=@/path/to/music.mp3"
# => {"task_id": "3f9c1a2e-...", "status": "processing"}

curl https://api.sonilo.com/v1/tasks/3f9c1a2e-... \
  -H "Authorization: Bearer sk_your_api_key"
# poll until "status" is "succeeded" or "failed"

import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

submit = requests.post(
    "https://api.sonilo.com/v1/audio-ducking",
    headers=headers,
    files={
        "voice_file": open("/path/to/voice.wav", "rb"),
        "music_file": open("/path/to/music.mp3", "rb"),
    },
    timeout=300,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    poll = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    poll.raise_for_status()
    task = poll.json()
    if task["status"] != "processing":
        break
    time.sleep(3)

if task["status"] == "succeeded":
    print(task["output_url"])
else:
    print(task["error"])

import fs from "node:fs";

const headers = { Authorization: "Bearer sk_your_api_key" };

const form = new FormData();
form.append("voice_file", await fs.openAsBlob("/path/to/voice.wav"), "voice.wav");
form.append("music_file", await fs.openAsBlob("/path/to/music.mp3"), "music.mp3");

const submit = await fetch("https://api.sonilo.com/v1/audio-ducking", {
  method: "POST",
  headers,
  body: form,
});
if (!submit.ok) {
  throw new Error(`HTTP ${submit.status}: ${await submit.text()}`);
}
const { task_id } = await submit.json();

let task;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const poll = await fetch(`https://api.sonilo.com/v1/tasks/${task_id}`, { headers });
  if (!poll.ok) {
    throw new Error(`HTTP ${poll.status}: ${await poll.text()}`);
  }
  task = await poll.json();
} while (task.status === "processing");

if (task.status === "succeeded") {
  console.log(task.output_url);
} else {
  console.log(task.error);
}

curl -X POST https://api.sonilo.com/v1/audio-ducking \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "voice_url=https://example.com/talking-head.mp4" \
  -F "music_url=https://example.com/music.mp3"
# => {"task_id": "3f9c1a2e-...", "status": "processing"}

import requests

resp = requests.post(
    "https://api.sonilo.com/v1/audio-ducking",
    headers={"Authorization": "Bearer sk_your_api_key"},
    files={
        "voice_url": (None, "https://example.com/talking-head.mp4"),
        "music_url": (None, "https://example.com/music.mp3"),
    },
    timeout=300,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
# poll GET /v1/tasks/{task_id} as in the file-upload example

const form = new FormData();
form.append("voice_url", "https://example.com/talking-head.mp4");
form.append("music_url", "https://example.com/music.mp3");

const resp = await fetch("https://api.sonilo.com/v1/audio-ducking", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key" },
  body: form,
});
if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
const { task_id } = await resp.json();
// poll GET /v1/tasks/{task_id} as in the file-upload example

{
  "task_id": "3f9c1a2e-...",
  "status": "processing"
}