Skip to main content

账户积分余额

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
  • 可跨账号
提交 AI 音乐创作任务,支持三种模式:
  • 描述模式:填写 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

请求示例 (JSON)

请求示例 (cURL)

响应示例 (200 OK)