Remix an instrumental

create.remix_instrumental takes a piece of music with no vocals and makes new variations of it. On its own, the source guides the result; add a prompt to steer it toward a style or mood you describe. Use it to get fresh versions of a music bed, to vary a theme across a series, or to restyle a track you already own. For a track with vocals, use create.remix_song.

The request

Field	Required	What it is
`source`	yes	The instrumental to remix: `{"url": "https://..."}`, a public link to a WAV, MP3 or FLAC file.
`prompt`	no	The style or mood to steer toward, up to 1,024 characters, as a short phrase, e.g. `"Dreamy, melancholic synthwave, mid-tempo"`.
`n_variations`	no	How many variations to make, from 1 to 3. Defaults to 1.
`loudness`	no	Normalise every variation to a target loudness, at no extra cost. Leave it out to get them as produced. See Loudness.
`idempotency_key`	yes	A UUID that identifies this job. The reference client fills it in for you.
`callback_url`	no	An HTTPS address to receive a webhook when the work is finished.

Every field, with its exact rules: submit and poll in the API Reference.

Example

This makes three variations of an instrumental, steered toward synthwave, and saves them. It uses the reference client; save soundpiece.py or soundpiece.mjs next to it first.

import soundpiece

remix = soundpiece.run("create.remix_instrumental", {
    "source": {"url": "https://example.com/audio/instrumental.mp3"},
    "prompt": "Dreamy, melancholic synthwave, mid-tempo",
    "n_variations": 3,
})

for number, output in enumerate(remix["outputs"], start=1):
    soundpiece.download(output["url"], f"variation-{number}.flac")
    print(f"Saved variation-{number}.flac")

import { run, download } from "./soundpiece.mjs";

const remix = await run("create.remix_instrumental", {
  source: { url: "https://example.com/audio/instrumental.mp3" },
  prompt: "Dreamy, melancholic synthwave, mid-tempo",
  n_variations: 3,
});

for (const [index, output] of remix.outputs.entries()) {
  await download(output.url, `variation-${index + 1}.flac`);
  console.log(`Saved variation-${index + 1}.flac`);
}

#!/usr/bin/env bash
# Submit, wait and download by hand. Needs curl, jq and uuidgen.
set -euo pipefail
API=https://api.soundpiece.co/v1
AUTH="Authorization: Bearer $SOUNDPIECE_API_KEY"

# 1. Submit. Sending this exact body again (same idempotency_key) is safe.
body=$(jq -n --arg key "$(uuidgen)" '{
  idempotency_key: $key,
  source: { url: "https://example.com/audio/instrumental.mp3" },
  prompt: "Dreamy, melancholic synthwave, mid-tempo",
  n_variations: 3
}')
response=$(curl --silent --show-error --max-time 30 --request PUT "$API/create.remix_instrumental" \
  --header "$AUTH" --header "Content-Type: application/json" --data "$body")
result=$(jq -e .remixed_instrumental <<<"$response") || { echo "$response"; exit 1; }
id=$(jq -r .id <<<"$result")

# 2. Wait. Each call returns as soon as the work is finished, or after 20 seconds.
while [ "$(jq -r .status <<<"$result")" = processing ]; do
  response=$(curl --silent --show-error --max-time 30 "$API/create.remix_instrumental?id=$id&wait=true" \
    --header "$AUTH")
  result=$(jq -e .remixed_instrumental <<<"$response") || { echo "$response"; exit 1; }
done

# 3. Download each variation, or show what went wrong.
if [ "$(jq -r .status <<<"$result")" = failed ]; then
  jq .error <<<"$result"
  exit 1
fi
number=0
for url in $(jq -r '.outputs[].url' <<<"$result"); do
  number=$((number + 1))
  curl --silent --show-error --fail --output "variation-$number.flac" "$url"
  echo "Saved variation-$number.flac"
done

The result

run returns the finished remixed_instrumental object, with one entry in outputs per variation:

{
  "id": "op_01ks2qrw5xm28g4h0j1k3n6p9q",
  "status": "ready",
  "created_at": "2026-10-10T09:15:02Z",
  "idempotency_key": "c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e2f",
  "n_variations": 3,
  "prompt": "Dreamy, melancholic synthwave, mid-tempo",
  "outputs": [
    { "url": "https://cdn.soundpiece.co/...signed...", "expires_at": "2026-10-10T09:31:40Z", "duration": 142.7 },
    { "url": "https://cdn.soundpiece.co/...signed...", "expires_at": "2026-10-10T09:31:40Z", "duration": 151.0 },
    { "url": "https://cdn.soundpiece.co/...signed...", "expires_at": "2026-10-10T09:31:40Z", "duration": 138.4 }
  ],
  "error": null
}

Field	What it means
`n_variations`	How many variations you asked for.
`prompt`	The prompt you sent, or `null` if you didn’t send one. The source URL is never echoed.
`loudness`	Present only if you asked for normalisation (not in this example).
`outputs[].url`	A signed link to one variation, as a FLAC file (44.1 kHz). It needs no API key.
`outputs[].expires_at`	When the link stops working. Poll the operation again for a fresh one.
`outputs[].duration`	The variation’s length in seconds.
`outputs[].loudness`	Present only if you asked for normalisation: `lufs`, `true_peak_dbtp` and `compressed`, measured on that variation.

Choosing parameters

With or without a prompt? Leave prompt out for variations that stay close to the source. Add one to move them toward a style or mood. Write it as a short phrase or sentence, such as "A slow, emotional solo piano piece around 80 BPM", not a list of tags. The output is always instrumental, so directions about vocals or lyrics have no effect.
Source. Use music without vocals. For a song with vocals, use create.remix_song.
n_variations. Ask for two or three when you want to choose; each costs the same as one.
Loudness. Off unless you include the block. See the loudness normalisation guide for which target to pick.

Errors

When you submit (the request is refused, nothing is charged):

Status	`type`	Why
`422`	`string_too_short` / `string_too_long`	`prompt` is empty or over 1,024 characters. (Leave it out rather than sending an empty one.)
`422`	`missing`	`source` is missing.
`422`	`source_too_large`	The source’s server says the file is over 50 MB. (When it doesn’t say, the size is checked during processing instead.)
`422`	`idempotency_key_reused`	The key was already used for a different endpoint.
`402`	`insufficient_credits`	Your balance is below 3 credits per variation.

While processing (the operation finishes as failed, with an error.code):

Code	Why
`tos_violation`	The prompt or source was rejected by our content policy.
`source_unreachable`	The source URL couldn’t be fetched.
`source_format_unsupported`	The file isn’t WAV, MP3 or FLAC audio.
`source_too_short`	The audio is shorter than 1 second.
`source_too_long`	The audio is longer than 5 minutes.
`source_too_large`	The file is larger than 50 MB.
`internal_error`, `generation_timeout`	Something went wrong on our side. Resubmit with the same idempotency key.

Source limits for this endpoint: WAV, MP3 or FLAC, from 1 second to 5 minutes long, and at most 50 MB. See Errors for the response shapes, and for the errors every endpoint can return (401, 403, 429).

Cost

3 credits per variation, so n_variations: 3 costs 9. Normalisation costs nothing extra. Resending a request with the same idempotency key is not charged again.

Getting started

Capabilities

Core Concepts

Compliance

Changelog

The request

Example

The result

Choosing parameters

Errors

Cost

​The request

​Example

​The result

​Choosing parameters

​Errors

​Cost

The request

Example

The result

Choosing parameters

Errors

Cost