Suno API Quickstart

Quickstart

Create one song and follow its playable candidates. Use an API key with task:create and task:read, and check your balance before submitting. The Task tracks execution and billing; the Generation tracks song candidates.

1. Generate a song

For each new logical operation, set and save a fresh REQUEST_KEY once. Reuse it with the exact same route and body only when recovering that operation. Use a different saved key when trying a different example or export format.

export REQUEST_KEY="$(uuidgen)"

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "simple",
    "prompt": "upbeat city pop, bright guitars, summer night drive",
    "model": "chirp-hawk",
    "config": {
      "metadata": { "source": "suno-quickstart" }
    }
  }'

Response example (excerpt):

{
  "taskId": "task_01J...",
  "generationId": "task_01J...",
  "status": "PROCESSING",
  "clipIds": [
    "clip_a",
    "clip_b"
  ],
  "deliveryStatus": "submitted",
  "pollUrl": "/api/v1/tasks/task_01J...",
  "viewUrl": "/api/v1/suno/generations/task_01J...",
  "creditsRequired": 28
}

This example explicitly selects chirp-hawk, so it costs 28 standard credits. chirp-goose costs 25; other published models remain 28. suno/chirp-v3-5 is retired. Always treat the task receipt as authoritative.

The endpoint normally waits briefly for Suno to acknowledge real clipIds. Send Prefer: respond-async when even that short wait is undesirable. The receipt never contains a Suno /stream link.

2. Poll the Generation

curl https://api.omnapi.com/api/v1/suno/generations/task_01J... \
  -H "x-api-key: $OMNAPI_KEY"

Each entry in clips[] has an independent submitted | queued | streaming | complete | error state. Start playback when a clip is playable: true and has a non-null playback.url; it does not need to wait for sibling candidates or the overall Task to complete. audioUrl can remain null during live playback, so do not use it as the readiness check. Use GET /api/v1/tasks/{taskId} separately for billing and execution diagnostics. For model identity, use modelCode for the OmnAPI request model, providerModelName for the exact clip model name, and majorModelVersion for the exact major version reported for that clip. model remains a compatibility label.

No SSE subscription or separate playback-session request is required. Poll the Generation every few seconds, respecting playback.retryAfterMs and request limits. Resolve a relative playback.url against https://api.omnapi.com, then open that URL in a browser or use it as an <audio src> without an API key. Live URLs are temporary; query the Generation again after playback.expiresAt or a playback error. Keep your API key on your server.

playback.state: "live" is non-seekable audio while generation continues; "final" is the completed, seekable audio. Do not replace an actively playing source on every poll. See the browser example and recovery guidance.

3. Read the clip

curl "https://api.omnapi.com/api/v1/suno/clips/clip_123" \
  -H "x-api-key: $OMNAPI_KEY"

Clip detail is a free direct 200 lookup and creates no Task. For multiple external Suno clip IDs, use GET /api/v1/suno/clips?clipIds=clip_a,clip_b; these values are legacy mid values, never internal OmnAPI row IDs. Owned clips expose style tags and prompts. Shared public or remixable clips expose style tags but keep prompts private; merely readable external clips return only minimal media fields. Missing tags or duration are repaired on later Clip and Generation reads when the metadata becomes available.

Common prices

Operation	Credits
Song generation with `chirp-goose`	25
Song generation with another published model, including Upload + Extend/Cover	28
Existing-clip Extend or Cover	25 with `chirp-goose`; 28 with either Pro model
WAV native / managed fallback	3
Lyrics generation	0
Clip, analysis, style, and Voice reads	0
Aligned lyrics timeline	1; 0 for the legacy Suno 55,000 plan
Owned completed clip → reusable public Voice	5
Verified recordings → reusable public Voice	66
Twelve-stem export	140
Named stem extract (98 native Suno names)	56

See Suno API endpoints for the complete route directory, then use the Interactive API Reference for exact generated schemas.

Continue the integration

Use the Python and TypeScript examples for persisted requests and resumable task polling. Browse the endpoint directory for the full public surface.