提交 Suno 音乐任务

概览

所有 Suno 音乐任务统一通过 POST /suno/submit/{action} 提交。
提交后返回任务 ID，使用 /suno/fetch 或 /suno/fetch/{id} 查询状态与结果。

支持的动作（action）

action	功能	默认模型
`generate-music`	生成歌曲/纯音乐	`suno-music-v5.5`
`generate-lyrics`	生成歌词（仅文本）	`suno-lyrics`
`generate-sounds`	生成音效	`suno-sounds-v5`
`extend-music`	延展已有音乐	`suno-extend-v5.5`
`upload-cover`	上传音频重新创作	`suno-upload-cover-v5.5`
`upload-extend`	上传音频并延展	`suno-upload-extend-v5.5`
`add-instrumental`	为音频添加伴奏	`suno-add-instrumental-v5.5`
`add-vocals`	为伴奏添加人声	`suno-add-vocals-v5.5`
`generate-mashup`	混合两首音频生成 Mashup	`suno-mashup-v5`
`replace-section`	替换音乐中指定片段	`suno-replace-section`
`convert-wav`	转换为 WAV 格式	`suno-wav`
`generate-midi`	从分离音频生成 MIDI	`suno-midi`
`create-mp4`	创建音乐可视化视频	`suno-mp4`
`generate-cover`	生成音乐封面图片	`suno-cover`
`vocal-removal`	人声与伴奏分离	`suno-vocal-removal`

可用模型版本

suno-music-* 系列：v4、v4.5、v4.5-plus、v4.5-all、v5、v5.5（默认）

suno-extend-* 系列：v4、v4.5、v4.5-plus、v4.5-all、v5、v5.5（默认）

suno-upload-cover-* / suno-upload-extend-*：同 extend

suno-add-instrumental-* / suno-add-vocals-*：v4.5-plus、v5、v5.5（默认）

suno-mashup-*：v4、v4.5、v4.5-plus、v4.5-all、v5（默认）

suno-sounds-v5 / suno-lyrics / suno-replace-section / suno-wav / suno-midi / suno-mp4 / suno-cover / suno-vocal-removal

请求体通用字段

字段	类型	说明
`model`	string	模型名（不传则使用上表默认模型）
`callBackUrl`	string	回调地址（网关自动注入平台回调，用户可省略）
`prompt`	string	歌词/描述（各类场景必填条件见下方各场景说明）
`style`	string	音乐风格/流派
`title`	string	歌曲标题
`customMode`	boolean	自定义模式开关
`instrumental`	boolean	纯音乐标志
`audioId`	string	音频 ID（从成功任务的 media[].suno_audio_id 获取）
`tags`	string	音乐风格标签
`negativeTags`	string	排除的风格/属性
`uploadUrl`	string	上传音频的公开 URL
`uploadUrlList`	[string]	Mashup：两首源音频 URL 列表
`defaultParamFlag`	boolean	extend：false=复用源参数，true=自定义
`continueAt`	number	extend：续写起点（秒）
`taskId`	string	原始音乐任务 ID（replace-section/convert-wav/cover/mp4/vocal-removal）
`infillStartS`	number	replace-section：替换起始秒数
`infillEndS`	number	replace-section：替换结束秒数
`fullLyrics`	string	replace-section：替换后的完整歌词
`personaId`	string	Persona ID 或 Suno Voice voiceId（可选）
`personaModel`	string	`style_persona` 或 `voice_persona`（可选）
`vocalGender`	string	人声性别 `m` / `f`（可选）
`styleWeight`	number	风格遵循度 0.00-1.00（可选）
`weirdnessConstraint`	number	创意偏离度 0.00-1.00（可选）
`audioWeight`	number	音频影响权重 0.00-1.00（可选）
`soundLoop`	boolean	音效循环播放（可选，仅 sounds）
`soundTempo`	number	BPM 1-300（可选，仅 sounds）
`soundKey`	string	音调（可选，仅 sounds）
`grabLyrics`	boolean	获取歌词字幕（可选，仅 sounds）

