歌曲媒体下载与试听 API

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

接口说明

这一组接口把「拿媒体地址」和「真正下载文件」分开：

• 想拿一个可以直接播放/下载的地址（例如放进自己的播放器或转存到对象存储）：用 POST /api/music/download-url，或响应里已经给出的 GET /api/music/download。
• 想让浏览器直接落盘保存文件：用 POST /api/music/download-file（单文件）或 POST /api/music/download-all（打包）。
• 歌曲还在生成中、想先试听：用 POST /api/music/generation-stream-url。

计费：全部免费。下载与试听只读取平台已托管的媒体，不调用 Suno，不扣费。

推荐模型：suno-v6。可用 suno-v6、suno-v6-wild 或 suno-v6-mini。

认证

支持的媒体类型（kind）

1）获取媒体地址

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"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url 用于播放或自行转存；nav_url 带 Content-Disposition: attachment， 适合直接赋给浏览器地址栏下载（部分国内手机浏览器不支持 blob 下载时使用）。

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

url / nav_url 指向平台的对象存储，默认在 7 天后失效（文件到期回收，旧地址会返回 404）。请在这 7 天内把文件转存到自己的存储。

过期后不必重新生成歌曲：重新调用 POST /api/music/download-url（或把 refresh 传 true）即可拿到该歌曲新的有效地址，本组接口本身免费、不额外计费。

2）直接下载单文件

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

响应体是文件流（不是 JSON），Content-Disposition 已经带好文件名。 歌词与时间轴歌词只能用这个接口取。

3）打包下载

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

song_id（单个）与 song_ids（批量，最多 50 条）二选一。响应体是 ZIP 文件流。

4）稳定下载地址

GET /api/music/download?song_id=<id>&kind=<kind> 是歌曲响应里直接给出的下载入口， 鉴权同时支持 API Key 与登录态，行为等价于 download-file，适合写死进客户端或第三方播放器。

5）生成中试听

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

playable_until_completed 为 true 表示这是生成中的临时试听地址，歌曲完成后请改用正式地址； 单首失败时该项会带 error 字段，其余歌曲照常返回。

注意事项

• 所有接口都只返回平台托管的媒体地址，不会返回 Suno 上游的加密源或临时签名地址。
• 地址不是永久有效的，长期保存请自行转存；需要原文件落盘时用 download-file。
• 分轨轨道的 MIDI 需要该轨道已完成分离，否则返回错误。