Suno API 接口使用文档

完整的 Suno 音乐生成 API 使用指南

📋 接口总览

共有 5 个 API 端点，其中生成接口包含 11 个独立场景

🎵 核心接口

1. 音乐生成接口 - 11 个场景

主接口路径: /sunoapi/generate (POST)

此接口通过不同的请求体参数支持 11 个独立场景：

场景 1️⃣ - 灵感模式

描述: 仅提供灵感提示词，系统自动生成歌词、曲风、标题

关键参数: gpt_description_prompt

适用场景:

快速创作，不想自己写歌词

寻找灵感，让AI发挥创意

根据主题或情感生成音乐

请求示例:

{
  "gpt_description_prompt": "乡愁"
}

场景 2️⃣ - 自定义模式

描述: 完全自定义歌词、标题和风格

关键参数: prompt, mv, title, tags

歌词结构化标签:

[Verse] - 主歌

[Chorus] - 副歌

[Bridge] - 桥段

[Intro] - 前奏

[Outro] - 尾奏

适用场景:

已有完整歌词，需要生成音乐

对歌曲有明确的创作意图

需要精确控制歌曲的各个元素

请求示例:

{
  "prompt": "[Verse]\n连续的日子一直忙碌\n文件成堆无尽头\n\n[Chorus]\n工作工作老板的呼喊\n做完做完这才算平安",
  "mv": "chirp-v3-5",
  "title": "工作",
  "tags": "edm"
}

场景 3️⃣ - 纯音乐自定义

描述: 生成纯音乐（无人声），指定风格

关键参数: prompt="", tags, mv, title

适用场景:

需要背景音乐

创作配乐

生成器乐曲

请求示例:

{
  "prompt": "",
  "tags": "heavy metal",
  "mv": "chirp-v3-5",
  "title": "北京",
  "continue_clip_id": null,
  "continue_at": null,
  "infill_start_s": null,
  "infill_end_s": null
}

场景 4️⃣ - 纯音乐灵感

描述: 通过灵感提示生成纯音乐

关键参数: gpt_description_prompt, make_instrumental: true

适用场景:

快速生成背景音乐

根据场景或情绪生成配乐

AI自动创作器乐曲

请求示例:

{
  "gpt_description_prompt": "一首关于彻夜跳舞的国歌舞蹈流行歌曲",
  "mv": "chirp-v3-5",
  "prompt": "",
  "make_instrumental": true
}

场景 5️⃣ - 续写音频

描述: 扩展已有音频（上传或系统生成）

关键参数: continue_clip_id, continue_at

两种模式:

模式A: 续写上传的音频

必须指定 mv (chirp-v4/chirp-auk/chirp-bluejay)

设置 task: "upload_extend"

{
  "continue_clip_id": "ca94a97d-d3f2-4a63-aeee-ba3a43384bcd",
  "continue_at": 10,
  "mv": "chirp-v4",
  "task": "upload_extend",
  "prompt": "歌词",
  "tags": "",
  "title": "标题"
}

模式B: 续写系统生成的音频

不需要 mv 和 task

{
  "continue_clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "continue_at": 57,
  "prompt": "",
  "tags": "",
  "title": ""
}

适用场景:

歌曲太短，需要延长

添加新的段落

扩展已有创作

场景 6️⃣ - 混音重制

描述: 使用参考音频进行混音重制

关键参数: reference_clip_id

两种模式:

模式A: 混音上传的音频

必须指定 mv (chirp-v4/chirp-auk/chirp-bluejay)

设置 task: "upload_reference"

{
  "reference_clip_id": "ca94a97d-d3f2-4a63-aeee-ba3a43384bcd",
  "mv": "chirp-v4",
  "task": "upload_reference",
  "prompt": "描述或歌词",
  "tags": "",
  "title": "标题"
}

模式B: 混音系统生成的音频

不需要 mv 和 task

{
  "reference_clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "prompt": "",
  "tags": "",
  "title": ""
}

适用场景:

基于现有音乐创作变体

改变音乐风格但保持主题

创作混音版本

场景 7️⃣ - 替换片段

描述: 替换指定时间段的音频内容

关键参数: infill_clip_id, infill_start_s, infill_end_s

两种模式:

模式A: 替换上传音频的片段

必须指定 mv (chirp-v4/chirp-auk/chirp-bluejay)

设置 task: "upload_infill"

