Suno overview

Overview

Suno endpoints provide music generation, managed audio-to-song workflows, lyrics, stems, and reusable Voice workflows. Authenticate with x-api-key. Song and derive writes create both an execution Task and a customer-facing Suno Generation. Use the Generation to follow songs and candidate clips; use the Task for execution, billing, webhooks, cancellation, and diagnostics.

A successful song remains successful if its later Remix-permission update fails. That update does not fail or refund the completed creation Task.

Choose a workflow

Start with one song · Storage and downloads

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

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

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

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

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

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.

Pricing

The service pricing catalog is the source of truth. Fetch GET /api/v1/pricing/catalog and cache it according to its Cache-Control header; the create receipt’s creditsRequired is authoritative for that task. Suno uses operation prices and does not accept maxCredits. The create receipt is authoritative if pricing changes after a catalog response was cached.

Operation	Credits
Song generation with `chirp-goose`, including Upload + Extend/Cover	25
Song generation with `chirp-hawk-wild` or `chirp-hawk`	28
Song generation with a public Voice	25 with `chirp-goose`; 28 with either Pro model
Existing-clip Extend (automatic Concat included)	25 with `chirp-goose`; 28 with either Pro model
Existing-clip Cover	25 with `chirp-goose`; 28 with either Pro model
WAV managed delivery	3
Lyrics generation, including paired candidates	0
Clip detail, batch clip query, audio analysis, style recommendation, 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
Stems `twelve` / full	140
Named stem `extract` (one of 98 native Suno names)	56

suno/chirp-v3-5 is retired and cannot be selected for new requests. All three v6 models support Voice generation with the required account permission.

These are standard catalog prices. Customer pricing applies to every paid Suno operation—not only song generation—and the returned creditsRequired already contains the caller’s rate. For variable delivery such as WAV, authorization, actual settlement, and refunds all reuse the same frozen customer-pricing rule.

When you send an Idempotency-Key, reuse it only when retrying the same logical request after a transport timeout; use a new key for a new attempt. Omitting the header creates a new task on every accepted write.

Export audio

Read Suno Audio Exports and Lyrics for inputs, examples, and recovery.

Newly delivered M4A, MP3, and WAV files omit the made with suno comment while preserving customer titles, artists, artwork, and the audio encoding during comment removal. Historical cached downloads may retain that comment until separately updated; refreshing their URLs does not rewrite the files.