Generate Music
Generate, extend, cover, mashup and more — the unified music generation endpoint
Quick Start
Check required parameters
GET /suno/v2/generate/schema?task=create to get the parameter schema and a request example for the create task.See Generate Schema →Poll task status
taskId to poll Get Task Status until status is success.Task Types Overview
| Task | Description | Key Required Fields |
|---|---|---|
create | Create new music from scratch | model |
extend | Extend existing music | clip_id, model |
upload_extend | Extend uploaded audio | audio_url, model |
upload_cover | Cover uploaded audio | audio_url, model |
cover | Create cover of existing clip | clip_id, model |
use_styles_lyrics | Use styles from clip with new lyrics | clip_id, model |
replace_section | Replace a section of existing audio | clip_id, range, infill_context_range, continued_aligned_prompt, model |
add_instrumental | Add instrumental to a range | clip_id, range, model |
add_vocals | Add vocals to a range | clip_id, range, model |
gen_stem_two | Generate two-track stems (vocals + instrumental) | clip_id, model |
gen_stem_all | Generate all stems | clip_id, model |
mashup | Mashup two songs | mashup_clip_ids, model |
sample | Sample from existing clip | clip_id, range, model |
inspiration | Generate from a real playlist | playlist_id, model — see Inspiration Guide |
sound | Generate sound effects | sound, model |
task and model fields. Use GET /suno/v2/generate/schema?task=xxx to get the full parameter details for any specific task type.Common Parameters
These parameters are shared across most task types:| Parameter | Type | Description |
|---|---|---|
task | string | Required. The task type (see table above) |
model | string | Required. Model version: chirp-v55, chirp-v50, chirp-45+, chirp-v45, chirp-v45-lite, chirp-v40, chirp-v35 |
prompt | string | Lyrics or prompt text |
tags | string | string[] | Style tags (e.g., "Pop, Happy, Upbeat") |
negative_tags | string | string[] | Styles to exclude |
title | string | Song title |
make_instrumental | boolean | Generate without vocals (default: false) |
vocal_gender | string | "m" (male) or "f" (female) |
controls | object | Advanced control: style_weight, audio_weight, weirdness_constraint (0~1) |
persona | object | Vocal persona for style mimicking |
Examples
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Task type. Use GET /generate/schema?task=xxx to query required fields for each task.
create, extend, upload_extend, upload_cover, cover, use_styles_lyrics, replace_section, add_instrumental, add_vocals, gen_stem_two, gen_stem_all, mashup, sample, inspiration, sound "create"
Model version. Supports standard models (e.g. chirp-v50) and custom models (chirp-custom:).
"chirp-v50"
Whether to make instrumental (no vocals). [Optional: all tasks]
false
Lyrics or prompt text. [Optional: all tasks] For replace_section: lyrics within infill_context_range (modified if replacement changes lyrics).
"[Verse]\nHello world, here I come...\n\n[Chorus]\nLa la la..."
Full song lyrics after replacement. [Required: replace_section] Contains the complete lyrics of the entire song with the replaced section updated.
"[Verse 1]\nOriginal lyrics...\n\n[Chorus]\nNew replaced lyrics...\n\n[Verse 2]\nMore lyrics..."
Lyrics for the replaced section only. [Optional: replace_section] The specific lyrics within the range being replaced.
"[Bridge]\nThis is the new bridge section\nWith updated lyrics..."
Short description for GPT lyrics generation. [Optional: create, mashup, etc.]
"A happy pop song about summer vacation"
Style tags. Supports string or array. [Optional: all tasks]
"Pop, Happy, Upbeat"
Negative style tags to exclude. [Optional: all tasks]
"Sad, Slow"
Song title. [Optional: all tasks]
"Summer Vibes"
Source clip ID. [Required: extend, cover, use_styles_lyrics, replace_section, add_instrumental, add_vocals, gen_stem_*, sample]
"clip_abc123"
Continue position in seconds. [Optional: extend, upload_extend]
x >= 030
Target range { start_s, end_s }. [Required: replace_section, sample] For replace_section: the section to replace (duration should be > 6 seconds). For sample: the time range to sample from source clip.
{ "start_s": 15.36, "end_s": 53.8 }Infill mode for replace_section. [Optional: replace_section] "smart" = auto-select based on duration (default), "classic" = always use infill (better for long selections), "fixed" = always use fixed_infill (better for short selections).
smart, classic, fixed "smart"
Infill context range (must encompass range). [Required: replace_section] Should extend ~30s before range.start_s and ~30s after range.end_s. If range starts within first 30s, use 0 for start_s. If range ends within last 30s of song, use song duration for end_s.
{ "start_s": 0, "end_s": 69.16 }Artist persona config for style mimicking. [Optional: create, cover, extend]
{
"persona_id": "persona_xyz789",
"artist_clip_id": "clip_abc123",
"persona_style": "vox"
}Advanced control sliders (0~1). [Optional: all tasks]
{
"style_weight": 0.6,
"audio_weight": 0.4,
"weirdness_constraint": 0.2
}Vocal gender (m=male, f=female). [Optional: all tasks]
m, f "m"
Audio URL for upload tasks. [Required: upload_extend, upload_cover]
"https://example.com/audio.mp3"
Two clip IDs for mashup [clip_a, clip_b]. [Required: mashup]
["clip_abc123", "clip_def456"]Suno playlist ID. [Required: inspiration] Must be obtained via /playlist/create → /playlist/addClips before calling /generate. Add inspiration clips (1–4, same account) to the playlist first. When combined with persona (vox_playlist_condition), the playlist must exist on the same account as the persona.
"119573ff-8e48-4fe6-9029-39c76c9a5597"
Sound generation config. [Required: sound] description is the core sound prompt (also auto-used as title). type/key/bpm are optional advanced options. Tags are auto-assembled; user-provided tags are ignored for sound task.
{
"description": "深沉的低音和温暖的模拟质感",
"type": "one_shot",
"key": "F#",
"bpm": 2
}Response
task id. Use this id to query task status.
"15c257ff-43f7-4678-bd41-202ad6b8488b"