{
  "infill_clip_id": "ca94a97d-d3f2-4a63-aeee-ba3a43384bcd",
  "infill_start_s": 10,
  "infill_end_s": 20,
  "mv": "chirp-v4",
  "task": "upload_infill",
  "prompt": "替换后的歌词",
  "tags": "",
  "title": "标题"
}

模式B: 替换系统生成音频的片段

不需要 mv 和 task

{
  "infill_clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "infill_start_s": 0,
  "infill_end_s": 10,
  "prompt": "",
  "tags": "",
  "title": ""
}

适用场景:

修改歌曲中不满意的部分

替换特定段落

精细调整音乐内容

场景 8️⃣ - 全轨分离

描述: 分离所有音轨（人声、贝斯、鼓等）

关键参数: clip_id, task: "all-stems"

请求示例:

{
  "clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "task": "all-stems"
}

适用场景:

需要单独音轨用于混音

提取特定乐器

制作伴奏或无伴奏版本

为获取MIDI数据做准备

分离的音轨类型:

人声 (Vocals)

贝斯 (Bass)

鼓 (Drums)

其他乐器 (Other Instruments)

场景 9️⃣ - 人声分离

描述: 仅分离人声和伴奏（比全轨分离更简单）

关键参数: clip_id, task: "vocal-stems"

请求示例:

{
  "clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "task": "vocal-stems"
}

适用场景:

制作卡拉OK版本

提取清唱

获取纯伴奏

简单的音轨分离需求

分离的音轨类型:

人声 (Vocals)

伴奏 (Instrumental)

与场景8的区别:

场景8: 分离所有音轨（更详细）

场景9: 仅分离人声和伴奏（更简单）

场景 🔟 - 改写

描述: 重新生成歌曲的新版本

关键参数: clip_id, task: "rewrite"

请求示例:

{
  "clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "task": "rewrite"
}

适用场景:

对当前版本不满意，需要新版本

生成多个备选方案

探索不同的演绎方式

特点:

保持相似的主题和风格

生成全新的旋律和编曲

场景 1️⃣1️⃣ - 重新填词

描述: 保持音乐不变，重新填写歌词和风格

关键参数: overpainting_clip_id, overpainting_start_s, overpainting_end_s, task: "overpainting"

特殊要求: 必须使用 chirp-bluejay 模型

请求示例:

{
  "mv": "chirp-bluejay",
  "overpainting_clip_id": "9b1d2e8d-a365-4bfd-8a18-8989e159b29f",
  "overpainting_start_s": 0,
  "overpainting_end_s": 57.9,
  "task": "overpainting",
  "prompt": "新的歌词内容",
  "tags": "A smooth, soulful R&B track with a moderate tempo",
  "title": "新标题",
  "override_fields": ["prompt", "tags"]
}

适用场景:

喜欢旋律但想改歌词

调整歌曲的情感表达

创作不同语言版本

2. 查询结果接口

路径: /sunoapi/feed/{clipsIds} (GET)

描述: 查询一个或多个音乐生成任务的结果

使用方法:

单个查询: /sunoapi/feed/clip_id

多个查询: /sunoapi/feed/clip_id1,clip_id2,clip_id3

返回内容:

音频URL、视频URL

歌词、标题、标签

任务状态

播放次数、点赞数

元数据信息

任务状态:

submitted: 已提交

queued: 排队中

streaming: 生成中

complete: 完成

error: 错误

3. 音频上传接口

路径: /sunoapi/upload (POST)

描述: 上传自定义音频文件，用于后续操作

内容类型: multipart/form-data

参数: file (音频文件)

支持格式: mp3, wav, flac 等

clip_id: 音频的唯一标识

duration: 音频时长（秒）

后续操作:
上传后获得的 clip_id 可用于：

场景5: 续写音频 (continue_clip_id)

场景6: 混音重制 (reference_clip_id)

场景7: 替换片段 (infill_clip_id)

4. MIDI 获取接口

路径: /suno/act/midi/{clip_id} (GET)

描述: 获取音乐的MIDI数据

使用方法:

先使用场景8进行全轨分离，获得 clip_id

使用该 clip_id 调用此接口

如果返回 state: "running"，需要轮询等待

当返回 state: "complete" 时，获得完整MIDI数据

返回内容:

乐器列表 (instruments)

每个音符的 pitch, start, end, velocity

返回状态:

state: "running" - 处理中，需要轮询

state: "complete" - 完成，包含完整MIDI数据

注意事项:

建议使用全轨分离后的 clip_id

普通音乐的 clip_id 也能执行，但可能没有数据

