Suno API for AI Music Generation

Suno endpoints provide direct music generation, remixing, export, lyrics, upload, and persona workflows. They follow the standard task model: authenticate with x-api-key, create a task with a POST /api/v1/suno/* endpoint, and poll GET /api/v1/tasks/{taskId} until terminal. The shared request config (priority / tags / metadata / webhookUrl), the status enum, and the resources[] output shape live in the hub — this page covers only Suno-specific inputs and outputs.

The model field on generation and derive endpoints accepts a Suno model identifier such as chirp-fenix, chirp-bluejay, or chirp-v4-5. Default when omitted: chirp-fenix.

Note

Use /api/v1/suno/* for new integrations. Existing Suno Cloud clients can use the migration map while moving to the current task model.

---

Read-style endpoints

Read-style Suno endpoints such as clip detail and timeline use the same task system but wait briefly for a result inline. If they don’t finish in that window they return 202 with the taskId (and pollUrl) — poll it like any other task. (See the task model for the sync/202 contract.)

Pricing

One paid Suno song-generation or derive request is 28 credits. Read-only operations are free unless the request creates, stores, or packages a new asset.

Operation	Credits
Song generation, derive, cover, extend, sample, mashup, persona song	28
Lyrics generation	0
Clip detail, batch clip query, timeline, style recommendation, persona reads	0
Upload audio, WAV export, local concat, persona creation	5
MP4 visualizer export	10
Stems two / basic	28
Stems twelve / full	140

---

POST /api/v1/suno/songs

Create a new song. Dispatch is controlled by mode.

Mode	Purpose	Required fields
simple	Prompt-only generation	prompt
custom	Lyrics + style generation	lyrics or prompt
mashup	Blend source clips	seed.clipIds with 2-4 clips
sample	Condition on a clip region	seed.sampleClipId, seed.sampleStartS, seed.sampleEndS
inspo	Generate from reference playlist clips	seed.playlistClipIds; prompt for simple inspo

If personaId is present, the request routes to persona music regardless of mode.

Optional advanced fields

Field	Type	Notes
controlSliders.style_weight	number 0–1	How strongly the style hint biases the model. Higher = stricter adherence to tags / style.
controlSliders.audio_weight	number 0–1	For sample/mashup modes — how strongly the model conditions on the seed audio.
controlSliders.weirdness_constraint	number 0–1	Diversity dial. Higher = more experimental output.

Values outside the allowed range are clamped to 0–1.

Simple

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "simple",
    "prompt": "bright city pop about a late train home",
    "instrumental": false
  }'

Custom

curl -X POST https://api.omnapi.com/api/v1/suno/songs \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "custom",
    "lyrics": "[Verse]\nNeon rain on the station floor...",
    "tags": "city pop, warm bass, female vocal",
    "title": "Late Train"
  }'

POST /api/v1/suno/clips/{clipId}/derive

Create a derivative from an existing clip.

action	What it does	Common fields
extend	Continue a clip	continueAt, prompt, tags, title
cover	Reinterpret a clip	prompt, tags, title
overpaint	Replace vocals, keep backing	prompt, tags, vocalGender
underpaint	Replace instruments, keep vocals	prompt, tags, vocalGender

curl -X POST https://api.omnapi.com/api/v1/suno/clips/clip_123/derive \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "extend",
    "continueAt": 92.5,
    "prompt": "add a bigger final chorus",
    "tags": "anthemic pop rock"
  }'

POST /api/v1/suno/clips/{clipId}/export

Export generated assets.

format	Output	Notes
wav	WAV audio	Availability depends on the source clip and account capabilities
video	MP4 visualizer	Creates or returns the clip video
stems	Separated audio	stemsMode: "two" or "twelve"

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

POST /api/v1/suno/lyrics

Generate Suno lyrics. Set candidates: 2 for paired candidates. Returns a task id — poll GET /api/v1/tasks/{taskId} for the result.

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

Clip reads

Endpoint	Purpose
GET /api/v1/suno/clips/{clipId}	Single clip detail, including viewer-scoped fields
GET /api/v1/suno/clips?ids=a,b,c	Batch clip query
GET /api/v1/suno/clips/{clipId}/timeline	Aligned lyrics timeline
GET /api/v1/suno/styles/recommend	Recommended styles. Optional ?exclude=a,b,c filters up to 50 styles out of the response.

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

Personas

Create a persona either from an existing rootClipId, or from two remote audio URLs that OmnAPI validates before use.

curl -X POST https://api.omnapi.com/api/v1/suno/personas \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo Voice",
    "voiceAudioUrl": "https://example.com/voice.mp3",
    "verificationAudioUrl": "https://example.com/verification.mp3"
  }'

Use GET /api/v1/suno/personas to list personas and GET /api/v1/suno/personas/{personaId} for details.

Uploads

Upload a remote audio URL into Suno. URLs must use http or https; private network addresses and oversized files are rejected.

curl -X POST https://api.omnapi.com/api/v1/suno/uploads \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/source.mp3",
    "title": "Imported Demo",
    "describeAudio": true
  }'

Legacy migration map

For minimal client changes, legacy Suno Cloud clients can use the /v1/* migration routes with the legacy api-key header. x-api-key is also accepted. Migration routes return OmnAPI task identifiers; poll GET /api/v1/tasks/{taskId} for the canonical result.

Legacy suno-cloud endpoint	New OmnAPI endpoint
POST /v1/generate-gpt	POST /api/v1/suno/songs with mode: "simple"
POST /v1/generate	POST /api/v1/suno/songs with mode: "custom"
POST /v1/generate/lyric	POST /api/v1/suno/lyrics
GET /v1/songs	GET /api/v1/suno/clips?ids=...
GET /v1/songs/lyric-stamp	GET /api/v1/suno/clips/{clipId}/timeline
POST /v1/upload	POST /api/v1/suno/uploads
POST /v1/stems	POST /api/v1/suno/clips/{clipId}/export with format: "stems"
POST /v1/generate-wav	POST /api/v1/suno/clips/{clipId}/export with format: "wav"
POST /v1/concatenate	POST /api/v1/suno/clips/{clipId}/derive with action: "extend" plus auto-concat configuration
POST /v1/create-persona	POST /api/v1/suno/personas
POST /v1/extend-and-concat	Migration route that submits an extend task
GET /v1/extend-and-concat/{jobId}	GET /api/v1/tasks/{taskId}

Note

The /v1/* migration routes are provided for existing clients. Treat them as a transition path, not the preferred contract for new integrations.