Suno Audio Exports and Lyrics

Export audio

Call POST /api/v1/suno/clips/{clipId}/export to turn one completed source clip into M4A, MP3, WAV, or retained separated tracks. The body is a discriminated union: select one format and send only the fields accepted by that variant.

Every export returns a Task receipt. Poll GET /api/v1/tasks/{taskId}, consume the returned audio resource URL, and retain the same Idempotency-Key when retrying one logical request.

M4A

Explicit M4A export costs 1 standard credit before customer pricing. New Suno song-creation Tasks already include their managed M4A delivery without a second export charge.

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/clips/clip_123/export \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "m4a" }'

MP3

MP3 export costs 2 standard credits before customer pricing. OmnAPI derives the MP3 from the managed M4A asset and returns a playable MP3 resource; clients should not reconstruct or depend on Suno’s historical direct MP3 URLs.

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

WAV

WAV export delivers the requested original clip and costs 3 standard credits before customer pricing. Use returned URLs and retention fields; see Asset storage.

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

Stems

Field	Type	Required	Notes
`format`	`"m4a"` \| `"mp3"` \| `"wav"` \| `"stems"`	yes	Selects exactly one audio export variant.
`stemsMode`	`"twelve"` \| `"extract"`	—	Default `twelve`.
`stemName`	enum	for `extract`	Exactly one of the 98 names below. Do not send it with M4A, MP3, WAV, or `twelve`.
`config`	object	—	Standard task config: `priority`, `tags`, `metadata`, `webhookUrl`.

`stemsMode`	Output	Credits
`twelve`	Full separated-track set; default	140
`extract`	Isolate/remove one named stem; requires one of the 98 allowed `stemName` values	56

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

Named Extract uses Suno’s native separator; OmnAPI does not regenerate the song or send it to another AI service. 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: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "stems", "stemsMode": "extract", "stemName": "Drum Kit" }'

Use the exact spelling of a published stem name, such as Lead Vocal, Drum Kit, or Acoustic Guitar.

Browse all 98 accepted stem names

Filter stem names

98 names

Values are case- and spacing-sensitive. Send one name exactly as shown; the API rejects aliases, translated labels, and names outside this list.

For Twelve, a complete API response currently contains 24 clips from the same source: 12 fixed groups (Vocals, Backing Vocals, Drums, Bass, Guitar, Keyboard, Percussion, Strings, Synth, FX, Brass, and Woodwinds), each with separator candidates V1 and V2. Suno’s UI can show only the eight groups detected for a particular song; it labels Vocals as Lead Vocal and FX as Other. The UI buttons 1 and 2 select the two separator candidates, not two source clips.

Stem task results expose sourceClipId, stemsMode, stemGroup, displayName, batchIndex, and variant where available, so integrations do not need to infer these semantics from array position or title. Extract results also expose stemName and extractRole (target or without-target). Named Extract may return a near-silent target when the requested instrument is not meaningfully present. Suno provides no reliable preflight presence signal, so an accepted Extract request is still charged.

The service manages delivery and retention automatically. Repeating an identical completed request may reuse retained assets, but the public operation price remains unchanged. The former two mode is not accepted. When native delivery is unavailable and the source supports it, OmnAPI may use managed compatibility processing. The caller never selects or reconciles delivery infrastructure.

If you supplied an Idempotency-Key, reuse it when retrying the same logical request so a transport retry does not create or charge a second task.

Export response

Export returns a Task create receipt rather than a Generation receipt:

{
  "taskId": "task_export_01J...",
  "status": "PENDING",
  "creditsRequired": 3,
  "estimatedCompletionTime": "2026-07-30T12:04:00.000Z",
  "requestId": "req_01J...",
  "links": {
    "task": "/api/v1/tasks/task_export_01J...",
    "resource": null,
    "final": null
  },
  "pricing": {
    "baseCredits": 3,
    "calculatedCredits": 3,
    "chargedCredits": 3,
    "adjustmentCredits": 0,
    "settlementRoundingCredits": 0,
    "settlementPolicyVersion": "whole-credit-v1",
    "billingIncrementCredits": 1,
    "source": "standard",
    "quoteVersion": 2
  },
  "product": {
    "type": "suno",
    "providerCode": "suno",
    "modelCode": "chirp-hawk",
    "featureCode": "get-wav",
    "resourceId": null
  },
  "warningCodes": []
}

Poll links.task. A completed export Task returns retained resources with url, contentType, assetStatus, urlExpiresAt, and retainedUntil when available. creditsCharged reflects final WAV settlement; do not assume the authorized maximum was ultimately charged. For historical resources, null expiry fields do not establish a new retention guarantee. Copy business-critical output and follow the returned asset policy; see Storage and download expiry.

Generate lyrics

Call POST /api/v1/suno/lyrics when you need lyrics without starting song generation. Set candidates: 2 for two independently generated candidates in one Task. A paired Task succeeds only after two distinct candidates, A and B, both complete. One delivered candidate is not reported as a successful pair. The operation returns a Task receipt; poll GET /api/v1/tasks/{taskId} for the result.

Field	Type	Notes
`prompt`	string, max 3,000	Required subject, story, mood, or structural direction
`candidates`	integer literal `1` or `2`	Omit or send `1` for one result; `2` requests paired candidates for the same operation price. Strings and `0` are invalid.
`lyricsModel`	string, max 100	Single-candidate requests use the stable default workflow; when `candidates` is `2`, the only accepted value is `default`
`source`	string, max 100	With `candidates: 2`, an optional caller label retained with the Task for audit; it is not a model selector
`config`	object	Priority, webhook URL, tags, and metadata

curl -X POST https://api.omnapi.com/api/v1/suno/lyrics \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "bittersweet indie pop about moving away", "candidates": 2 }'

The immediate response is the same Task create receipt shape used by export. After completion, read the generated text from the Task’s outputResults and standardized text resources. Paired candidates remain part of one Task, one billing decision, and one idempotency scope. The two resources preserve their A/B order.

Each completed text resource can also contain metadata.stylePrompt. For compatibility, the same complete style prompt is returned as the single item in metadata.tags; it is not split on commas. Style expansion is best-effort. If it is temporarily unavailable, the lyrics Task still succeeds, those optional fields are omitted, and outputResults.warnings can include SUNO_STYLE_UPSAMPLE_UNAVAILABLE.

{
  "type": "TEXT",
  "index": 0,
  "id": "lyrics_a",
  "content": "[Verse 1]\n...",
  "metadata": {
    "stylePrompt": "Intimate indie folk built around fingerpicked acoustic guitar...",
    "tags": [
      "Intimate indie folk built around fingerpicked acoustic guitar..."
    ]
  }
}

If either candidate is not delivered, the Task fails atomically, is refunded, and exposes SUNO_LYRICS_PAIR_TEMPORARILY_UNAVAILABLE with retryable: true. Retry later as a new request. Idempotency-Key remains optional; when the failed request supplied one, use a new value for that new attempt.