仅支持同账号下的 clip_id

账号下线后不可调用

5. Style Tags 扩展接口

路径: /suno/act/tags (POST)

描述: 根据简单提示词扩展生成详细的音乐风格标签

参数: original_tags

请求示例:

{
  "original_tags": "student"
}

响应示例:

{
  "upsampled_tags": "Laid-back indie pop driven by a clean guitar riff, tight bass, and crisp drums. Verses feature subtle synth textures and gentle background vocals.",
  "request_id": "507acd16-8b84-4e55-be2b-4329d82efb26"
}

使用场景:

不知道如何写详细的 style tags

需要专业的风格描述

快速生成风格指导

使用方法:
返回的 upsampled_tags 可直接用于生成音乐时的 tags 参数

📊 接口分类

🎼 音乐创作类（4个场景）

场景1: 灵感模式 - 快速创作

场景2: 自定义模式 - 精确控制

场景3: 纯音乐自定义 - 背景音乐

场景4: 纯音乐灵感 - 快速配乐

🔄 音频操作类（3个场景）

场景5: 续写音频 - 延长歌曲

场景6: 混音重制 - 创作变体

场景7: 替换片段 - 精细修改

🎚️ 音频处理类（4个场景）

场景8: 全轨分离 - 完整音轨

场景9: 人声分离 - 简单分离

场景10: 改写 - 重新生成

场景11: 重新填词 - 改写歌词

🛠️ 辅助工具类（4个接口）

查询结果 - 获取生成状态

音频上传 - 上传自定义文件

MIDI获取 - 提取音符数据

Style Tags扩展 - 生成风格描述

🔄 典型工作流程

流程 1: 快速创作

1. 场景1（灵感模式）→ 提供灵感词
2. 查询结果接口 → 获取音频URL
3. 下载使用

流程 2: 精细创作

1. Tags扩展接口 → 获得详细风格描述
2. 场景2（自定义模式）→ 使用风格+歌词
3. 查询结果接口 → 获取音频

流程 3: 上传音频续写

1. 上传音频接口 → 获得 clip_id
2. 场景5（续写音频）→ 使用 clip_id 续写
3. 查询结果接口 → 获取续写结果

流程 4: 提取伴奏

1. 场景1/2 → 生成音乐
2. 场景9（人声分离）→ 分离人声和伴奏
3. 查询结果接口 → 获取分离后的音轨

流程 5: 获取MIDI

1. 场景8（全轨分离）→ 分离所有音轨
2. MIDI接口 → 获取MIDI数据（轮询直到complete）
3. 处理MIDI数据

流程 6: 混音创作

1. 上传参考音频 → 获得 reference_clip_id
2. 场景6（混音重制）→ 基于参考创作
3. 查询结果接口 → 获取混音结果

流程 7: 修改歌词保持旋律

1. 生成音乐 → 获得 clip_id
2. 场景11（重新填词）→ 使用 chirp-bluejay 重新填词
3. 查询结果接口 → 获取新版本

🎯 快速查找指南

我想生成一首新歌

有歌词: → 场景2（自定义模式）

没有歌词: → 场景1（灵感模式）

纯音乐: → 场景3/4

我想修改已有音乐

延长时长: → 场景5（续写音频）

重新混音: → 场景6（混音重制）

修改片段: → 场景7（替换片段）

换歌词: → 场景11（重新填词）

重新生成: → 场景10（改写）

我想处理音频

提取伴奏: → 场景9（人声分离）

分离所有音轨: → 场景8（全轨分离）

获取MIDI: → MIDI接口（需先全轨分离）

我不知道怎么写风格标签

使用 Tags扩展接口

📝 模型版本

版本名称	发布日期	说明	可用场景
`chirp-crow`	2025.09.23+	v5 版本	场景1-11
`chirp-bluejay`	2025.07.17+	v4.5+ 版本	场景1-11，场景11必须
`chirp-auk`	2025.05.03+	v4.5 版本	场景1-11
`chirp-v4`	-	v4 版本	场景1-11
`chirp-v3-5`	-	v3.5 版本	场景1-11

📖 认证方式

所有接口都需要在 HTTP Header 中添加：

Authorization: Bearer YOUR_API_KEY

🌟 文档特点

✅ OpenAPI 文档优势

场景独立: 11 个生成场景在文档中完全独立展示

标签分组: 使用标签将场景分组展示

完整示例: 每个场景都有完整的请求示例

详细描述: 每个场景都有使用说明、适用场景

