账户积分余额
GET /suno/account/integral
查询 Suno 渠道账户剩余积分。
请求示例 (cURL)
响应示例 (200 OK)
生成 MIDI
GET /suno/act/midi
根据 clipId 与 stemClipId 生成 MIDI 数据。
请求参数 (Query / Path)
string
required
音频 / 视频 clip ID
string
required
分轨 stem 的 clip ID
请求示例 (cURL)
响应示例 (200 OK)
MP4 生成状态
GET /suno/act/mp4-state
按 taskBatchId 查询 MP4 视频生成进度与状态。
请求参数 (Query / Path)
string
required
任务批次 ID
请求示例 (cURL)
响应示例 (200 OK)
获取音乐风格
GET /suno/act/music-style
查询账号下的音乐风格/作品列表(Open 渠道)。
请求示例 (cURL)
响应示例 (200 OK)
我的音乐列表
GET /suno/act/my-musics
分页查询当前账号下的音乐作品列表。
请求参数 (Query / Path)
string
页码(从 1 开始)
string
每页条数
请求示例 (cURL)
响应示例 (200 OK)
Timing:歌词、音频时间线
GET /suno/act/timing/{id}
查询 clip 的歌词与音频时间线对齐数据。
请求参数 (Query / Path)
string
required
clipId
请求示例 (cURL)
响应示例 (200 OK)
获取wav
GET /suno/act/wav/{clip_id}
获取指定 clip 的 WAV 音频资源。
请求参数 (Query / Path)
string
required
clipId
请求示例 (cURL)
响应示例 (200 OK)
波形图数据
GET /suno/act/waveform
获取指定 clip 的波形图数据。
请求参数 (Query / Path)
string
required
音频 / 视频 clip ID
请求示例 (cURL)
响应示例 (200 OK)
查询单个任务
GET /suno/fetch/{id}
GET 轮询入口;id 为提交任务返回的 task_id。
查询单个任务或片段的详细状态,包括音频 URL、歌词等。
请求参数 (Query / Path)
string
required
task_id 或上游要求的查询 ID
请求示例 (cURL)
响应示例 (200 OK)
查询任务状态
POST /suno/fetch
轮询入口之一。请求体为 task_id / clip id 列表(ids)。
注意:task_id 用于轮询任务;clip_id 用于续写/补段等,二者勿混用(API-Doc-Standards §2.4)。
根据任务 ID 列表批量查询任务或作品状态。
请求体参数 (Body)
string
可选;多数场景仅传 ids 即可
array
required
task_id 或 clip_id 列表
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
调整播放速度
POST /suno/submit/adjust-speed
同步调整播放速度,0 积分。
请求体参数 (Body)
string
required
歌曲 clipId
boolean
是否保持音调
number
required
播放速度 0.25~4.0
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
生成歌曲(拼接歌曲)
POST /suno/submit/concat
续写歌曲后再拼接成完整曲目。
请求体参数 (Body)
string
required
续写返回的 clipId
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
Fade 淡入淡出
POST /suno/submit/fade
同步 fade 处理,0 积分。
请求体参数 (Body)
string
required
歌曲 clipId
number
淡入秒数
number
淡出秒数
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
生成歌词
POST /suno/submit/lyrics
根据主题或关键词生成歌词文本。
请求体参数 (Body)
string
required
歌词主题/关键词
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
生成 MP4 视频
POST /suno/submit/mp4
生成 MP4 视频,0 积分,异步。
请求体参数 (Body)
string
required
歌曲 clipId
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
创建音乐
POST /suno/submit/music
等价于 POST /suno/submit/“ 且 action=music(路由参数见 manifest)。
支持模型(mv):用户侧可复制 ID(与下方 examples 对齐;chirp-auk / chirp-fenix 仅为别名):
- chirp-v3-0(对应版本 v3.0)
- chirp-v3-5(对应版本 v3.5)
- chirp-v4(对应版本 v4.0)
- chirp-v4-5(对应版本 v4.5;别名 chirp-auk)
- chirp-v5(对应版本 v5.0)
- chirp-v5-5(对应版本 v5.5;别名 chirp-fenix)
- chirp-v6(对应版本 v6.0)
- chirp-v6-wild(对应版本 v6-wild)
- chirp-v6-mini(对应版本 v6-mini)
gpt_description_prompt 与 prompt,以网关/上游实际分支为准(勿当作简单二选一可同时填)。详见 API-Doc-Standards §2.3。
clip 续写:continue_clip_id 须来自先前 fetch 返回的 clip/song,不可自造。
接入步骤
A. 生成音乐
可以通过场生成歌曲接口生成后,获取其中的一首歌的clip_id 值为: 54834687-5e79-4f08-8e14-cf188f15b598
B. 新建 Persona
clip_id需要系统内存在的,非 uploader- 不能跨账号,所以可能账号下线用不了
C. 使用 persona_id 创作
注意事项:- mv 为
chirp-v3-5-tau或者chirp-v4-tau - task 为
artist_consistency - persona_id 为 B 步骤得到的
- artist_clip_id 就是 A 步骤中的
clip_id - 可跨账号
- 描述模式:填写
gpt_description_prompt,AI 自动生成音乐风格与歌词 - 自定义模式:填写
prompt(歌词)+tags(风格标签),精确控制创作方向 - 纯音乐模式:设置
make_instrumental: true,生成无歌词背景音乐 - 续写模式:填写
continue_clip_id+continue_at,延续已有片段
请求体参数 (Body)
string
源曲 clip_id(步骤 A 生成音乐后从 fetch 结果取得)。task=artist_consistency 时必填,且应与创建 Persona 时使用的 root_clip_id 为同一首源曲。须为系统内已生成 clip,非 uploader 临时 ID。
number
从源音频第几秒开始续写(配合 continue_clip_id)
string
续写/补段用的源 clip ID。须为已生成歌曲的 clip_id(从 GET /suno/fetch/:id 结果获取),非 task_id
string
灵感模式:用自然语言描述想要的音乐风格/主题(与 prompt 二选一,优先灵感)
boolean
是否生成纯音乐(无人声)
object
扩展字段;可通过 metadata.task 或 metadata.metadata_params 传参(与顶层二选一即可)
object
Open 渠道扩展参数,按 task 传不同子字段;未列出的键可能透传上游
string
模型版本;不传默认 chirp-v5。另支持 chirp-v6 / chirp-v6-wild / chirp-v6-mini。task=artist_consistency 时仅建议 chirp-v3-5-tau 或 chirp-v4-tau
string
Persona ID。仅 task=artist_consistency 时必填。须先 POST /suno/submit/persona 创建成功后从 fetch 结果获取;无固定枚举,不可手写假 UUID。Persona 与创建账号绑定,不可跨账号复用创建步骤。
string
自定义模式:新歌歌词;续写/补段/重制/混搭等也常用。task=remaster 时上游必填
string
风格标签,逗号分隔,如 “pop, piano, emotional”。可空
string
特殊任务类型;不传则为普通生成(灵感/自定义/纯音乐)
string
关联原任务 ID,用于渠道路由(可选)
string
歌曲标题
请求示例 (cURL)
响应示例 (200 OK)
创建歌手风格(Persona)
POST /suno/submit/persona
基于已生成 clip 创建 Persona,供 task=artist_consistency 等场景复用歌手音色。
请求体参数 (Body)
string
required
源歌曲 clipId;也可用 clip_id
string
required
风格描述;可改用 tags
integer
required
人声片段结束秒,须大于 start
integer
required
人声片段起始秒
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
重新生成封面图
POST /suno/submit/regen-img
重新生成封面,0 积分,异步。
请求体参数 (Body)
string
required
任务 taskBatchId
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
修改标题/封面
POST /suno/submit/set-metadata
同步修改标题与封面
请求体参数 (Body)
string
required
音频 / 视频 clip ID
string
required
新封面 URL
string
required
新标题
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
全轨12路分离(URL)
POST /suno/submit/stems-all-by-url
按 URL 全轨分离,0 积分,异步。
请求体参数 (Body)
string
required
音频文件 URL
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
全轨12路分离(clipId)
POST /suno/submit/stems-all
全轨 12 路分离,异步。返回 taskBatchId。
请求体参数 (Body)
string
required
歌曲 clipId
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
人声/伴奏分离(URL)
POST /suno/submit/stems-by-url
按 URL 分离人声与伴奏,0 积分,异步。
请求体参数 (Body)
string
required
音频文件 URL
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
人声/伴奏分离(clipId)
POST /suno/submit/stems
按 clipId 分离人声与伴奏,0 积分,异步。返回 taskBatchId,用查询接口轮询。
请求体参数 (Body)
string
任务完成回调地址,留空表示不回调
string
required
歌曲 clipId
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
提升音乐风格
POST /suno/submit/upsample-tags
将简短风格描述扩展为更丰富的 tags 提示词。
请求体参数 (Body)
string
required
原始风格描述
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
资源转临时地址
POST /suno/submit/url-transfer
将资源 URL 转为临时可访问地址,0 积分,同步。
请求体参数 (Body)
string
required
原始资源 URL
请求示例 (JSON)
请求示例 (cURL)
响应示例 (200 OK)
上传版权歌曲
POST /suno/uploads/audio
上传版权音频到 Suno,用于后续续写或 Persona 等操作。
请求体参数 (Body)
string
required
歌曲名称
number
required
上传前调整速度,取值范围 [0.25, 2.0]
boolean
required
是否修复速度。true=修复回原速;false=保留调速后的速度
string
required
上传类型。NORMAL=普通上传(免费);MUSIC_COPYRIGHT=版权上传(消耗 30 积分)。本接口填 MUSIC_COPYRIGHT
string
required
参考音频文件的源 URL,如 https://cdn1.suno.ai/xxx.mp3