Suno Music Generation

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

First-time setup

1. Install the official Skill with clawhub install @acedatacloud/suno. Check that the ClawHub publisher is @acedatacloud.
2. Sign in at AceDataCloud → Applications, open General application, and check Suno access, balance, and current pricing. Copy its API key, or select Manage Keys → Create for a separate key. Copy the key value without Bearer ; a platform-... management token is not a service API key.
3. If you enable Allowed APIs restrictions, include /suno/audios and /suno/tasks. Advanced workflows below may call additional routes.
4. On the OpenClaw Gateway host, put ACEDATACLOUD_API_TOKEN=your_api_key_here in ~/.openclaw/.env, then restart the Gateway and start a new session. For a direct terminal test, run export ACEDATACLOUD_API_TOKEN="your_api_key_here" in that shell. Never put the key in a prompt or commit an .env file.
5. Run the Quick Start below. If it returns a task ID, query that same task until it finishes; do not submit a second billable generation just to check progress.

Illustrated key setup, first run, and troubleshooting · Token details

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", "async": true}'

Async: All generation is async. See async task polling. Poll via POST /suno/tasks with {"id": "<task_id>"} 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 MP3 (/suno/mp3), 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.

Studio Projects (Beta)

Use POST /suno/projects for versioned multitrack editing, not /suno/audios. Only process audio the user has rights to use. Send an Idempotency-Key header (1–128 characters) for every action except retrieve; keep the same key and payload when recovering an uncertain request. A new operation needs a new key; reusing a key with a different payload returns 409.

Create, retrieve, and save

POST /suno/projects
{"action":"create","title":"My Studio Project"}

Save data.id, then retrieve with that project id before editing. The returned state is authoritative; modify it rather than inventing track/clip structures. An empty project starts with {"tracks":[],"timing":{"bps":2}}.

POST /suno/projects
{"action":"retrieve","id":"PROJECT_ID"}

POST /suno/projects
{"action":"save","id":"PROJECT_ID","state":{"tracks":[],"timing":{"bps":2}}}

save replaces the complete state, not a patch: preserve unknown fields from retrieve.data.state. It completes synchronously even if its result includes task_id. Only the first save of a new, unversioned project may omit version_id. Afterwards, include the latest version_id in every modification, candidate generation, and render. After save, add_track, commit_candidate, or remove_track, retain the new version from the result. upload, render, generate_track, and replace_section do not change the project version. On HTTP 409, retrieve the current project, reconcile changes, and submit with a new key; do not blindly replay stale edits.

timing.bps is beats per second, must be positive, and defaults to 2 (120 BPM). Clip startBeats, endBeats, and readStartBeats are project beats, not audio-analysis bar positions. Request placement fields start_beats / end_beats are nonnegative project beats; start_seconds / end_seconds select source-audio seconds.

Upload and add audio

POST /suno/projects
{"action":"upload","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","audio_url":"https://cdn.example.com/reference.mp3","async":true}

Poll the upload task to success, then read response.data.candidate.audio_id and use it in add_track:

POST /suno/projects
{"action":"add_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","audio_id":"AUDIO_ID","name":"Backing Vocals"}

Default placement preserves playback speed and converts audio duration to beats using timing.bps.

Generate, choose, and commit candidates

Projects accept only these public model names: chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild, chirp-v6-mini. An unsupported name returns 400 before submission; an accepted name does not guarantee the selected operation succeeds. Never silently switch models.

POST /suno/projects
{"action":"replace_section","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","source_audio_id":"AUDIO_ID","start_seconds":35.12,"end_seconds":48.76,"model":"chirp-v6","replacement_lyrics":"New section lyrics","async":true}

replace_section returns two candidates without selecting one. The end must not exceed the actual source duration. prompt supplies source lyrics/context; replacement_lyrics supplies the new interval lyrics. If fixed=true, the range must be shorter than 26 seconds; support is model-dependent and this mode is not verified by the documented Backend run.

For a new track, first add the source audio to the project, then retrieve the complete state and append an empty audio track with a fresh unique id, type:"audio", clips:[], takeLanes:[], mute:false, solo:false, amplitude:1, instrument:{"type":"song"}, and color:"#7251F7". Save the complete state before generating, retaining its new version and the destination track ID. Render that version to success and use response.data.audio_id as the mix reference:

