Suno API 接口文档总览

更新于 2026-09-15 · Suno-API 团队

请从这个地址下载安装配置 suno-api agent kit  https://www.suno-api.io/suno-agent-kit.zip

获取 API Key

注册后约 1 分钟即可创建 Key，不需要手机号，也不用绑卡：

1. 打开控制台：https://www.suno-api.io/console
2. 使用邮箱注册并登录。
3. 进入「令牌管理」→「新建令牌」，复制生成的 Key。
4. 调用接口时放进请求头：Authorization: Bearer YOUR_API_KEY。

API Key 只完整显示一次，请立即保存。不要把 Key 写进前端代码、公开仓库或可被他人访问的日志。

邮箱注册即可创建 API Key，生成接口 0.6 元一次、返回 2 首歌，支持 MP3/WAV 下载、翻唱、续写、分轨与人声克隆；接口基址 https://www.suno-api.io。

本页说明当前可用的模型、全部生成与编辑接口、计费方式和推荐接入顺序；新接入建议按这里的顺序往下读，遇到 401/403/429 也有对应的排查入口。

Suno API 怎么接？ 本站使用 Suno 官方 V6 模型，提供 API Key。注册后即可创建 Key，通过 HTTP 接口调用音乐生成、查询和下载能力，无需自行申请 Suno 账号。

Suno API 使用什么模型？ 我们使用 Suno 官方模型提供 HTTP API。无需自行申请 Suno 账号，在本站注册后即可创建 API Key，直接调用官方模型的音乐生成能力；Key、计费与限流由本站统一管理。

常见问题速查

API Key 怎么获取？ 用邮箱注册后进入控制台 → 令牌管理，新建一个令牌即可，不需要手机号，也不用绑卡。

Suno API 开放平台是什么？ 它指通过一个 API Key 调用 Suno 官方模型音乐能力的开放接口平台。本站提供中文控制台、统一鉴权、异步任务查询、媒体下载和按次计费；从快速开始指南进入，Key 的创建步骤见认证说明。

API Suno 怎么调用？ 请求基址是 https://www.suno-api.io，请求头使用 Authorization: Bearer YOUR_API_KEY。先调用生成接口，再用歌曲 ID 查询任务和获取 MP3/WAV；完整路径见快速开始与歌曲查询 API。

多少钱一次？ 生成接口 0.6 元一次、返回 2 首歌；查询状态、WAV、时间轴歌词、提示词建议等接口不额外收费。

Suno API pricing 怎么计算？ 普通生成按调用次数计费，0.6 元一次固定返回 2 首；分轨、克隆音色、强化上传等编辑能力按各自单价计费，查询、WAV、时间轴歌词和媒体下载不另收费。完整价格口径见 Suno API 计费说明。

支持哪些模型？ suno-v6（默认）、suno-v6-wild、suno-v6-mini；v5.5 及更早的普通生成模型已下线，历史作品不受影响。

接口地址是什么？ https://www.suno-api.io，请求头带 Authorization: Bearer YOUR_API_KEY。

当前支持的模型

普通歌曲生成接口的对客模型只有 suno-v6、suno-v6-wild 和 suno-v6-mini，不填写 model 时默认使用 suno-v6。

普通模型 suno-v2、suno-v3、suno-v3-5、suno-v4、suno-v4-5、suno-v4-5-all、suno-v4-5-plus、suno-v5、suno-v5-5 已下线。查询历史任务时仍可能看到旧模型名，这只表示历史数据，不表示旧模型仍可用于新建请求。分轨接口是例外，详见分轨（人声伴奏分离）API。

认证方式

所有对外 API Key 接口统一使用：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

接口基础地址：

https://www.suno-api.io

通用参数填写约定

• 请求体中的 number 必须传 JSON 数字，不能传百分数字符串。例如强度 50% 应写成 0.5，不能写成 50 或 50%。
• 请求体中的 boolean 必须传 true 或 false，不要传 true、false、0、1 等替代值。
• 标记为“否”的字段可以完全不传。不确定参数含义时，优先省略字段，让服务使用默认行为；不要用空字符串、null 或 0 代替“未传”，因为 0 在部分数值字段中是有效值。
• 字段名区分拼写。各接口文档会列出推荐字段和兼容字段；新接入请按参数表原样传递。若文档说明 snake_case 与 camelCase 同时兼容，二者不要同时传。
• 所有以 _s、Seconds 结尾的时长字段单位均为秒，可以使用小数；Unix 时间戳会单独注明是秒级还是毫秒级。
• pending: 开头的 ID 是平台占位 ID，不是真实歌曲 ID。只有接口明确说明支持占位 ID 时才能使用，否则应等待返回真实 song_id。

