Suno · Music Generation
Suno Music API · Introduction
Suno is the most full-featured AI music capability: generate a whole song from one sentence, plus extend, cover, mashup, split stems, make sound effects, add cover art, even train a custom style. Below we explain it in plain language, then link to every capability.
How to call (in 3 lines)
- Every capability goes to one endpoint:
POST /api/cqt/generator/suno; thetaskfield decides what you do. - You first get a
taskIdback — the music is not ready immediately. - Poll with the taskId:
GET /api/cqt/info/suno?id=taskIduntil status becomes success.
⚡ One exception: Song Download uses its own endpoint
POST /api/cqt/v2/suno/download and returns the download link in one request — no polling. Pass a clip ID, a song page URL, or one of your suno task IDs.About pricing
Each call costs credits, varying by capability: 30 for a song, 10 for a sound effect, 60–150 for stem separation, 1–4 for small tools (lyrics/tags/export). Credits are auto-refunded if a task fails.
Model versions
Creation capabilities need a model. Three are available:
v6— v6 Pro: strongest and most balanced. Use it when unsure.v6-mini— lighter and less resource-hungry.v6-wild— better for experimental, wilder styles.
Legacy v55, v50, v45+, v45, v45-lite and v40 are still accepted but always run as v6 Pro, so existing calls need no change. To use mini / wild you must pass v6-mini or v6-wild explicitly. Pricing is unchanged — the v6 series costs the same as the legacy models.
Capability map
Click any capability for details and live try-out:
Music CreationNEW
POSTCreate New Music
Generate a brand-new song from scratch — just describe the style you want or provide lyrics.
POSTExtend Song
Continue an existing song to make it longer.
POSTCover
Re-perform an existing song in a new style (melody kept, style/arrangement changed).
POSTExtend Uploaded Audio
Continue generating from audio you uploaded.
POSTCover Uploaded Audio
Re-perform your uploaded audio in a new style.
POSTReuse Style with New Lyrics
Keep a song’s style but swap in your new lyrics.
POSTReplace Section
Redo only one part of a song (e.g. the second verse), keeping the rest.
POSTReplace & Auto-mergeNEW
One-shot replace_section + auto-merge: one replace produces two candidates, each is auto-merged back into a full track, directly yielding 2 complete songs — no manual replace_merge needed.
POSTAdd Instrumental
Add backing instruments to a chosen section.
POSTAdd Vocals
Add sung vocals to a chosen instrumental section.
POSTMashup Two Songs
Blend two songs into a new one.
POSTSample
Take a snippet from existing music as inspiration to generate new music.
POSTGenerate Sound Effect
Generate a sound effect (not a song), e.g. thunder or footsteps.
Inspiration PlaylistNEW
POSTCreate Inspiration PlaylistNEW
Bundle 1-4 reference clips into an "inspiration playlist"; returns a playlistId (synchronously) for the next inspiration step.
POSTGenerate from Inspiration
Generate new music matching an "inspiration playlist". First get a playlistId via playlist_create (the old playlist_clip_ids shortcut is deprecated).
Stem Separation
Enhance & AssetsNEW
POSTRemasterNEW
Re-optimize a song’s audio quality and clarity.
POSTCover ImageNEW
Generate a cover image for your song.
POSTStandalone VideoNEW
Generate accompanying video footage for music.
POSTCustom ModelNEW
Train a dedicated style model from audio you provide.
POSTVoice PersonaNEW
Extract a "voice persona" from a song to sing other songs later.
POSTVoice Persona ①: InitNEW
Voice-persona step 1 (free): upload your voice + pick a language; returns a verification phrase and a session taskId.
POSTVoice Persona ②: CompleteNEW
Voice-persona step 2 (5 credits): pass the taskId from init + a recording of the verification phrase + a name to create the persona.
POSTMerge Two LyricsNEW
Merge two lyric texts into new lyrics — often a pre-step for mashup. Takes lyric text, not clip IDs.
Audio EditingNEW
Helpers / ExportNEW
POSTSong DownloadNEW
Download a Suno song as a real audio file. The audio on the official page is an encrypted stream — saving it directly gives you garbage bytes. This endpoint restores the full audio, re-hosts it on our CDN and returns a direct download link.
POSTGenerate Lyrics
Generate lyrics text only (no song).
POSTEnhance Tags
Expand your simple style tags into a richer description.
POSTUpload Audio
Upload external audio and get back a clip ID for other features.
POSTMerge Clips
Concatenate/merge multiple audio clips into one.
POSTExport MP4 / WAV / Timeline / Downbeats
Export a song to video (MP4), lossless audio (WAV), or get lyric timeline / beat data.
Common Errors
| Code | msg | Meaning | How to fix |
|---|---|---|---|
| 451 | artist name not allowed | Your description references a specific artist, which Suno does not allow. Message: "we don’t reference specific artists on Suno". | Remove the artist name and use style/genre words (e.g. pop, jazz, upbeat), then retry |
| 451 | content moderation | Prompt/lyrics rejected by content moderation | Edit the prompt or lyrics and retry |
| 401 | Unauthorized | Invalid or disabled API Key | Check the Authorization header and API Key |
| 402 | insufficient credits | Insufficient credits | Recharge in the console and retry |
| 429 | Task limit reached | Too many running tasks (concurrency limit) | Wait for running tasks to finish, then submit |
| 500 | failed / timeout | Task failed or request timed out | Retry later; contact support if it persists |
Tip: after saving your API Key via Authorize (top-right), every capability page supports "Try it".