Suno API details
Start with one song. Use this reference when integrating additional operations.
Supported generation models
Section titled “Supported generation models”New integrations can select one of the three current models below. When the
model is omitted, execution uses chirp-hawk through the existing default alias.
model value | Suno generation family | Credits per generation | Public Voice mode |
|---|---|---|---|
chirp-hawk | v6 Pro; default | 28 | Yes, with the required account permission |
chirp-hawk-wild | v6-wild Pro | 28 | Yes, with the required account permission |
chirp-goose | v6-mini | 25 | Yes, with the required account permission |
The mini model’s free-account availability does not make OmnAPI requests free.
Existing customer discounts continue to apply. Previous generation names remain
accepted: chirp-auk-turbo runs on chirp-goose (25 credits), while chirp-v4,
chirp-auk, chirp-bluejay, chirp-crow, and chirp-fenix run on chirp-hawk
(28 credits). Underscore spellings are also accepted. Your requested model name
retains its customer-specific pricing rules and task identity; the generated
clip reports the actual V6 model. Existing feature restrictions still apply.
When model is omitted, the existing chirp-fenix pricing identity is retained
and execution uses chirp-hawk. New clients can explicitly select the V6 names.
Use the bare value above in /api/v1/suno/songs and
/api/v1/suno/clips/{clipId}/derive. The generic Task API uses a full path
such as suno/chirp-hawk/text-to-music-simple; do not send that full path in
the direct Suno model field. chirp-v3-5 is retired, and remaster-only
models are not selectable through these public operations.
Commercial Boundaries
Section titled “Commercial Boundaries”The modern Suno surface is a production, task-backed API for:
- new songs from prompts, custom lyrics, a reusable public Voice, or caller-owned audio;
- existing-clip Extend and Cover, with Concat included automatically in Extend;
- lyrics, native or managed WAV, full or named stems, aligned lyrics, audio analysis, and style recommendations;
- Voice creation from an owned completed clip or verified recordings, and public Voice reuse.
OmnAPI owns request validation, idempotent task creation, provider polling, required post-processing, retained output delivery, webhooks, and credit settlement. Model output quality and wall-clock time still depend on Suno and the validity of caller-supplied media.
Technical failures that end a paid Task as FAILED or CANCELLED follow the
shared refund rules. Subjective music quality is not an automatic refund
condition. Callers are responsible for having the rights to prompts, lyrics,
recordings, and uploaded audio.
Unlike MV, Suno operations use catalog operation prices and do not expose
quote, preflight, or maxCredits. Read GET /api/v1/pricing/catalog
before presenting a purchase and treat the create receipt’s
creditsRequired as authoritative.
The public API supports these workflows and boundaries:
| Capability | Public status | Reason |
|---|---|---|
| Cover | Public through action: "cover" | Stable source-bound contract and billing |
| Extend + Concat | Public as one action: "extend" task | The complete song is one product; a separate Concat would permit duplicate work and charging |
| Remaster / Infill / Editor actions | Unsupported | Use the documented Cover or Extend workflows when they fit the intended change |
| Video / Opus exports | Unsupported | Audio export accepts M4A, MP3, WAV, or stems; create music videos through the MV API |
| Standalone upload | Not public | Upload is exposed only inside atomic Upload + Extend/Cover workflows |
Endpoints
Section titled “Endpoints”Every endpoint below requires x-api-key. Send Content-Type: application/json on JSON requests. Idempotency-Key is optional on POST
requests and strongly recommended when a client may retry a write.
| Method | Path | Function | Description |
|---|---|---|---|
| GET | /api/v1/suno/availability | Availability | Read advisory delivery health and advanced-operation availability |
| POST | /api/v1/suno/songs | Song creation | Create from a prompt, custom lyrics, public Voice, or managed upload workflow |
| POST | /api/v1/suno/lyrics | Lyrics | Generate one or two lyrics candidates without creating a song |
| GET | /api/v1/suno/generations | Generation tracking | List the caller’s song-product history with cursor pagination |
| GET | /api/v1/suno/generations/{generationId} | Generation tracking | Read candidate states, early playable URLs, finalization, and billing |
| GET | /api/v1/suno/clips | Clip reads | Batch-read external clip IDs with ordered partial-result reporting |
| GET | /api/v1/suno/clips/{clipId} | Clip reads | Read one external clip directly without creating a Task |
| POST | /api/v1/suno/clips/{clipId}/derive | Clip derivation | Extend with automatic Concat or Cover an existing clip |
| POST | /api/v1/suno/clips/{clipId}/export | Audio export | Export retained M4A/MP3, managed WAV, or stems |
| GET | /api/v1/suno/clips/{clipId}/timeline | Music metadata | Read aligned lyric words, lines, and waveform timing |
| GET | /api/v1/suno/clips/{clipId}/audio-analysis | Music metadata | Read typed beat, key, downbeat, and waveform analysis |
| GET | /api/v1/suno/styles/recommend | Music metadata | Get style recommendations with an optional exclusion list |
| GET | /api/v1/suno/voices/verification-phrase | Voice workflow | Obtain a phrase task for recording verification |
| POST | /api/v1/suno/voices | Voice workflow | Create a reusable public Voice from verified recordings |
| POST | /api/v1/suno/voices/from-clip | Voice workflow | Create a reusable public Voice from a completed clip owned by the caller |
| GET | /api/v1/suno/voices | Voice workflow | List completed public Voices created by the caller |
| GET | /api/v1/suno/voices/{voiceId} | Voice workflow | Inspect a known public Voice that can be reused for generation |
The shared Task API completes the asynchronous workflow:
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/tasks/{taskId} | Read execution, billing, terminal error, and retained resources |
| POST | /api/v1/tasks/{taskId}/cancel | Request safe cancellation; refund eligibility depends on provider submission state |
Assets and storage
Section titled “Assets and storage”| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/suno/assets | List retained assets independently of Task history |
| GET | /api/v1/suno/assets/{id}/download | Refresh a private download URL |
| GET | /api/v1/suno/storage | Check availability, rate and subscription |
| PUT | /api/v1/suno/storage | Explicitly enable or cancel paid ordinary-audio storage |
| GET | /api/v1/suno/storage/charges | Reconcile storage charges |
Read storage and download expiry before relying on a
retention policy. Long-term enrollment depends on the live available value.
Response contracts
Section titled “Response contracts”Suno uses a small set of consistent response shapes:
| Endpoint family | Success response | How to continue |
|---|---|---|
| Song and derive writes | Generation receipt with taskId, generationId, clipIds, pollUrl, and viewUrl | Poll viewUrl for candidates; poll pollUrl for execution and billing |
| Lyrics, export, and Voice creation | Task create receipt with taskId, links, pricing, and product | Poll links.task; consume retained resources after completion |
| Generation reads | SunoGeneration or { items, nextCursor, hasMore } | Continue with the opaque cursor; never derive cursor values |
| Clip detail and batch reads | Direct SunoClip or { items, missingClipIds, errors } | No Task is created and no credits are charged |
| Timeline, analysis, styles, verification phrase, and Voice detail | Read-style Task response | 200 is ready; 202 means poll the returned pollUrl |
| Availability | Advisory health object | Respect retryAfterSec; the actual task receipt remains authoritative |
Write responses are business objects directly. Errors use the shared envelope:
{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Human-readable message", "details": {} }}Use the Interactive API Reference for the generated schema of every request and response.
IDs and polling
Section titled “IDs and polling”| ID | Meaning | Use it with |
|---|---|---|
taskId | OmnAPI execution and billing ID | /api/v1/tasks/{taskId}, cancellation, webhooks |
generationId | Suno product ID; currently equal to taskId | /api/v1/suno/generations/{generationId} |
clipId | External Suno clip ID; the legacy mid | Clip reads, Extend, Cover, WAV, Stems, MV |
Internal database row IDs are never part of the modern Suno contract.
POST /songs and POST /clips/{clipId}/derive normally wait up to 15 seconds
for Suno’s acknowledgement. The usual response arrives in about 2–4 seconds
and already contains clipIds, so clients can buffer a candidate as soon as
its audioUrl becomes available. Send Prefer: respond-async to skip this
acknowledgement wait. If the wait expires, the request still returns the same
Generation receipt rather than a gateway timeout; keep polling its viewUrl.
There is no Suno /stream endpoint. Poll the Generation, use its webhook-backed
Task, or poll the Task when execution diagnostics are needed.
Direct clip detail and batch clip reads are free 200 responses and do not
create Tasks. Timeline, analysis, style, and Voice detail reads may require a
short provider lookup; they return 200 when ready or 202 with taskId and
pollUrl when that lookup continues.