文本字段长度上限

文本字段超限会直接返回 HTTP 400：不会进入生成、不会预扣费、也不会产生任务记录。

计数口径与 Suno 网页端完全一致：按 UTF-16 码元（等价 JS 的 String.length）——常用中文/英文算 1，emoji 与增补平面生僻字算 2；不做 trim，行首行尾空格、制表符、换行（\n 算 1）全部计入。

上限随请求里声明的模型变化（与上游 models[].max_lengths 一致）：

同名字段在不同接口可能走不同档位：description 在 /api/music/create 是 simple 提示词（3000），在 /api/music/extend 会映射成歌词 prompt（v6 = 5000），在 /api/music/sounds 则是音效描述（100）。

超限时的 message 会直接给出字段名和实测字数，按这两个数字裁剪即可定位：

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

适用接口：/api/music/create、/api/music/create/custom、/api/music/midi、/api/music/sounds、/api/music/extend、/api/music/concat、/api/music/upload-cover、/api/music/generate-from-source、/api/music/add-instrumental、/api/music/add-vocal、/api/music/add-stem、/api/music/mashup、/api/music/sample、/api/music/crop、/api/music/remove-section、/api/music/fade、/api/music/reverse、/api/music/speed、/api/music/inspo、/api/music/simple-cover、/api/music/voice-profile/cover、/api/music/speech、/api/music/replace-section、/api/music/generate-with-voice、/api/lyrics/generate、/api/music/boost-style。

唯一例外：POST /api/music/sounds 的 description（音效描述）上限是 100 字符，走的是平台更短的那条限制。

异步生成与音频地址

音乐生成接口默认按异步方式工作。首次响应中的 status 为 pending、submitted 或 processing 时，audio_url、video_url、cover_url 为空属于正常现象，不表示任务失败。请保存真实 song_id 或接口返回的 client_request_id，按对应查询文档轮询；只有状态完成后再读取和下载音频地址。

⚠️ 音频地址有效期：7 天，请及时转存

audio_url、wav_url、video_url 以及各下载接口返回的地址，都由平台的对象存储提供，默认在 7 天后失效（文件到期会被回收，继续用旧地址访问会返回 404 / 无法下载）。

• 请在拿到地址后 7 天内把文件转存到你自己的存储（自有对象存储、CDN、服务器磁盘均可），不要把我们的地址当作长期链接使用。
• 地址过期 不需要重新生成歌曲、也不会产生额外费用：重新调用歌曲查询 API（或媒体下载 API）即可拿到该歌曲新的有效地址。

等待时间与超时设置

生成类接口是同步接口：只有在响应返回时，订单才算被受理并提交给平台生成。在此之前服务端需要先完成必要的安全校验，这个过程不会有任何中间响应，也不会有其他接口能查到这一单。因此判断"有没有生成"的唯一依据是响应本身，而不是等待过程中观察到的任何现象。

实测等待时间（2026-09-18 ~ 2026-09-20 生产环境 /api/music/create 系列）

• 约 10% 的请求需要等待 30 秒以上，约 1% 需要 1–2 分钟。等待时间偏长的请求，通常是本次需要先通过一次安全检查。
• 请求字段、返回结构、错误码和计费方式都没有变化，已有接入方只需要调整客户端超时设置，不需要修改其他代码。

接入要求

1. 客户端超时请设置为 300 秒以上。默认 30 秒、60 秒、120 秒的客户端会在等待期间主动断开。
2. 未收到响应不等于没有生成。 连接超时或中断时，订单可能已经受理并正在生成。
3. 超时后不要立即重试：重复提交会产生新订单并再次扣费。
4. 如果连接中断，请稍后用 GET /api/music/songs 按时间倒序查询；已受理的订单会正常出现在列表里。确认确实没有，再重新提交。
5. 报障请附上响应头里的 X-Oneapi-Request-Id，便于直接定位到这一次请求。

