docs / endpoints / generations
GET/v1/generations/:id

Fetch a single generation by id. This is the polling endpoint: call it every few seconds after submitting until status is "complete" or "failed" — or skip polling with a webhook. Generations are scoped to your account and to the key's environment: a live key can't read sandbox generations, and vice versa.

## Example request

GET /v1/generations/:idbash
curl https://api.songapi.dev/v1/generations/gen_h2vJk8PqXw4RtY7NcAbD \
  -H "Authorization: Bearer $SONGAPI_KEY"

## Response · 200 OK

200 OK — completed generationjson
{
  "id": "gen_h2vJk8PqXw4RtY7NcAbD",
  "object": "generation",
  "env": "live",
  "type": "generate",
  "status": "complete",
  "prompt": "upbeat indie pop song about summer road trips",
  "model": "v5",
  "credits": 11,
  "clips": [
    {
      "id": "clip_9sK2mWq7RtY4NcAbD3vJ",
      "audio_url": "https://cdn.songapi.dev/gen_h2vJk8…/clip_1.mp3",
      "image_url": "https://cdn.songapi.dev/gen_h2vJk8…/clip_1.jpeg",
      "duration_secs": 167,
      "lyrics": "Windows down, radio loud…",
      "tags": "indie pop, upbeat",
      "title": "Summer Road Trips"
    },
    { … second variation … }
  ],
  "error": null,
  "duration_secs": 167,
  "audio_url": "https://cdn.songapi.dev/gen_h2vJk8…/clip_1.mp3",
  "created_at": "2026-07-22T03:47:00.000Z",
  "completed_at": "2026-07-22T03:47:41.000Z"
}

Music generations return two variations in clips; the top-level audio_url and duration_secs mirror the first clip. Failed generations have status: "failed", a human-readable error, and the credits refunded. Unknown ids return 404 not_found.

GET/v1/generations

List your generations, newest first.

## Query parameters

limitintegerResults per page, 1–100. Default: 20.
offsetintegerNumber of results to skip. Default: 0.
statusstringFilter by status: queued, processing, complete, or failed.

## Example request

GET /v1/generationsbash
curl "https://api.songapi.dev/v1/generations?limit=10&status=complete" \
  -H "Authorization: Bearer $SONGAPI_KEY"

## Response · 200 OK

200 OKjson
{
  "object": "list",
  "data": [ … generation objects … ],
  "total": 42,
  "limit": 10,
  "offset": 0
}