Suno API 下载 MP3 与 WAV：地址、鉴权和转存

直接答案：歌曲完成后，先用 POST /api/music/download-url 拿播放或转存地址，或直接用 POST /api/music/download-file 以流的方式落盘。两种接口都免费；地址默认约 7 天有效，长期交付必须在有效期内复制到自己的对象存储。

先选对下载入口

拿 MP3 地址

curl -X POST "https://www.suno-api.io/api/music/download-url"   -H "Authorization: Bearer $SUNO_API_KEY"   -H "Content-Type: application/json"   -d '{"song_id":"YOUR_SONG_ID","kind":"song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "YOUR_SONG_ID",
    "kind": "song",
    "url": "https://media.example.com/assets/song.mp3",
    "nav_url": "https://media.example.com/assets/song.mp3?...attachment"
  }
}

url 适合播放或程序转存；nav_url 带 attachment 下载头，适合国内手机浏览器直接落盘。不要把 API Key 拼进这两个媒体 URL。

服务端直接保存 MP3

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

响应体是文件流，不是 JSON；文件名可从 Content-Disposition 读取。先在临时目录落盘，校验响应状态和文件大小，再移动到正式存储，避免半截文件被当成成功产物。

Python 流式转存

import requests

BASE = "https://www.suno-api.io"
headers = {"Authorization": f"Bearer {API_KEY}"}
song_id = "YOUR_SONG_ID"

with requests.post(
    f"{BASE}/api/music/download-file",
    headers=headers,
    json={"song_id": song_id, "kind": "song"},
    stream=True,
    timeout=(15, 180),
) as response:
    response.raise_for_status()
    with open("song.mp3.part", "wb") as fh:
        for chunk in response.iter_content(chunk_size=1024 * 256):
            if chunk:
                fh.write(chunk)

print("saved", song_id)

生产环境还应在文件完成后计算大小或哈希，再改名为正式文件；不要直接把正在写入的路径返回给用户。

WAV、视频、封面与歌词

7 天有效期怎么处理

1. 歌曲进入 completed 或 playable 后立即下载或转存。
2. 业务数据库保存自己的对象存储 key，不要只保存上游临时 URL。
3. 用户再次请求下载时先检查自己的长期副本。
4. 没有长期副本且旧链接 404 时，重新调用 download-url 或歌曲查询获取新地址。
5. 地址过期不等于歌曲丢失，不需要重新生成，也不会重复扣生成费。

常见问题

MP3 和 WAV 下载收费吗？

媒体下载接口免费。WAV 的准备工作取决于对应接口规则，但下载这一步不会重复扣歌曲生成费。

媒体地址为什么返回 404？

临时对象默认约 7 天后回收，或资源尚未准备成功。先刷新地址，再检查 kind 与资源准备状态。

应该用 download-url 还是 download-file？

需要公开播放或自行转存时用 download-url；需要服务端直接拿 bytes 落盘时用 download-file。歌词必须用 download-file。

继续阅读：媒体下载 API、WAV API、批量生成队列、返回字段详解。

← 返回全部文章