各场景请求示例

生成歌曲（generate-music）- customMode=true

{"model":"suno-music-v5.5","prompt":"A hopeful pop song about finding light","style":"Pop, Warm","title":"Morning Light","customMode":true,"instrumental":false}

生成纯音乐（generate-music）- instrumental=true

{"model":"suno-music-v5.5","prompt":"Warm cinematic background music","style":"Cinematic","title":"Launch Day","customMode":true,"instrumental":true}

简易模式（generate-music）- customMode=false

{"model":"suno-music-v5.5","customMode":false,"instrumental":false,"prompt":"A short relaxing piano tune"}

生成音效（generate-sounds）

{"model":"suno-sounds-v5","prompt":"A clean notification sound, short, bright","soundLoop":false}

生成歌词（generate-lyrics）

{"model":"suno-lyrics","prompt":"写一首关于夏夜海边、温柔重逢的中文流行歌词"}

延展音乐（extend-music）- 自定义续写

{"model":"suno-extend-v5.5","audioId":"<suno_audio_id>","defaultParamFlag":true,"continueAt":60,"prompt":"Continue with a brighter chorus","style":"Pop Rock","title":"Brighter Chorus"}

延展音乐（extend-music）- 沿用源参数

{"model":"suno-extend-v5.5","audioId":"<suno_audio_id>","defaultParamFlag":false}

上传并重新创作（upload-cover）

{"model":"suno-upload-cover-v5.5","uploadUrl":"https://example.com/source.mp3","customMode":true,"instrumental":false,"prompt":"Create a warm acoustic cover","style":"Acoustic Pop","title":"Warm Cover"}

上传并延展（upload-extend）

{"model":"suno-upload-extend-v5.5","uploadUrl":"https://example.com/source.mp3","defaultParamFlag":true,"continueAt":60,"prompt":"Extend this into a cinematic ending","style":"Cinematic Pop","title":"Final Scene"}

添加伴奏（add-instrumental）

{"model":"suno-add-instrumental-v5.5","uploadUrl":"https://example.com/vocals.mp3","title":"Instrumental Version","tags":"pop, clean instrumental","negativeTags":"noise, distortion"}

添加人声（add-vocals）

{"model":"suno-add-vocals-v5.5","uploadUrl":"https://example.com/instrumental.mp3","prompt":"Add a gentle female vocal","title":"Vocal Version","style":"Soft Pop","negativeTags":"noise, distortion"}

生成 Mashup（generate-mashup）

{"model":"suno-mashup-v5","uploadUrlList":["https://example.com/source-a.mp3","https://example.com/source-b.mp3"],"customMode":true,"prompt":"Blend the melodies into an upbeat electronic track","style":"Electronic Pop","title":"Two Lights","instrumental":false}

替换片段（replace-section）

{"model":"suno-replace-section","taskId":"task_xxx","audioId":"<suno_audio_id>","prompt":"Replace this section with a brighter hook","tags":"pop, bright hook","title":"Updated Hook","fullLyrics":"[Verse] ... [Chorus] ...","infillStartS":45,"infillEndS":75}

转换 WAV（convert-wav）

{"model":"suno-wav","taskId":"task_xxx","audioId":"<suno_audio_id>"}

生成 MIDI（generate-midi）- 需先完成人声分离

{"model":"suno-midi","taskId":"<vocal_removal_task_id>"}

创建音乐视频（create-mp4）

{"model":"suno-mp4","taskId":"task_xxx","audioId":"<suno_audio_id>"}

生成封面（generate-cover）

{"model":"suno-cover","taskId":"task_xxx"}

人声分离（vocal-removal）

{"model":"suno-vocal-removal","taskId":"task_xxx","audioId":"<suno_audio_id>"}

工作流示例：完整音乐创作流程

