Quickstart

Overview

Every Soundpiece operation follows the same pattern:

Submit a request — receive an operation id and status: processing.
Poll the same endpoint (or wait for a webhook) until status is ready or failed.
Download the audio using the signed URL in the response.

This guide walks through a complete example: generating a song from lyrics and a prompt.

Step 1: Get your API key

API keys are issued from your account dashboard. Each key comes paired with a webhook signing secret. Both are shown once at creation — save them somewhere safe. Keys start with the prefix spk_ — the prefix is part of the key, so use the value exactly as the dashboard shows it. Pass yours as a Bearer token on every request:

Authorization: Bearer <your-api-key>

Anyone with your key can use your account. Never embed it in client-side or mobile application code. If a key is exposed, revoke it from the dashboard and create a new one.

Step 2: Submit a song generation request

Pass an idempotency_key (a UUID you choose) so you can safely retry the request over an unreliable network.

status=$(curl --silent --output response.json --write-out '%{http_code}' \
  --request PUT \
  --url https://api.soundpiece.co/v1/create.new_song \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "lyrics": "I've been driving all night, my hands wet on the wheel",
    "prompt": "Synthwave, melancholic, mid-tempo"
  }')

if [ "$status" -ne 200 ]; then
  echo "Error (HTTP $status):"
else
  echo "Success:"
fi
jq . response.json

import json
import uuid
import requests

response = requests.put(
    "https://api.soundpiece.co/v1/create.new_song",
    headers={"Authorization": "Bearer <your-api-key>"},
    json={
        "idempotency_key": str(uuid.uuid4()),
        "lyrics": "I've been driving all night, my hands wet on the wheel",
        "prompt": "Synthwave, melancholic, mid-tempo",
    },
)

body = response.json()
if response.status_code != 200:
    print(f"Error (HTTP {response.status_code}):")
    print(json.dumps(body, indent=2))
else:
    print("Success:")
    print(json.dumps(body, indent=2))
    song = body["song"]
    # ...continue to Step 3 with song["id"]

import { randomUUID } from "node:crypto";

const response = await fetch("https://api.soundpiece.co/v1/create.new_song", {
  method: "PUT",
  headers: {
    Authorization: "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    idempotency_key: randomUUID(),
    lyrics: "I've been driving all night, my hands wet on the wheel",
    prompt: "Synthwave, melancholic, mid-tempo",
  }),
});

const body = await response.json();
if (!response.ok) {
  console.error(`Error (HTTP ${response.status}):`);
  console.error(JSON.stringify(body, null, 2));
} else {
  console.log("Success:");
  console.log(JSON.stringify(body, null, 2));
  const { song } = body;
  // ...continue to Step 3 with song.id
}

Response

{
  "song": {
    "id": "op_01h7k...",
    "status": "processing",
    "created_at": "2026-05-20T12:34:56Z",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "lyrics": "I've been driving all night, my hands wet on the wheel",
    "prompt": "Synthwave, melancholic, mid-tempo",
    "reference": null,
    "outputs": null,
    "error": null
  }
}

The id (operation id) is the handle you’ll use to fetch the result. Notice that the request you sent is echoed back on the response — useful for keeping the request and its outcome together without your own bookkeeping.

Step 3: Poll until the operation is ready

Call the same endpoint with GET and the operation id. Pass ?wait=true to long-poll for up to 20 seconds — the server returns as soon as the operation reaches ready or failed, or after 20 seconds if it is still running. Repeat until you get a terminal status.

status=$(curl --silent --output response.json --write-out '%{http_code}' \
  --request GET \
  --url 'https://api.soundpiece.co/v1/create.new_song?id=op_01h7k...&wait=true' \
  --header 'Authorization: Bearer <your-api-key>')

if [ "$status" -ne 200 ]; then
  echo "Error (HTTP $status):"
else
  echo "Success:"
fi
jq . response.json

import time

def wait_for_song(operation_id, api_key, timeout=300):
    start = time.time()
    while time.time() - start < timeout:
        response = requests.get(
            "https://api.soundpiece.co/v1/create.new_song",
            headers={"Authorization": f"Bearer {api_key}"},
            params={"id": operation_id, "wait": "true"},
        )
        if response.status_code != 200:
            print(f"Error (HTTP {response.status_code}):")
            print(json.dumps(response.json(), indent=2))
            return None
        song = response.json()["song"]
        if song["status"] in ("ready", "failed"):
            return song
    raise TimeoutError("Operation did not complete in time")

