Skip to main content
POST
The /generate endpoint supports 17 different task types. Each task has its own page under Generate tasks: required fields and a copy-ready example. Generate Schema is the same data as JSON (GET /suno/v2/generate/schema?task=xxx).

​
Quick Start

1

Check required parameters

Call GET /suno/v2/generate/schema?task=create to get the parameter schema and a request example for the create task.See Generate Schema →
2

Send generate request

Call POST /suno/v2/generate with the correct parameters for your task type.
3

Poll task status

Use the returned taskId to poll Get Task Status until status is success.

​
Task Types Overview

All tasks require the task and model fields. Use GET /suno/v2/generate/schema?task=xxx to get the full parameter details for any specific task type. For task=create, schema examples include custom / simple_idea / simple_audio_refs. Simple can also take attached_lyrics, image_urls (1–5 jpeg or png), and one video_url (mp4). For replace: replaceSection / replaceSimple.

​
replace_simple vs replace_section

Pages: Simple replace, Replace section. Prefer replace_simple when you only have a clip and a time range. The task is stored and billed as replace_section — /status shows task=replace_section. Use replace_section when you need to set infill_context_range yourself. The server:
  • Snaps range to a 40ms grid.
  • Widens a selection shorter than 4s around its center, clamped to the song. Max selection 120s. A song shorter than 4s returns HTTP 400.
  • Builds context about ±15s. A client infill_context_range is ignored.
  • Picks lyrics in this order: continued_aligned_prompt → replace original_infill_lyrics with infill_lyrics in the original lyrics → original clip lyrics → 400 if none exist.
  • Treats infill_type as deprecated. smart / classic / fixed all run as infill. Omit it.
Omit title / tags to keep the original song’s title and style. Optional: negative_tags, prompt, persona, max_mode, controls, vocal_gender. original_infill_lyrics must appear in the original lyrics when you use it to swap one line.

​
task=create: Custom vs Simple

Do not send agentic_thinking or create_mode. Mode is inferred from the body.
audio_refs, image_urls, and video_url are Simple only. Sending any of them with lyrics (prompt) or persona returns HTTP 400. image_urls and video_url on any task other than create are also 400. A non-empty prompt ignores attached_lyrics and stays Custom.
audio_refs pick is ByModel — clips do not need to belong to the occupied pool account. Other-user official clip_ids are accepted; the result may be marked remix and commercial download may be disabled.

​
audio_refs[]

​
Speech (task=create + is_speech)

Full page: Speech. Speech is still task=create (same billing). Omit is_speech for a normal song. is_speech and backing_music only take effect when true, and only on create. Official captures use chirp-v6-mini.

​
Sounds (task=sound)

Full page: Sounds. Required: sound.description. Model chirp-v6. Always instrumental. prompt and tags you send are overwritten. max_mode is rejected. Key needs a space: "G maj", not Gmaj or G major. Values outside the key list return 400. "G" and "G maj" both become user_key: "G". "A min" becomes "Am". Natural notes are sent as-is. Major drops maj; minor replaces min with m. The 12 notes are C, C#, D, D#, E, F, F#, G, G#, A, A#, B — each as a natural, maj, and min. Loop + G major + BPM Auto → sound_configs { "user_key": "G", "user_loop": true }. Add bpm: 120 to also send user_tempo: 120.

​
Common Parameters

These parameters are shared across most task types: Official Create form mapping (Max Mode, Variety, Duration, …): Create Options.

​
persona object

​
controls object

​
Examples

task=inspiration requires a real playlist_id from Create Playlist. The legacy pattern playlist_id: "inspiration" with playlist_clip_ids is deprecated. See the Inspiration workflow.
Not sure which parameters to pass? Call GET /suno/v2/generate/schema?task=your_task — it returns the required fields, optional fields, not-allowed fields, and a complete request example for each task type.Try Generate Schema →

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
task
enum<string>
required

Task type. Use GET /generate/schema?task=xxx to query required fields for each task. replace_simple = replace_section where the server computes infill_context_range / mode / lyrics from clip_id + range.

Available options:
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,
add_stems,
replace_simple
Example:

"create"

​
model
string
required

Model version. New: chirp-v6 (v6 Pro), chirp-v6-mini, chirp-v6-wild. Legacy names (chirp-v55 / chirp-v50 / chirp-v45 / chirp-45+ / chirp-v45-lite / chirp-v40 / chirp-v35) are still accepted and always auto-converted to v6 Pro. Custom: chirp-custom:.

Example:

"chirp-v6"

​
make_instrumental
boolean
default:false

Whether to make instrumental (no vocals). [Optional: all tasks]

Example:

false

​
prompt
string

