cURL

# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/normalise_loudness

# 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.normalise_loudness \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "idempotency_key": "$IDEMPOTENCY_KEY",
  "source": {
    "url": "https://example.com/audio/song.mp3"
  }
}
EOF

# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/normalise_loudness

import uuid

import requests

url = "https://api.soundpiece.co/v1/adapt.normalise_loudness"

# One key per job: keep it, and send the same key if you retry.
idempotency_key = str(uuid.uuid4())

payload = {
    "idempotency_key": idempotency_key,
    "source": {
        "url": "https://example.com/audio/song.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/normalise_loudness

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.normalise_loudness", {
  method: "PUT",
  headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
  body: JSON.stringify({
    idempotency_key: idempotencyKey,
    source: {
      url: "https://example.com/audio/song.mp3",
    },
  }),
});

console.log(await response.json());

{
  "normalised_audio": {
    "id": "op_01m3vcs7e0f8rsq32d5sqhmetw",
    "status": "processing",
    "created_at": "2026-10-01T09:30:00Z",
    "idempotency_key": "3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b",
    "loudness": {
      "target_lufs": -14,
      "allow_compression": true
    },
    "output": null,
    "error": null
  }
}

Adapt

adapt.normalise_loudness (submit)

Submit a loudness normalisation request.

Returns immediately with status: processing. Use the matching GET to poll for completion, or supply a callback_url to receive a webhook.

Normalises an audio track to a target integrated loudness (LUFS, as defined by EBU R128), keeping its true peak at or below -1 dBTP. The target defaults to -14 LUFS, the level most streaming services play music back at; loudness is optional, and {} asks for the defaults. Instead of a number, loudness can name a preset for a common destination: streaming (-14 LUFS), podcast (-16 LUFS) or broadcast (-23 LUFS, EBU R128). A preset’s value is fixed and never changes. The -1 dBTP ceiling is fixed.

Audio whose peaks are loud relative to its average level may not be able to reach the target by a change of level alone without breaking the ceiling. allow_compression decides what happens then: compress the dynamics to land close to the target (the default), or keep the dynamics and stop short of it. Either way the ready output reports the loudness and true peak measured on the delivered audio, and whether its dynamics were altered.

The source must be fetchable, decodable audio within the supported format, length and size limits, else a source_* error — validated once the source is fetched and decoded (see errors).

Credits cost: 1 per request. Insufficient credits returns 402 — see errors.

PUT

adapt.normalise_loudness

cURL

# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/normalise_loudness

# 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.normalise_loudness \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "idempotency_key": "$IDEMPOTENCY_KEY",
  "source": {
    "url": "https://example.com/audio/song.mp3"
  }
}
EOF

# A complete program that also waits for the result and downloads it:
# https://docs.soundpiece.co/guides/adapt/normalise_loudness

import uuid

import requests

url = "https://api.soundpiece.co/v1/adapt.normalise_loudness"

# One key per job: keep it, and send the same key if you retry.
idempotency_key = str(uuid.uuid4())

payload = {
    "idempotency_key": idempotency_key,
    "source": {
        "url": "https://example.com/audio/song.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/normalise_loudness

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.normalise_loudness", {
  method: "PUT",
  headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
  body: JSON.stringify({
    idempotency_key: idempotencyKey,
    source: {
      url: "https://example.com/audio/song.mp3",
    },
  }),
});

console.log(await response.json());

{
  "normalised_audio": {
    "id": "op_01m3vcs7e0f8rsq32d5sqhmetw",
    "status": "processing",
    "created_at": "2026-10-01T09:30:00Z",
    "idempotency_key": "3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b",
    "loudness": {
      "target_lufs": -14,
      "allow_compression": true
    },
    "output": null,
    "error": null
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

idempotency_key

string<uuid>

required

A unique UUID you choose. Send the same key to retry safely; we'll return the original response without doing the work again.

Example:

"3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b"

source

AudioSource · object

required

The audio source to operate on.

Show child attributes

callback_url

string<uri> | null

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.

Required string length: 1 - 2048

Example:

"https://example.com/webhooks/soundpiece"

loudness

Target · object

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

Response

Successful Response

normalised_audio

NormalisedAudio · object

required

Show child attributes