result = wait_for_song(song["id"], "<your-api-key>")
if result is not None:
    print("Success:" if result["status"] == "ready" else "Error:")
    print(json.dumps(result, indent=2))

async function waitForSong(operationId, apiKey, timeoutMs = 300000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const res = await fetch(
      `https://api.soundpiece.co/v1/create.new_song?id=${operationId}&wait=true`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    if (!res.ok) {
      console.error(`Error (HTTP ${res.status}):`);
      console.error(JSON.stringify(await res.json(), null, 2));
      return null;
    }
    const { song } = await res.json();
    if (song.status === "ready" || song.status === "failed") return song;
  }
  throw new Error("Operation timed out");
}

const result = await waitForSong(song.id, "<your-api-key>");
if (result !== null) {
  console.log(result.status === "ready" ? "Success:" : "Error:");
  console.log(JSON.stringify(result, null, 2));
}

Response when ready

{
  "song": {
    "id": "op_01h7k...",
    "status": "ready",
    "created_at": "2026-05-20T12:34:56Z",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "lyrics": "I've been driving all night, my hands wet on the wheel",
    "prompt": "Synthwave, melancholic, mid-tempo",
    "reference": null,
    "outputs": [
      {
        "url": "https://cdn.soundpiece.co/...signed...",
        "expires_at": "2026-05-20T12:50:21Z",
        "duration": 87.4
      },
      {
        "url": "https://cdn.soundpiece.co/...signed...",
        "expires_at": "2026-05-20T12:50:21Z",
        "duration": 91.2
      }
    ],
    "error": null
  }
}

Song generation typically produces multiple variations — each appears as a separate entry in outputs.

For production workloads, use webhooks so you don’t have to poll. Supply a callback_url on the original PUT and we’ll post the same response to that URL when the operation terminates. Polling remains the canonical source of truth — see Async operations.

Step 4: Download the audio

Each output carries a signed URL you can GET to download the audio as a FLAC file (44.1 kHz). The URL is time-limited; check the expires_at field. If it has expired, call the GET endpoint again — we’ll generate a fresh URL.

curl --output song.flac \
  'https://cdn.soundpiece.co/...signed...'

with requests.get(result["outputs"][0]["url"], stream=True) as r:
    r.raise_for_status()
    with open("song.flac", "wb") as f:
        for chunk in r.iter_content(chunk_size=64 * 1024):
            f.write(chunk)
print("Saved to song.flac")

import fs from "node:fs";

const audio = await fetch(result.outputs[0].url);
const buffer = await audio.arrayBuffer();
fs.writeFileSync("song.flac", Buffer.from(buffer));
console.log("Saved to song.flac");

No auth header is needed on the download — the signed URL is self-authenticating until it expires.

That’s it. The same pattern applies to every endpoint:

PUT /v1/create.new_song — generate a song from lyrics + prompt or reference.
PUT /v1/create.new_instrumental — generate an instrumental from a prompt or reference.
PUT /v1/create.new_sample — generate a short sample at a target duration.
PUT /v1/create.new_fx — generate a one-shot effect.
PUT /v1/create.remix_song — remix an existing song (with vocals/lyrics) into new song variations, guided by lyrics and prompt.
PUT /v1/create.remix_instrumental — remix an existing instrumental track into new instrumental variations.
PUT /v1/adapt.separate_stems — separate a track into vocals, drums, bass, other.
PUT /v1/adapt.auto_cut_down — trim a track to a target duration at musically natural cut points.

See the API Reference for the full surface, or read on for authentication, async operations, webhooks, errors, rate limits, and versioning.

Getting started

Core Concepts

Compliance

Overview

Step 1: Get your API key

Step 2: Submit a song generation request

Step 3: Poll until the operation is ready

Step 4: Download the audio

​Overview

​Step 1: Get your API key

​Step 2: Submit a song generation request

​Step 3: Poll until the operation is ready

​Step 4: Download the audio

Overview

Step 1: Get your API key

Step 2: Submit a song generation request

Step 3: Poll until the operation is ready

Step 4: Download the audio