代码示例: 提供多语言代码示例

📱 文档使用建议

使用 Swagger UI 或 Redoc 查看文档时：

每个场景都会显示为独立的接口

可以直接在文档中测试每个场景

示例代码可以直接复制使用

📋 接口路径总结

物理路径统计

序号	HTTP 方法	路径	场景数	主要功能
1	POST	`/sunoapi/generate`	11	音乐生成（多场景）
2	GET	`/sunoapi/feed/{clipsIds}`	1	查询结果
3	POST	`/sunoapi/upload`	1	上传音频
4	GET	`/suno/act/midi/{clip_id}`	1	获取MIDI
5	POST	`/suno/act/tags`	1	扩展风格标签

总计:

5 个物理路径

15 个功能场景（生成接口的 11 个场景 + 4 个其他接口）

📖 相关文档

OpenAPI 完整规范: ./suno-openapi.yaml

文档版本: 3.0
最后更新: 2025-11-12

suno api 说明

Suno API 接口使用文档#

📋 接口总览#

🎵 核心接口#

1. 音乐生成接口 - 11 个场景#

场景 1️⃣ - 灵感模式#

场景 2️⃣ - 自定义模式#

场景 3️⃣ - 纯音乐自定义#

场景 4️⃣ - 纯音乐灵感#

场景 5️⃣ - 续写音频#

模式A: 续写上传的音频#

模式B: 续写系统生成的音频#

场景 6️⃣ - 混音重制#

模式A: 混音上传的音频#

模式B: 混音系统生成的音频#

场景 7️⃣ - 替换片段#

模式A: 替换上传音频的片段#

模式B: 替换系统生成音频的片段#

场景 8️⃣ - 全轨分离#

场景 9️⃣ - 人声分离#

场景 🔟 - 改写#

场景 1️⃣1️⃣ - 重新填词#

2. 查询结果接口#

3. 音频上传接口#

4. MIDI 获取接口#

5. Style Tags 扩展接口#

📊 接口分类#

🎼 音乐创作类（4个场景）#

🔄 音频操作类（3个场景）#

🎚️ 音频处理类（4个场景）#

🛠️ 辅助工具类（4个接口）#

🔄 典型工作流程#

流程 1: 快速创作#

流程 2: 精细创作#

流程 3: 上传音频续写#

流程 4: 提取伴奏#

流程 5: 获取MIDI#

流程 6: 混音创作#

流程 7: 修改歌词保持旋律#

🎯 快速查找指南#

我想生成一首新歌#

我想修改已有音乐#

我想处理音频#

我不知道怎么写风格标签#

📝 模型版本#

📖 认证方式#

🌟 文档特点#

✅ OpenAPI 文档优势#

📱 文档使用建议#

📋 接口路径总结#

物理路径统计#

📖 相关文档#

Suno API 接口使用文档

📋 接口总览

🎵 核心接口

1. 音乐生成接口 - 11 个场景

场景 1️⃣ - 灵感模式

场景 2️⃣ - 自定义模式

场景 3️⃣ - 纯音乐自定义

场景 4️⃣ - 纯音乐灵感

场景 5️⃣ - 续写音频

模式A: 续写上传的音频

模式B: 续写系统生成的音频

场景 6️⃣ - 混音重制

模式A: 混音上传的音频

模式B: 混音系统生成的音频

场景 7️⃣ - 替换片段

模式A: 替换上传音频的片段

模式B: 替换系统生成音频的片段

场景 8️⃣ - 全轨分离

场景 9️⃣ - 人声分离

场景 🔟 - 改写

场景 1️⃣1️⃣ - 重新填词

2. 查询结果接口

3. 音频上传接口

4. MIDI 获取接口

5. Style Tags 扩展接口

📊 接口分类

🎼 音乐创作类（4个场景）

🔄 音频操作类（3个场景）

🎚️ 音频处理类（4个场景）

🛠️ 辅助工具类（4个接口）

🔄 典型工作流程

流程 1: 快速创作

流程 2: 精细创作

流程 3: 上传音频续写

流程 4: 提取伴奏

流程 5: 获取MIDI

流程 6: 混音创作

流程 7: 修改歌词保持旋律

🎯 快速查找指南

我想生成一首新歌

我想修改已有音乐

我想处理音频

我不知道怎么写风格标签

📝 模型版本

📖 认证方式

🌟 文档特点

✅ OpenAPI 文档优势

📱 文档使用建议

📋 接口路径总结

物理路径统计

📖 相关文档