Lyrics (official Custom). [Optional] task=create + non-empty prompt → Custom (you write lyrics). task=create + empty/omit prompt is Simple ONLY if you also send gpt_description_prompt and/or audio_refs and/or attached_styles and/or attached_lyrics (and no persona). Empty prompt with none of those three fields stays Custom. Do not send lyrics together with audio_refs (400). replace_section: lyrics inside infill_context_range.

Example:

"[Verse]\nHello world, here I come...\n\n[Chorus]\nLa la la..."

​
continued_aligned_prompt
string

Full song lyrics after replacement. [Required: replace_section] [Optional: replace_simple] Contains the complete lyrics of the entire song with the replaced section updated. replace_simple: omit to reuse the original clip lyrics (or the splice of original_infill_lyrics → infill_lyrics); returns 400 when the original lyrics cannot be found either.

Example:

"[Verse 1]\nOriginal lyrics...\n\n[Chorus]\nNew replaced lyrics...\n\n[Verse 2]\nMore lyrics..."

​
infill_lyrics
string

Lyrics for the replaced section only. [Optional: replace_section, replace_simple] The specific lyrics within the range being replaced.

Example:

"[Bridge]\nThis is the new bridge section\nWith updated lyrics..."

​
original_infill_lyrics
string

Original lyrics inside the selected range. [Optional: replace_simple] When continued_aligned_prompt is omitted, the server replaces this text with infill_lyrics in the original clip lyrics.

Example:

"Old bridge line"

​
gpt_description_prompt
string

Natural-language song idea (official Simple text box). [Optional] task=create + empty/omit prompt + this non-empty field + no persona → Simple. May be "" if you only send audio_refs and/or attached_styles and/or attached_lyrics. Ignored when prompt has lyrics (Custom). Also used by mashup.

Example:

"Emotive bossa nova song about the silence after a fight"

​
tags

Style tags. Supports string or array. [Optional: all tasks]

Example:

"Pop, Happy, Upbeat"

​
negative_tags

Official Create form → More Options → "Exclude styles". Mapped to top-level negative_tags. [Optional: all tasks]

Example:

"Sad, Slow"

​
title
string

Song title. [Optional: all tasks]

Example:

"Summer Vibes"

​
clip_id
string

Source clip ID. [Required: extend, cover, use_styles_lyrics, replace_section, replace_simple, add_instrumental, add_vocals, gen_stem_*, add_stems, sample]

Example:

"clip_abc123"

​
continue_at
number

Continue position in seconds. [Optional: extend, upload_extend]

Required range: x >= 0
Example:

30

​
range
object

Target range { start_s, end_s }. [Required: replace_section, replace_simple, sample] For replace_section: the section to replace (use at least 4 seconds; shorter selections usually fail and are refunded by Suno). For replace_simple: the selection to replace; the server snaps it to a 40ms grid, widens it to at least 4s around its center, and builds the context window. For sample: the time range to sample from source clip.

Example:
​
infill_type
enum<string>

Infill mode. [Optional: replace_section, replace_simple] DEPRECATED: Suno no longer supports fixed_infill, so smart / classic / fixed all run as infill on every model. Still accepted for backward compatibility; you can omit it.

Available options:
smart,
classic,
fixed
Example:

"smart"

​
infill_context_range
object

Infill context range (must encompass range). [Required: replace_section] [Ignored: replace_simple — computed by the server] 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.

Example:
​
persona
object

Artist persona config for style mimicking. [Optional: create, cover, extend, replace_section, replace_simple]

Example:
​
controls
object

Official Create form → More Options sliders. style_weight = Style Influence (01); weirdness_constraint = Weirdness (01); aug_creativity = Variety (04 int, 2=Normal, 4=max); audio_weight = reference-audio influence (cover/extend, 01); duration = Duration Custom in seconds (10~360, chirp-v55+). Omit unused keys.

Example:
​
vocal_gender
enum<string>

Official Create form → More Options → "Vocal Gender" (Male=m, Female=f). Mapped to metadata.vocal_gender. Omit for no preference.

Available options:
m,
f
Example:

"m"

​
is_speech
boolean

Speech tab. [Optional: create only] true = this create is spoken audio, not a song. Mapped to metadata.is_speech. Omit or false = normal song; the field is not sent. Ignored on every task except create. Billing stays task=create.

Advanced (you write the script): task=create, non-empty prompt = the words to speak, tags = voice style (pace, tone, "no whisper"), vocal_gender m|f, is_speech true, backing_music true if a music bed should sit under the voice. controls.aug_creativity is Variety (0–4, 4 = max).

Simple (idea only): task=create, omit prompt and persona, put the idea in gpt_description_prompt, set is_speech true and vocal_gender. The server sends this as the official Simple mode. Leave backing_music unset unless you want a music bed.

Example:

true

​
backing_music
boolean

Speech tab → music under the voice. [Optional: create only] true maps to metadata.backing_music. Use with is_speech on the advanced script form. Omit or false = not sent. Ignored unless task=create.

