# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/auto_duck
# One key per job: keep it, and send the same key if you retry.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request PUT \
--url https://api.soundpiece.co/v1/adapt.auto_duck \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"idempotency_key": "$IDEMPOTENCY_KEY",
"music": {
"url": "https://example.com/audio/music.mp3"
},
"voice": {
"url": "https://example.com/audio/voiceover.mp3"
}
}
EOF# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/auto_duck
import uuid
import requests
url = "https://api.soundpiece.co/v1/adapt.auto_duck"
# One key per job: keep it, and send the same key if you retry.
idempotency_key = str(uuid.uuid4())
payload = {
"idempotency_key": idempotency_key,
"music": {
"url": "https://example.com/audio/music.mp3",
},
"voice": {
"url": "https://example.com/audio/voiceover.mp3",
},
}
headers = {"Authorization": "Bearer <token>"}
response = requests.put(url, json=payload, headers=headers, timeout=30)
print(response.json())// A complete program that also waits for the result and downloads it:
// https://docs.soundpiece.co/guides/adapt/auto_duck
import { randomUUID } from "node:crypto";
// One key per job: keep it, and send the same key if you retry.
const idempotencyKey = randomUUID();
const response = await fetch("https://api.soundpiece.co/v1/adapt.auto_duck", {
method: "PUT",
headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
body: JSON.stringify({
idempotency_key: idempotencyKey,
music: {
url: "https://example.com/audio/music.mp3",
},
voice: {
url: "https://example.com/audio/voiceover.mp3",
},
}),
});
console.log(await response.json());adapt.auto_duck (submit)
Submit an auto-duck request.
Returns immediately with status: processing. Use the matching GET to
poll for completion, or supply a callback_url to receive a webhook.
Mixes a voice over music, turning the music down while the voice speaks so
the speech stays clear. The voice is levelled, the music placed under it,
ducked while speech is detected, and the mix delivered at the requested
loudness: -14 LUFS by default, with peaks kept at or below -1 dBTP true
peak. loudness is optional, and {} asks for the defaults; it can also
name a preset, such as podcast (-16 LUFS) — see loudness.
The ready output reports the loudness measured on the delivered mix.
The output is as long as the longer of the two inputs: the shorter one is padded with silence at its end, and nothing is cut.
music and voice must be different sources, else a 422 with
same_source; two URLs recognisably serving the same file count as the
same source. Each must be fetchable, decodable audio within the supported
format, length and size limits, else a source_* error — validated once it
is fetched and decoded, with the error’s source naming the input that
failed when it is known (see errors).
Credits cost: 1 per request, normalisation included. Insufficient
credits returns 402 — see errors.
# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/auto_duck
# One key per job: keep it, and send the same key if you retry.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request PUT \
--url https://api.soundpiece.co/v1/adapt.auto_duck \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"idempotency_key": "$IDEMPOTENCY_KEY",
"music": {
"url": "https://example.com/audio/music.mp3"
},
"voice": {
"url": "https://example.com/audio/voiceover.mp3"
}
}
EOF# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/auto_duck
import uuid
import requests
url = "https://api.soundpiece.co/v1/adapt.auto_duck"
# One key per job: keep it, and send the same key if you retry.
idempotency_key = str(uuid.uuid4())
payload = {
"idempotency_key": idempotency_key,
"music": {
"url": "https://example.com/audio/music.mp3",
},
"voice": {
"url": "https://example.com/audio/voiceover.mp3",
},
}
headers = {"Authorization": "Bearer <token>"}
response = requests.put(url, json=payload, headers=headers, timeout=30)
print(response.json())// A complete program that also waits for the result and downloads it:
// https://docs.soundpiece.co/guides/adapt/auto_duck
import { randomUUID } from "node:crypto";
// One key per job: keep it, and send the same key if you retry.
const idempotencyKey = randomUUID();
const response = await fetch("https://api.soundpiece.co/v1/adapt.auto_duck", {
method: "PUT",
headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
body: JSON.stringify({
idempotency_key: idempotencyKey,
music: {
url: "https://example.com/audio/music.mp3",
},
voice: {
url: "https://example.com/audio/voiceover.mp3",
},
}),
});
console.log(await response.json());Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
A unique UUID you choose. Send the same key to retry safely; we'll return the original response without doing the work again.
"3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b"
The music to mix the voice over. It is turned down while the voice speaks. Must be a different source from voice.
Show child attributes
Show child attributes
{ "url": "https://example.com/audio/music.mp3" }
The speech to mix over the music. While it is speaking, the music is turned down so the voice stays clear.
Show child attributes
Show child attributes
{ "url": "https://example.com/audio/voiceover.mp3" }
Optional HTTPS URL we'll POST the final response to when the operation reaches ready or failed. Polling remains the canonical source of truth; webhooks are a best-effort latency optimisation.
1 - 2048"https://example.com/webhooks/soundpiece"
A target loudness to normalise audio to. Every field has a default, so
{} asks for the defaults: -14 LUFS, compression allowed.
- Target
- Preset
Show child attributes
Show child attributes
Response
Successful Response
Show child attributes
Show child attributes
