Skip to main content

​
Overview

Every Soundpiece operation follows the same pattern:
  1. Submit a request — receive an operation id and status: processing.
  2. Poll the same endpoint (or wait for a webhook) until status is ready or failed.
  3. 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_. Pass yours as a Bearer token on every request: 
Authorization: Bearer spk_<your-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. 
curl --request PUT \
  --url https://api.soundpiece.co/v1/create.new_song \
  --header 'Authorization: Bearer spk_<your-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"
  }'
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. 
curl --request GET \
  --url 'https://api.soundpiece.co/v1/create.new_song?id=op_01h7k...&wait=true' \
  --header 'Authorization: Bearer spk_<your-key>'
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...'
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.