Suno API

Suno is the direct music provider surface. It uses the same authentication, credit reservation and polling model as Producer:

• Authenticate with x-api-key
• Create a task with one of the POST /api/v1/suno/* endpoints
• Receive { taskId, status, creditsReserved }
• Poll GET /api/v1/tasks/{taskId} until terminal

Default model: suno/chirp-fenix/*. You can override model on generation and derive endpoints when you need a specific Suno model.

Caution

Legacy suno-cloud /v1/* compatibility is available as a migration bridge, but new integrations should use /api/v1/suno/*. The compatibility routes are task-first and may return taskId instead of the old synchronous payloads.

---

Shared config

Every task-creating endpoint accepts an optional config object:

{
  "config": {
    "priority": 5,
    "tags": ["campaign-42"],
    "metadata": { "customerId": "cus_123" },
    "webhookUrl": "https://yourapp.com/webhooks/omnapi"
  }
}

webhookUrl is per-task. If omitted, poll GET /api/v1/tasks/{taskId}.

Response shape

Creation endpoints return immediately:

{
  "taskId": "task_01H...",
  "status": "PENDING",
  "creditsReserved": 30,
  "estimatedCompletionTime": null
}

Read-style Suno endpoints such as clip detail and timeline use the same task system but wait briefly for a result. If they do not finish during that window, poll the returned taskId like any other task.

---

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.

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	Premium Suno account required upstream
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, or wait: true to block briefly 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

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 uploads and verifies for you.

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 call the /v1/* facade with the old api-key header. x-api-key is also accepted. The facade submits normal OmnAPI tasks and returns 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	Compatibility facade that submits an extend task
GET /v1/extend-and-concat/{jobId}	GET /api/v1/tasks/{taskId}

Note

The /v1/* facade is intentionally not published in the public OpenAPI playground. Treat it as a migration tool, not the preferred contract for new customer builds.