POST /suno/projects
{"action":"generate_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","source_audio_id":"AUDIO_ID","render_audio_id":"RENDER_AUDIO_ID","model":"chirp-v5","start_seconds":12,"end_seconds":20,"stem_control_tags":"add Piano","tags":"gentle piano, instrumental","batch_size":2,"instrumental":true,"vocal_gender":"unspecified","async":true}

stem_control_tags is descriptive text, not an enum. batch_size is 1–4 (default 2). instrumental defaults to true; use prompt for new-track text/lyrics and vocal_gender (f, m, unspecified, default unspecified) for a preference, not a guaranteed result. Both generation actions accept tags and negative_tags (default empty strings). Source-second ranges are not output-duration guarantees; inspect each candidate's actual duration. Generation does not add candidates to the project.

Poll to success, read response.data.operation_id and the chosen response.data.candidates[].id (do not substitute project IDs or the commit task ID), and let the user choose a candidate before committing:

POST /suno/projects
{"action":"commit_candidate","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","operation_id":"OPERATION_ID","candidate_id":"CANDIDATE_ID","track_id":"TRACK_ID","async":true}

• Candidates are bound to the version used to generate them. Save an empty destination track before generating a new-track candidate; creating it afterwards makes the candidate stale.
• Replacement candidates must go back to the original track containing the unique source clip. A full take preserves its placement; an interval replacement preserves the surrounding clips. Do not supply start_beats / end_beats for these replacements. If duration cannot be matched reliably, the request returns 400 and leaves the project unchanged.
• New-track candidates use the saved empty track and default to the source clip's start, or an explicit non-overlapping range. Overlap on the destination track returns 400.
• To remove a track, confirm the intended track, then submit the current version and retrieve again to verify the remaining state:

POST /suno/projects
{"action":"remove_track","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","track_id":"TRACK_ID"}

Render and recover

POST /suno/projects
{"action":"render","id":"PROJECT_ID","version_id":"CURRENT_VERSION_ID","title":"Final Mix","async":true}

Omit start_beats / end_beats to render from the earliest audible clip start to the latest audible end. Muted tracks/clips are excluded; when solo tracks exist, only those tracks participate. An empty or inaudible project, negative bounds, or an end not greater than the start returns 400. On terminal success, persist the returned render_id, audio_id, audio_url, and duration.

upload, add_track, generate_track, replace_section, commit_candidate, and render always run asynchronously, even with async:false. For every asynchronous Projects operation, poll POST /suno/tasks with {"action":"retrieve","id":"TASK_ID"} every 3–5 seconds. Success requires finished_at and response.success=true; response.success=false indicates failure. Read response.error on failure, including after a callback. HTTP 200 or a task_id is acceptance, not completed audio. This Projects rule is distinct from the /suno/audios clip-state rule below.

A readable candidate URL or successful commit does not prove the project can render. The documented Backend run generated and committed a new track, but rendering with it failed with studio_audio_unavailable; a replacement candidate also failed to commit because its duration matched neither the source nor the selected interval. Keep the original project and candidate for inspection; do not guess placement or automatically repeat paid generation. Before removing an unavailable track, confirm the intended edit with the user, retrieve the current state, remove only that track, then retrieve and render the new version to verify recovery. Projects and candidates are bound to their application and execution environment; do not assume cross-application reuse or automatic failover.

An identical key and payload replay the original result, including failure, without generating again. To explicitly retry, first confirm the original task failed, then use a new key. Never resubmit while the original is processing or uncertain. Keep trace_id for troubleshooting; report studio_state_invalid (400), studio_model_unsupported (400), studio_unavailable / studio_model_unavailable (503), too_many_requests (429), and studio_audio_unavailable / content_rejected (403) rather than changing models or discarding edits.

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

• /suno/audios generation is async — set "callback_url" to get a task id immediately, then poll /suno/tasks using {"id":"<task_id>"} or {"ids":[...],"action":"retrieve_batch"}
• CRITICAL for /suno/audios: Check the clip state field — only state: "complete" with success: true means done. During pending, the API may return intermediate audio_url values (streaming previews). Do NOT stop polling just because audio_url 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 audio_id and a name; optional vox_audio_id, vocal_start, 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