Suno API Quickstart

Use /api/v1/suno/* for new Suno-compatible music workflows. Existing Suno Cloud clients can find migration mappings in the full Suno API guide. For the complete 16-operation directory, response contracts, lifecycle, errors, and webhook behavior, start with the guide’s Endpoints section.

1. Generate a song

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

Response:

{
  "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-fenix, so it costs 28 standard credits. chirp-auk-turbo 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 buffering when a clip is playable: true and has an audioUrl; it does not need to wait for sibling candidates or the overall Task to complete. 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.

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.

4. Extend the clip

curl -X POST https://api.omnapi.com/api/v1/suno/clips/clip_123/derive \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "extend",
    "continueAt": 55,
    "prompt": "continue into a larger final chorus"
  }'

This is one 28-standard-credit task. It automatically concatenates the selected continuation; use the completed resource with role: "final". There is no separate public Concat request.

5. Export WAV

curl -X POST https://api.omnapi.com/api/v1/suno/clips/clip_123/export \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "format": "wav" }'

WAV export costs 3 standard credits and uses managed delivery automatically. Existing/native output is preferred; when direct delivery is unavailable, an eligible remixable clip is rehomed without a second customer charge. This also covers an owner account with missing subscription entitlement, an explicit insufficient-balance rejection, or an exhausted WAV allowance. OmnAPI also checks the replacement account’s live balance and rotates to another eligible account when a derivative request is definitively rejected for insufficient balance.

6. Create stems

curl -X POST https://api.omnapi.com/api/v1/suno/clips/clip_123/export \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "format": "stems", "stemsMode": "twelve" }'

Twelve returns 24 clips for one source: 12 fixed stem groups with separator variants V1 and V2. Suno’s UI may show only the eight groups it detected and calls FX “Other”; UI selectors 1 and 2 are candidates, not source clips.

To isolate one instrument, send stemsMode: "extract" with one of the 98 stemName values published in OpenAPI and the pricing catalog. For example:

curl -X POST https://api.omnapi.com/api/v1/suno/clips/clip_123/export \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "format": "stems", "stemsMode": "extract", "stemName": "Drum Kit" }'

This is native Suno separation. There is no reliable instrument-presence preflight; a missing instrument can produce a near-silent stem and the accepted 56-credit request is still billed.

7. Upload audio and continue it

Standalone Upload is not exposed. Submit customer-owned audio together with the song operation:

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "upload-extend",
    "audio": {
      "url": "https://example.com/source.wav",
      "extensionType": "wav"
    },
    "prompt": "continue into a larger final chorus"
  }'

Common prices

Operation	Credits
Song generation with chirp-auk-turbo	25
Song generation with another published model, including Upload + Extend/Cover	28
Existing-clip Extend or Cover	28
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.