Suno API 文档

Suno API 提供专业的、无水印的音乐生成服务，具有快速流式输出和高性价比 - 是完美的无缝音频 API 集成选择。

API 服务概览

我们目前提供以下 API 服务：

音乐生成 (Music Generation)
- 用于创建和管理音乐生成任务的接口
- 支持自定义模式和非自定义模式
- 支持生成带歌词或纯音乐
- 包含延长现有音乐的功能
- 提供多种模型版本 (V3_5, V4)
- 获取带时间戳的歌词用于同步显示
歌词生成 (Lyrics Generation)
- 用于歌词生成和管理的接口
- 根据提示生成歌词内容，无需生成音频
- 返回多个歌词变体供选择
WAV 格式转换 (WAV Conversion)
- 用于将音乐转换为WAV格式的接口
- 生成高质量、无损的 WAV 文件，适合专业编辑
人声移除 (Vocal Removal)
- 用于从音乐轨道中移除人声的接口
- 将音频分离为人声和伴奏两个独立轨道
音乐视频生成 (Music Video Generation)
- 用于生成MP4视频的接口
- 为音频添加可视化效果，生成 MP4 文件
- 可选添加作者和域名水印
账户管理 (Account Management)
- 用于账户和积分管理的接口
- 查询当前账户剩余积分

基本信息

API 服务器：https://apibox.erweima.ai
API 版本：1.0.0
技术支持：[email protected]

在使用 API 之前，请确保：

从 API 密钥管理页面获取您的 API 密钥
查看认证指南

入门指南

认证

所有 API 请求都需要使用 Bearer Token 认证。请在请求头中添加：

Authorization: Bearer YOUR_API_KEY

参考 API 认证说明获取更多细节。

重要提示：

保持 API 密钥安全，切勿泄露
如怀疑密钥泄露，请立即在管理页面重置

错误处理

我们的 API 使用标准 HTTP 状态码。响应体中的 code 字段提供了更详细的状态信息：

`code`	描述	说明
✅ 200	请求成功	操作成功完成。
⚠️ 400	参数错误	请求中提供的参数无效或缺失。
⚠️ 401	没有访问权限	API Key 无效、缺失或权限不足。
⚠️ 404	请求方式或者路径错误	请求的 API 路径或 HTTP 方法不正确。
⚠️ 405	调用超过限制	API 调用频率超过了允许的速率限制。
⚠️ 413	主题或者prompt过长	提供的文本（如 prompt, style, title）超过限制。
⚠️ 429	积分不足	账户积分余额不足以执行请求的操作。
⚠️ 455	网站维护	系统正在进行维护，请稍后再试。
❌ 500	服务器异常	服务器内部发生未知错误。

当 code 不为 200 时，响应体中的 msg 字段会提供具体的错误信息。

API 服务详情

音乐生成

此服务包含创建、延长和查询音乐生成任务的功能。

生成音乐: 使用 AI 模型生成带有或不带歌词的音乐。支持 customMode (自定义模式) 和非自定义模式，提供 V3_5 和 V4 模型。新用户推荐使用非自定义模式快速体验。
延长音乐: 延长或修改现有音乐作品。可以选择使用默认参数或自定义参数进行延长。
获取音乐生成详情: 查询音乐生成任务的状态和结果。状态包括 PENDING, TEXT_SUCCESS, FIRST_SUCCESS, SUCCESS, CREATE_TASK_FAILED, GENERATE_AUDIO_FAILED, CALLBACK_EXCEPTION, SENSITIVE_WORD_ERROR。
获取带时间戳的歌词: 获取与音频同步的带时间戳的歌词数据，可用于卡拉OK式显示。

了解更多关于音乐生成 →

歌词生成

独立生成歌词内容，无需伴随音频。

生成歌词: 根据提供的 prompt 生成歌词文本，通常包含歌曲结构标记（如 [Verse]）。返回多个歌词变体。
获取歌词生成详情: 查询歌词生成任务的状态和结果。状态包括 PENDING, SUCCESS, CREATE_TASK_FAILED, GENERATE_LYRICS_FAILED, CALLBACK_EXCEPTION, SENSITIVE_WORD_ERROR。

