跳转到主要内容
POST
/generate 端点支持 17 种任务。每种任务在 生成任务 下单独一页：必填字段和可复制示例。Generate Schema 是同一份数据的 JSON（GET /suno/v2/generate/schema?task=xxx）。

​
快速开始

1

检查必填参数

调用 GET /suno/v2/generate/schema?task=create 获取 create 任务的参数模式和请求示例。参见 Generate Schema →
2

发送生成请求

使用正确的参数调用 POST /suno/v2/generate。
3

轮询任务状态

使用返回的 taskId 轮询获取任务状态，直到状态为 success。

​
任务类型概览

所有任务都需要 task 和 model 字段。使用 GET /suno/v2/generate/schema?task=xxx 获取任何特定任务类型的完整参数详情。task=create 的 schema 示例含 custom / simple_idea / simple_audio_refs。Simple 还可以传 attached_lyrics、image_urls（1–5 个 jpeg 或 png），以及一条 video_url（mp4）。替换段落示例：replaceSection / replaceSimple。

​
replace_simple vs replace_section

页面：简单替换、替换片段。 只知道 clip 和时间范围时用 replace_simple。任务落库 / 计费为 replace_section — /status 里看到的是 task=replace_section。需要自己指定 infill_context_range 时用 replace_section。 服务端会：
  • 把 range 对齐到 40ms。
  • 选区短于 4 秒时，以中心向两侧扩到 4 秒，并限制在歌曲长度内。选区最长 120 秒。歌曲本身短于 4 秒会 HTTP 400。
  • 上下文大约是选区前后各 15 秒。传入的 infill_context_range 会被忽略。
  • 歌词按这个顺序取：continued_aligned_prompt → 在原曲歌词里把 original_infill_lyrics 换成 infill_lyrics → 原曲歌词 → 都没有则 400。
  • infill_type 已废弃。smart / classic / fixed 都会按同一种方式处理。可不传。
不传 title / tags 时沿用原曲标题和风格。还可选：negative_tags、prompt、persona、max_mode、controls、vocal_gender。 用 original_infill_lyrics 换一句时，这段原文必须能在原曲歌词里找到。

​
task=create：Custom vs Simple

不要传 agentic_thinking 或 create_mode。模式由请求体推断。
audio_refs、image_urls 和 video_url 仅 Simple。和歌词（prompt）或 persona 一起传会 HTTP 400。image_urls 和 video_url 用在 create 以外的任务上也会 400。prompt 非空时忽略 attached_lyrics，请求仍是 Custom。
audio_refs 选账号是 ByModel — clip 不必属于当前占用的池账号。其他人的官方 clip_id 可用；结果可能被标 remix，商业下载可能被关掉。

​
audio_refs[]

​
朗读 Speech（task=create + is_speech）

完整页面：语音。 朗读仍是 task=create，按 create 计费。不传 is_speech 就是普通歌曲。is_speech 和 backing_music 只有 true 才生效，并且只在 create 上生效。官网示例用 chirp-v6-mini。

​
音效 Sounds（task=sound）

完整页面：音效。 必填 sound.description。模型 chirp-v6。始终无人声。自己传的 prompt 和 tags 会被覆盖。max_mode 不能用。 调性必须带空格，例如 "G maj"，不能写成 Gmaj 或 G major。不在 调性表 里会 400。"G" 和 "G maj" 都变成 user_key: "G"。"A min" 变成 "Am"。自然音原样发送。大调去掉 maj，小调把 min 换成 m。12 个音名是 C、C#、D、D#、E、F、F#、G、G#、A、A#、B，每个都有自然音、 maj、 min。 Loop、G major、BPM Auto → sound_configs { "user_key": "G", "user_loop": true }。再加 bpm: 120 会带上 user_tempo: 120。

​
通用参数

以下参数在大多数任务类型中通用： 官网 Create 表单对照（Max Mode、Variety、Duration 等）：Create 选项。

​
persona 对象

​
controls 对象

​
示例

task=inspiration 必须使用 创建播放列表 返回的真实 playlist_id。旧模式 playlist_id: "inspiration" + playlist_clip_ids 已废弃。详见 Inspiration 流程。
不确定该传哪些参数？ 调用 GET /suno/v2/generate/schema?task=your_task — 它会返回每种任务类型的必填字段、可选字段、不允许的字段和完整的请求示例。试用 Generate Schema →

授权

​
Authorization
string
header
必填

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

请求体

application/json
​
task
enum<string>
必填

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.

可用选项:
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
示例:

"create"

​
model
string
必填

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:.

示例:

"chirp-v6"

​
make_instrumental
boolean
默认值:false

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

示例:

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.

示例:

"[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.

示例:

"[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.

示例:

"[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.

示例:

"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.

示例:

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

​
tags

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

示例:

"Pop, Happy, Upbeat"

​
negative_tags

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

示例:

"Sad, Slow"

​
title
string

Song title. [Optional: all tasks]

示例:

"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]

示例:

"clip_abc123"

​
continue_at
number

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

必填范围: x >= 0
示例:

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.

示例:
​
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.

可用选项:
smart,
classic,
fixed
示例:

"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.

示例:
​
persona
object

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

示例:
​
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.

示例:
​
vocal_gender
enum<string>

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

可用选项:
m,
f
示例:

"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.

示例:

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.

示例:

true

​
audio_url
string<uri>

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

示例:

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

​
mashup_clip_ids
string[]

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

示例:
​
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.

示例:

"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.

示例:
​
stem_control_tags
string

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

示例:

"add "

​
max_mode
boolean
默认值: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).

示例:

false

​
use_personalization
boolean
默认值: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).

示例:

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
示例:
​
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).

示例:

"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.

示例:

"[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
示例:
​
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.

示例:

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

响应

201 - application/json
​
taskId
string
必填

task id. Use this id to query task status.

示例:

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