Quickstart

Every Soundpiece request follows the same three steps:

Submit the request. You get back an operation id and status: "processing".
Wait until status is ready or failed, by polling the same endpoint (or by receiving a webhook).
Download the audio from the signed URL in the result.

This guide generates a song from lyrics and a prompt, using the reference client to do the waiting and retrying for you.

Step 1: Get your API key

API keys are issued from your account dashboard, under Developer → API keys. A key is shown once, when you create it, so save it somewhere safe. Keys start with spk_; the prefix is part of the key. Put the key in an environment variable, so it never appears in your code:

export SOUNDPIECE_API_KEY="spk_..."

Anyone with your key can use your account. Never put it in code that runs in a browser or a mobile app. If a key is exposed, revoke it from the dashboard and create a new one. See Authentication.

Step 2: Save the reference client

Copy the file for your language from The reference client into a new folder:

Python: save it as soundpiece.py, then run pip install requests.
JavaScript: save it as soundpiece.mjs. It needs Node.js 18 or later and nothing else.

Step 3: Generate a song

Save this program next to the client and run it. Generating a song usually takes a minute or two.

import soundpiece

song = soundpiece.run("create.new_song", {
    "lyrics": "[Verse]\nDriving all night with the radio on\n\n[Chorus]\nCity lights, carry me home",
    "prompt": "synthwave, melancholic, mid-tempo",
})

soundpiece.download(song["outputs"][0]["url"], "song.flac")
print("Saved song.flac")

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

const song = await run("create.new_song", {
  lyrics: "[Verse]\nDriving all night with the radio on\n\n[Chorus]\nCity lights, carry me home",
  prompt: "synthwave, melancholic, mid-tempo",
});

await download(song.outputs[0].url, "song.flac");
console.log("Saved song.flac");

#!/usr/bin/env bash
# The same three steps 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:
#    it returns the same operation instead of starting new work.
body=$(jq -n --arg key "$(uuidgen)" '{
  idempotency_key: $key,
  lyrics: "[Verse]\nDriving all night with the radio on\n\n[Chorus]\nCity lights, carry me home",
  prompt: "synthwave, melancholic, mid-tempo"
}')
response=$(curl --silent --show-error --max-time 30 --request PUT "$API/create.new_song" \
  --header "$AUTH" --header "Content-Type: application/json" --data "$body")
song=$(jq -e .song <<<"$response") || { echo "$response"; exit 1; }
id=$(jq -r .id <<<"$song")

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

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

run returns the finished song object. It looks like this:

{
  "id": "op_01ks2p3hc0etfb59tdwh9edd1r",
  "status": "ready",
  "created_at": "2026-05-20T12:34:56Z",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "lyrics": "[Verse]\nDriving all night with the radio on\n\n[Chorus]\nCity lights, carry me home",
  "prompt": "synthwave, melancholic, mid-tempo",
  "n_variations": 1,
  "outputs": [
    {
      "url": "https://cdn.soundpiece.co/...signed...",
      "expires_at": "2026-05-20T12:50:21Z",
      "duration": 87.4
    }
  ],
  "error": null
}

id identifies the operation. You can poll it again later with GET /v1/create.new_song?id=....
idempotency_key is the key the client sent with your request. Sending the same key again returns this same operation instead of starting new work; see keeping a key across re-runs.
outputs has one entry per variation. Set n_variations (1 to 3) in the request for more.
url is a signed download link for a FLAC file (44.1 kHz). It needs no API key, and stops working at expires_at. Poll the operation again for a fresh one.

If the song can’t be made, run raises a SoundpieceError carrying the result’s error.code and error.message; see Errors.

Next steps

The same pattern works for every endpoint. Swap the endpoint name and the request body:

Endpoint	What it does
`create.new_song`	Generate a song from lyrics plus a prompt or a reference track.
`create.new_instrumental`	Generate an instrumental from a prompt or a reference track.
`create.new_sample`	Generate a short sample at a target duration, optionally loopable.
`create.new_fx`	Generate a one-shot sound effect.
`create.remix_song`	Remix a song with vocals into new variations, guided by new lyrics and a prompt.
`create.remix_instrumental`	Remix an instrumental into new variations.
`adapt.separate_stems`	Separate a track into vocals, drums, bass, other and instrumental.
`adapt.auto_cut_down`	Trim a track to a target duration at musically natural cut points.
`adapt.normalise_loudness`	Normalise a track to a target loudness.
`adapt.auto_duck`	Mix a voice over music, turning the music down while the voice speaks.

Each endpoint has a guide with a complete example, its result, its errors and its cost; follow the links in the table. The exact fields are in the API Reference, e.g. create.new_song (submit). Before you go to production, work through the production checklist.

Getting started

Capabilities

Core Concepts

Compliance

Changelog

Step 1: Get your API key

Step 2: Save the reference client

Step 3: Generate a song

Next steps

​Step 1: Get your API key

​Step 2: Save the reference client

​Step 3: Generate a song

​Next steps

Step 1: Get your API key

Step 2: Save the reference client

Step 3: Generate a song

Next steps