歌曲媒体下载与试听 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 已经带好文件名。 歌词与时间轴歌词只能用这个接口取（download-url 只返回媒体地址，不返回歌词）。 其中 .lrc 文件目前仅部分歌曲支持；若返回 success:false，请按下一节用 时间轴歌词 API 自行生成 .lrc，不要重试。

时间轴歌词（.lrc）怎么取

推荐用两步，任何歌曲都适用：

第一步：取逐词时间轴（免费）

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

返回直接就是数组（没有 data 外层包装），每个元素形如 {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}。 word 里已经带换行，可按行拆开；字段含义、器乐段过滤等注意点见 时间轴歌词 API 的「字段说明」「使用注意」。

第二步：用 start_s 自行拼 .lrc（时间格式 [mm:ss.cc]）

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc 也可以直接下载服务端生成的 .lrc， 但目前仅部分歌曲支持：如果返回 success:false，请改用上面这种方式自行生成， 不需要重试、也不影响计费。

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 需要该轨道已完成分离，否则返回错误。