Example:

true

​
audio_url
string<uri>

Audio URL for upload tasks. [Required: upload_extend, upload_cover]

Example:

"https://example.com/audio.mp3"

​
mashup_clip_ids
string[]

Two clip IDs for mashup [clip_a, clip_b]. [Required: mashup]

Example:
​
playlist_id
string

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.

Example:

"119573ff-8e48-4fe6-9029-39c76c9a5597"

​
sound
object

Sounds tab. [Required: task=sound] model chirp-v6. Always instrumental. prompt and tags you send are overwritten.

Maps to the Sounds form: description = the Sound box; type = Advanced Type (one_shot | loop); key = Advanced Key; bpm = Advanced BPM.

Official payload: tags = description only. Loop, key, and BPM go in metadata.sound_configs:

  1. user_loop=true — only when type is "loop".
  2. user_key — "G" and "G maj" both become "G"; "G min" becomes "Gm". Omit key for Any.
  3. user_tempo — only when bpm is set. Omit bpm for Auto. Title is the description with each word capitalized, cut at 80 characters ("..." fills the last 3).

Loop + G major + BPM Auto → sound_configs { user_key: "G", user_loop: true }. Loop + G + BPM 120 → { user_loop: true, user_key: "G", user_tempo: 120 }. max_mode is rejected on sound.

Example:
​
stem_control_tags
string

Stem control tags for add_stems. [Optional: add_stems] Default "add ".

Example:

"add "

​
max_mode
boolean
default:false

Official Create form → "Max Mode" (also in More Options). Mapped to metadata.is_max_mode. Uses more compute for consistency throughout the song. Costs 2x official-account credits. User billing is 2x via a platform param_cost_rule matching max_mode=true. Default omitted/false = current pricing (no change). Rejected on gen_stem_* and sound (HTTP 400).

Example:

false

​
use_personalization
boolean
default:false

Official Create form → More Options → "Personalize" / "My Taste". Mapped to top-level use_personalization. Uses the picked official account's taste profile. Default omitted/false. Effect is not guaranteed (pool accounts may have no taste data).

Example:

false

​
audio_refs
object[]

Official Simple → attach existing songs (chips above the idea box). [Optional, create Simple only] 1–4 items. Omit prompt and persona (400 otherwise). Account pick is normal ByModel. clip_id is required; style_prompt / lyrics / duration_s are optional (clip_id alone is enough). Clips do not need to belong to the occupied pool account. Other-user clip_ids are accepted; official may mark the result as a remix and disable commercial download.

Required array length: 1 - 4 elements
Example:
​
attached_styles
string

Official Simple → attached style paragraph (top-level attached_styles). [Optional, create Simple only] A written style brief, e.g. "Modern country heartbreak with 92 BPM two-step groove…". Can be sent with audio_refs, or alone. Empty/omit prompt + this field + no persona → Simple. Ignored on Custom (non-empty prompt).

Example:

"Modern country heartbreak with 92 BPM two-step groove, acoustic guitar downstrokes locking every downbeat, pedal-steel answers, and twangy Telecaster fills."

​
attached_lyrics
string

Official Simple → pinned lyrics (top-level attached_lyrics). [Optional, create Simple only] Full lyrics the caller already wrote. prompt stays empty, so this stays Simple (upstream agentic_thinking), not Custom. Empty/omit prompt + this field + no persona → Simple, even without gpt_description_prompt. Can be sent with gpt_description_prompt and attached_styles. Ignored when prompt is non-empty. Omit to leave the payload unchanged.

Example:

"[Verse 1]\n旧窗花还贴在门上\n\n[Chorus]\n新年快乐，新年快乐"

​
image_urls
string<uri>[]

Official Simple → + Image. [Optional, create Simple only] 1–5 jpeg or png URLs the server can download. Omit prompt and persona (400 otherwise). Also 400 on every task except create. The server uploads each URL on the account selected for this generate and sends the resulting ids as user_uploaded_image_ids. Empty/omit prompt + image_urls + no persona is Simple even without gpt_description_prompt. Omit image_urls to leave the request unchanged.

Required array length: 1 - 5 elements
Example:
​
video_url
string<uri>

Official Simple → one reference video. [Optional, create Simple only] One mp4 URL the server can download. Omit prompt and persona (400 otherwise). Also 400 on every task except create. The server uploads it on the account selected for this generate and sends the id as user_uploaded_video_id. Empty/omit prompt + video_url + no persona is Simple even without gpt_description_prompt. Omit video_url to leave the request unchanged.

Example:

"https://example.com/clip.mp4"

Response

201 - application/json
​
taskId
string
required

task id. Use this id to query task status.

Example:

"15c257ff-43f7-4678-bd41-202ad6b8488b"