生成歌曲 → POST /suno/submit/generate-music → 得到 task_id

轮询结果 → GET /suno/fetch/{task_id} 直到 status=succeeded

获取 audioId → 从响应 data.media[].suno_audio_id 取出音频 ID

延展音乐 → POST /suno/submit/extend-music 用 audioId 续写

转换 WAV → POST /suno/submit/convert-wav 用 taskId+audioId 转无损

创建视频 → POST /suno/submit/create-mp4 用 taskId+audioId 生成视频

人声分离 → POST /suno/submit/vocal-removal 用 taskId+audioId 分离伴奏

生成 MIDI → POST /suno/submit/generate-midi 用分离任务的 taskId 转 MIDI

查询任务状态

单个查询：GET /suno/fetch/{task_id}

批量查询：POST /suno/fetch body: {"ids":["task_id1","task_id2"]}

响应状态说明：pending/SUBMITTED(等待中)、running/QUEUED/IN_PROGRESS(处理中)、
succeeded/SUCCESS(成功)、failed/FAILURE(失败)、cancelled(已取消)。
任务成功后，媒体结果在 data.media[] 中，suno_audio_id 用于后续编辑操作。

提交 Suno 音乐任务

概览

支持的动作（action）

可用模型版本

请求体通用字段

各场景请求示例

生成歌曲（generate-music）- customMode=true

生成纯音乐（generate-music）- instrumental=true

简易模式（generate-music）- customMode=false

生成音效（generate-sounds）

生成歌词（generate-lyrics）

延展音乐（extend-music）- 自定义续写

延展音乐（extend-music）- 沿用源参数

上传并重新创作（upload-cover）

上传并延展（upload-extend）

添加伴奏（add-instrumental）

添加人声（add-vocals）

生成 Mashup（generate-mashup）

替换片段（replace-section）

转换 WAV（convert-wav）

生成 MIDI（generate-midi）- 需先完成人声分离

创建音乐视频（create-mp4）

生成封面（generate-cover）

人声分离（vocal-removal）

工作流示例：完整音乐创作流程

查询任务状态

请求参数

返回响应

提交 Suno 音乐任务

概览#

支持的动作（action）#

可用模型版本#

请求体通用字段#

各场景请求示例#

生成歌曲（generate-music）- customMode=true#

生成纯音乐（generate-music）- instrumental=true#

简易模式（generate-music）- customMode=false#

生成音效（generate-sounds）#

生成歌词（generate-lyrics）#

延展音乐（extend-music）- 自定义续写#

延展音乐（extend-music）- 沿用源参数#

上传并重新创作（upload-cover）#

上传并延展（upload-extend）#

添加伴奏（add-instrumental）#

添加人声（add-vocals）#

生成 Mashup（generate-mashup）#

替换片段（replace-section）#

转换 WAV（convert-wav）#

生成 MIDI（generate-midi）- 需先完成人声分离#

创建音乐视频（create-mp4）#

生成封面（generate-cover）#

人声分离（vocal-removal）#

工作流示例：完整音乐创作流程#

查询任务状态#

请求参数

返回响应

概览

支持的动作（action）

可用模型版本

请求体通用字段

各场景请求示例

生成歌曲（generate-music）- customMode=true

生成纯音乐（generate-music）- instrumental=true

简易模式（generate-music）- customMode=false

生成音效（generate-sounds）

生成歌词（generate-lyrics）

延展音乐（extend-music）- 自定义续写

延展音乐（extend-music）- 沿用源参数

上传并重新创作（upload-cover）

上传并延展（upload-extend）

添加伴奏（add-instrumental）

添加人声（add-vocals）

生成 Mashup（generate-mashup）

替换片段（replace-section）

转换 WAV（convert-wav）

生成 MIDI（generate-midi）- 需先完成人声分离

创建音乐视频（create-mp4）

生成封面（generate-cover）

人声分离（vocal-removal）

工作流示例：完整音乐创作流程

查询任务状态