cURL

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

# 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/create.remix_song \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "idempotency_key": "$IDEMPOTENCY_KEY",
  "source": {
    "url": "https://example.com/audio/song.mp3"
  },
  "lyrics": "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
  "prompt": "synthwave, melancholic, mid-tempo"
}
EOF

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

import uuid

import requests

url = "https://api.soundpiece.co/v1/create.remix_song"

# 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",
    },
    "lyrics": "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
    "prompt": "synthwave, melancholic, mid-tempo",
}
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/create/remix_song

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/create.remix_song", {
  method: "PUT",
  headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
  body: JSON.stringify({
    idempotency_key: idempotencyKey,
    source: {
      url: "https://example.com/audio/song.mp3",
    },
    lyrics: "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
    prompt: "synthwave, melancholic, mid-tempo",
  }),
});

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

{
  "remixed_song": {
    "id": "op_01m3vcs7e0f8rsq32d5sqhmetw",
    "status": "processing",
    "created_at": "2026-10-01T09:30:00Z",
    "idempotency_key": "3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b",
    "lyrics": "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
    "prompt": "acoustic folk, warm, female vocal",
    "n_variations": 2,
    "loudness": {
      "target_lufs": -14,
      "allow_compression": true
    },
    "outputs": null,
    "error": null
  }
}

Create

create.remix_song (submit)

Submit a song remix request.

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

Takes an existing song with vocals/lyrics and produces new song variations of it, guided by the lyrics and prompt you supply. For remixing an instrumental track (no vocals), use create.remix_instrumental instead: a source with no recognisable vocals fails the operation with source_has_no_vocals. Set n_variations (1-3) for how many variations to produce — each appears as a separate entry in outputs when the operation is ready.

Add the optional loudness block to have every variation normalised to a target integrated loudness, given in LUFS or as a named preset (streaming, podcast or broadcast), at no extra cost — see loudness.

Credits cost: 3 per variation (so n_variations: 2 costs 6). Insufficient credits returns 402 — see errors.

PUT

create.remix_song

cURL

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

# 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/create.remix_song \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "idempotency_key": "$IDEMPOTENCY_KEY",
  "source": {
    "url": "https://example.com/audio/song.mp3"
  },
  "lyrics": "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
  "prompt": "synthwave, melancholic, mid-tempo"
}
EOF

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

import uuid

import requests

url = "https://api.soundpiece.co/v1/create.remix_song"

# 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",
    },
    "lyrics": "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
    "prompt": "synthwave, melancholic, mid-tempo",
}
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/create/remix_song

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/create.remix_song", {
  method: "PUT",
  headers: {Authorization: "Bearer <token>", "Content-Type": "application/json"},
  body: JSON.stringify({
    idempotency_key: idempotencyKey,
    source: {
      url: "https://example.com/audio/song.mp3",
    },
    lyrics: "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
    prompt: "synthwave, melancholic, mid-tempo",
  }),
});

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

{
  "remixed_song": {
    "id": "op_01m3vcs7e0f8rsq32d5sqhmetw",
    "status": "processing",
    "created_at": "2026-10-01T09:30:00Z",
    "idempotency_key": "3f2b8c1e-9d4a-4e7b-b6c5-1a2d3e4f5a6b",
    "lyrics": "[Verse]\nI've been driving all night, my hands wet on the wheel\n\n[Chorus]\nNeon in the mirror, and the road is all I feel",
    "prompt": "acoustic folk, warm, female vocal",
    "n_variations": 2,
    "loudness": {
      "target_lufs": -14,
      "allow_compression": true
    },
    "outputs": 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 song (with vocals) to remix. The audio must be a WAV, MP3, or FLAC file between 10 seconds and 5 minutes long, and at most 50 MB.

Show child attributes

lyrics

string

required

Song lyrics. Use [Verse], [Chorus], [Bridge], [Intro], [Outro], [Instrumental] section markers on their own line to structure the song. Each subsequent line within a section is a separate vocal line.

Example:

[Verse]
This is a demo song, don't get too excited
Wrote it in me lounge while slightly half-sighted

[Chorus]
It's only a demo, keep your hopes low
Recorded it once, then decided "that'll go"

Required string length: 1 - 3000

prompt

string

required

Free-text description of the audio to generate. Mix tags, a description of the desired mood and instrumentation, and a scene — use commas to separate tags. Examples: rock song, energetic, male vocal (song), synthwave, melancholic, mid-tempo (instrumental), rock, guitar, energetic, no drums (sample), someone typing on a keyboard (effect).

Required string length: 1 - 1024

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"

n_variations

integer

default:1

How many output variations to produce (1-3).

Required range: 1 <= x <= 3

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

remixed_song

RemixedSong · object

required

Show child attributes