了解更多关于歌词生成 →

WAV 格式转换

将已生成的音乐文件转换为高质量的 WAV 格式。

转换为WAV格式: 提供 taskId 或 audioId 将对应的 MP3 音频转换为 WAV。WAV 格式适合专业音频编辑和制作。
获取WAV转换详情: 查询 WAV 转换任务的状态和结果。状态包括 PENDING, SUCCESS, CREATE_TASK_FAILED, GENERATE_WAV_FAILED, CALLBACK_EXCEPTION。

了解更多关于 WAV 转换 →

人声移除

将现有音频文件分离为人声和伴奏两个轨道。

创建人声分离任务: 提供 taskId 和 audioId 来分离指定音频。
获取人声分离详情: 查询人声分离任务的状态和结果。状态包括 PENDING, SUCCESS, CREATE_TASK_FAILED, GENERATE_AUDIO_FAILED, CALLBACK_EXCEPTION。回调会返回原始音频、人声和伴奏的 URL。

了解更多关于人声移除 →

音乐视频生成

将音频文件转换为带可视化效果的 MP4 视频。

创建音乐视频: 提供 taskId 和 audioId 生成 MP4 视频。可以添加作者名和域名作为水印（长度限制50字符）。
获取音乐视频详情: 查询 MP4 视频生成任务的状态和结果。状态包括 PENDING, SUCCESS, CREATE_TASK_FAILED, GENERATE_MP4_FAILED, CALLBACK_EXCEPTION。

了解更多关于 MP4 视频生成 →

账户管理

管理您的 API 积分。

获取账户积分: 查询当前账户剩余的积分余额。建议在执行消耗积分的操作前检查余额，避免因积分不足（错误码 429）导致任务失败。

了解更多关于账户管理 →

最佳实践

回调处理
- 确保您的 callBackUrl 是公网可访问的。
- 实现健壮的回调处理逻辑，处理不同任务类型的回调结构和可能的回调阶段（如音乐生成的 text, first, complete）。注意某些阶段可能被跳过。
- 建议在回调接口中实现幂等性处理，防止重复处理同一任务的回调通知。
- 如果不想依赖回调，可以使用相应的 "获取详情" 接口主动轮询任务状态。
参数使用与限制
- 仔细阅读各接口的参数说明，特别是条件必填字段（如音乐生成中的 prompt, style, title 取决于 customMode 和 instrumental 的值）。
- 注意文本长度限制（如 prompt, style, title, MP4水印的 author, domainName）。
- 延长音乐时，模型版本 (model) 必须与源音频一致。
错误处理与资源管理
- 实现适当的错误处理逻辑，根据响应 code 和 msg 进行判断。
- 对于 500 服务器错误或可能的网络问题，可以考虑实施重试机制。
- 定期通过 "获取账户积分" 接口监控积分余额，避免服务中断。
- 所有生成的文件（音乐、歌词、WAV、人声分离结果、MP4）将在服务器上保留 15 天，请及时下载所需文件。
性能与效率
- 对于音乐生成，如果需要带时间戳的歌词，请调用 "获取带时间戳的歌词" 接口。
- WAV 文件通常比 MP3 文件大很多，仅在需要高质量或进一步处理时选择转换。

需要帮助？

如果您遇到任何问题或有疑问，请通过以下方式联系我们：

📧 电子邮件：[email protected]
💬 在线支持：控制台
📚 API 参考：完整文档

语言支持

本文档提供英文和中文两种语言版本。您可以使用导航栏中的语言选择器切换语言。

API 服务概览​

基本信息​

入门指南​

认证​

错误处理​

API 服务详情​

音乐生成​

歌词生成​

WAV 格式转换​

人声移除​

音乐视频生成​

账户管理​

最佳实践​

需要帮助？​