Suno Music Generation

Generate AI-powered music through AceDataCloud's Suno API.

Setup: See [authentication](../_shared/authentication.md) for token setup.

Quick Start

curl -X POST https://api.acedata.cloud/suno/audios \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a happy pop song about coding", "model": "chirp-v6", "callback_url": "https://api.acedata.cloud/health"}'

Async: All generation is async. See [async task polling](../shared/async-tasks.md). Poll via POST /suno/tasks with {"id": "<taskid>"} every 3-5 seconds.

Available Models

Core Workflows

1. Quick Generation (Inspiration Mode)

Generate a song from a text description. Suno creates lyrics, style, and music automatically.

POST /suno/audios
{
  "prompt": "an upbeat electronic track about the future of AI",
  "model": "chirp-v6",
  "instrumental": false
}

2. Custom Generation (Full Control)

Provide your own lyrics, title, and style for precise control.

POST /suno/audios
{
  "custom": true,
  "lyric": "[Verse]\nCode is poetry in motion\n[Chorus]\nWe build the future tonight",
  "title": "Digital Dreams",
  "style": "Synthwave, Electronic, Dreamy",
  "model": "chirp-v6",
  "vocal_gender": "f"
}

3. Extend a Song

Continue an existing song from a specific timestamp with new lyrics.

POST /suno/audios
{
  "action": "extend",
  "audio_id": "existing-audio-id",
  "lyric": "[Bridge]\nNew section lyrics here",
  "continue_at": 120.0,
  "style": "Same style as original"
}

4. Cover / Remix

Create a new version of an existing song in a different style.

POST /suno/audios
{
  "action": "cover",
  "audio_id": "existing-audio-id",
  "style": "Jazz, Acoustic, Mellow"
}

5. Full Song Creation Workflow

For best results follow this multi-step workflow:

1. Generate lyrics — POST /suno/lyrics with a topic/prompt
2. Optimize style — POST /suno/style to refine style description
3. Generate music — POST /suno/audios with custom action, lyrics + style
4. Poll task — POST /suno/tasks with id (or ids for batch) until status is complete
5. Optional: Extend — Use extend action to add more sections
6. Optional: Concat — Use concat action to merge extended segments
7. Optional: Convert — Get WAV (/suno/wav), MIDI (/suno/midi), or MP4 (/suno/mp4)

Available Actions

Custom Music Models (Beta)

Custom models learn reusable musical characteristics from 6–24 authorized audio files. Creation is a paid, long-running operation. Ask the user to confirm the files and cost before submitting it.

Create

POST /suno/custom-models
{
  "action": "create",
  "name": "My Album Sound",
  "audio_urls": [
    "https://cdn.example.com/track-01.mp3",
    "https://cdn.example.com/track-02.mp3",
    "https://cdn.example.com/track-03.mp3",
    "https://cdn.example.com/track-04.mp3",
    "https://cdn.example.com/track-05.mp3",
    "https://cdn.example.com/track-06.mp3"
  ]
}

Send a stable Idempotency-Key header and reuse it after network failures. Save the returned id; query it until status is ready.

Query and list

POST /suno/custom-models
{"action": "retrieve", "id": "<custom-model-id>"}

POST /suno/custom-models
{"action": "retrieve_batch", "status": "ready", "limit": 20, "offset": 0}

Generate

POST /suno/custom-models
{
  "action": "generate",
  "id": "<ready-custom-model-id>",
  "lyric": "[Verse]\nOriginal lyrics here",
  "style": "warm indie pop",
  "title": "New Song",
  "async": true
}

Async acceptance is not terminal success: poll the returned task and inspect response.success. A custom-model request never falls back to another model. The model must belong to the current Suno application and have status: "ready".

Archive

POST /suno/custom-models
{"action": "delete", "id": "<custom-model-id>"}

delete archives the platform resource and prevents further use. capacity_released: false means it does not promise that model capacity was released.

Auxiliary Endpoints

Advanced Parameters

Lyrics Format

Use section markers in square brackets:

[Verse 1]
Your verse lyrics here

[Chorus]
Catchy chorus lyrics

[Bridge]
Bridge section

[Outro]
Ending lyrics

Gotchas

• All generation is async — always set "callbackurl" to get a task id immediately, then poll /suno/tasks using {"id":"<taskid>"} or {"ids":[...],"action":"retrieve_batch"}
• CRITICAL: Check the state field — only state: "complete" with success: true means done. During pending, the API may return intermediate audiourl values (streaming previews). Do NOT stop polling just because audiourl is non-empty
• Lyrics max ~3000 characters. For longer songs, use the extend workflow
• Style tags are descriptive phrases, not enum values (e.g., "Synthwave, Electronic, Dreamy")
• vocal_gender ("f"/"m") is only supported on v4.5+ models
• variation_category ("high"/"normal"/"subtle") is only supported on v5+ models
• duration is forwarded as you send it — support varies by model and action, and an unsupported combination may ignore it or return an error, so verify with one request before batching. Note the request duration is a target; the duration in each returned clip is the actual length and will vary slightly
• The concat action merges extended song segments — requires audio_id of the extended track
• persona requires an existing audioid and a name; optional voxaudioid, vocalstart, vocal_end, and description refine the vocal reference
• Upload external audio via /suno/upload before using it with extend/cover

MCP: pip install mcp-suno | Hosted: https://suno.mcp.acedata.cloud/mcp | See [all MCP servers](../_shared/mcp-servers.md)