不想挂长连接？用受理回执模式。 POST /api/music/create 与 POST /api/music/create/custom 支持可选的受理回执：请求体加 "accept_mode": "async"（或请求头 X-Accept-Mode: async），接口立刻返回 202 和受理号，生成在后台继续，用 GET /api/music/requests/{request_id} 查进度。这样客户端即使只有几十秒超时也不会误判"没有生成"、也不会因为重试而重复扣费。详见灵感模式生成 API 的「受理回执模式」。

参考：python requests 用 timeout=300，urllib 用 urlopen(..., timeout=300)，Node 用 req.setTimeout(300000)，curl 用 --max-time 300。

推荐接口列表

以上 /api/voice/clone/* 与 /api/music/generate-with-voice 属于早期人声克隆链路，不推荐新接入， 请改用【推荐】克隆音色 API。

高级参数：Max Mode 与 Variety

使用建议： Max Mode 是否值得开、Variety 怎么选

生成类接口都支持这两个可选参数（不传等于保持原来的行为与价格）：

支持这两个参数的接口：POST /api/music/create、POST /api/music/create/custom、 POST /api/music/extend、POST /api/music/upload-cover、POST /api/music/generate-from-source、 POST /api/music/add-instrumental、POST /api/music/add-vocal、POST /api/music/add-stem、 POST /api/music/mashup、POST /api/music/sample、POST /api/music/inspo、 POST /api/music/replace-section、POST /api/music/voice-profile/cover、POST /api/music/speech。

• max_mode 的 2 倍价格示例：默认 0.6 元/次的接口开启后为 1.2 元/次； 指定人声生成 默认 1.2 元/次，开启后为 2.4 元/次； 【推荐】克隆音色 API 的音色翻唱同样是 1.2 元/次（开启 max_mode 为 2.4 元/次）。
• variety 只对 suno-v6 系列（suno-v6、suno-v6-wild、suno-v6-mini）有效， 其它模型传了会返回 400。
• 音效生成、分轨、拼接、WAV、Studio 编辑类动作（裁剪、删减、淡入淡出、倒放、变速等） 没有这两个参数，显式传入会返回 400，避免"传了但没生效"。
• variety 是 0-4 的整数原值，与 style_weight、weirdness_constraint（0-1 小数）量纲不同。

通用歌曲返回字段

音乐生成、翻唱、续写、分离、查询等接口通常返回歌曲数组，常用字段如下：

接入四步（最小可用示例）

新接入按这四步走一遍就能拿到第一首歌；每一步的完整字段见「推荐接口列表」里对应的文档页。

# 1) 提交生成：0.6 元一次，返回 2 首
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "明亮的中文流行，钢琴前奏，温暖女声", "model": "suno-v6"}'

# 2) 轮询任务：直到 status 变成 completed（建议 3-5 秒一次）
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "第 1 步返回的 song_id"}'

# 3) 取媒体地址：读取类接口免费，可指定 song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "同一个 song_id", "kind": "song"}'

出问题时的排查入口：401 / 402 / 403 / 429 见报错清单；超时与重复扣费见下面的「等待时间与超时设置」；接口逐个说明见下面的「推荐接口列表」。

调用建议

• 新接入客户建议统一使用 suno-v6。
• 标注默认价格的接口，实际扣费以当前后台价格配置和请求模型为准。
• 生成类接口通常会先返回任务，再通过 /api/music/query 查询最终音频。
• wait_completion=true 会阻塞等待，适合低频测试；生产环境更建议异步查询。
• 生成类接口可能需要等待较长时间才返回，请把客户端超时设为 300 秒以上，并注意"未收到响应"不等于没有生成，详见上面的「等待时间与超时设置」。
• 上传、翻唱、替换、WAV 等能力依赖平台账号和源 clip 权限，失败时请优先查看返回的 message 或 error_message。

版本说明

本文档按当前 Create UI 已接入能力重新整理，推荐新接入客户优先阅读本章节。旧版接口文档仍保留在“旧版接口文档（兼容）”章节，老用户可以继续按原方式调用。