下载音频文件
- 按任务 ID 下载生成好的音频，支持多格式，异步任务
- 一次请求可以同时拿 mp3、m4a、wav
- 多格式只收一次费用
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
模型名称，省略时按 suno 处理。
生成源歌曲时返回的任务 ID。
源任务须属于当前账户、已完成、且含可下载音轨。音乐生成、延长、翻唱、分轨等任务都可以下载；只返回文本的任务（歌词、BPM 等）不可下载。
指定源任务结果 data.result.music[] 中的第几首，默认 1，从 1 开始计数。越界会报错。
要下载的格式数组，至少一项。取值 mp3、m4a、wav。
可多选，大小写不敏感，重复值自动去重，结果顺序与请求顺序一致。与 format 二选一。
只下载单一格式时代替 formats 使用，例如 "mp3"。
formats 与 format 均缺失或列表为空时返回 400。
The model name; treated as suno when omitted.
The task ID returned when the source song was generated.
The source task must belong to the current account, be completed, and contain downloadable tracks. Music generation, extension, cover, and stem tasks can all be downloaded; tasks that return only text (lyrics, BPM, etc.) can't.
Which track in the source task's data.result.music[], default 1, counting from 1. Out of range returns an error.
The array of formats to download, at least one. Values: mp3, m4a, wav.
Multiple are allowed, case-insensitive, duplicates are de-duplicated automatically, and the result order follows the request order. Mutually exclusive with format.
Used in place of formats when downloading a single format, e.g. "mp3".
Both missing, or an empty list, returns a 400.
提交响应
状态码，成功为 200。
初始值固定为 submitted。
新建的下载任务 ID，与请求中的源歌曲 task_id 不同。轮询时用这个。
这一步容易搞混：提交下载后返回的是一个新任务 ID。拿原来的 task_id 去查，永远查不到下载结果。
The status code; 200 on success.
Fixed at submitted initially.
The new download task's ID, which differs from the source song's task_id in the request. Poll with this one.
This step is easy to mix up: submitting a download returns a new task ID. Querying with the original task_id will never find the download result.
查询下载任务
用 GET /v1/music/tasks/{下载任务ID}。建议提交后立即查一次，非终态则每 2 秒轮询，最多 60 秒。
任务状态，取值 submitted、processing、completed、failed。
进度百分比。
创建时间，Unix 时间戳。
完成时间，Unix 时间戳，仅完成时出现。
实际耗时，单位秒。
费用。失败任务为 0。
积分消耗。
结果对象，仅 completed 状态存在，processing 时没有这个字段。
歌曲唯一标识。
下载文件列表，新代码应读取这个字段。
文件格式。
文件下载地址。可能有有效期，需尽快保存。
兼容旧 WAV 接口的字段，请求 WAV 时仍可能返回。不建议新代码使用。
失败原因，可展示给用户并提供重试。
Use GET /v1/music/tasks/{download task ID}. Query once right after submitting; if not in a terminal state, poll every 2 seconds for up to 60 seconds.
The task status: submitted, processing, completed, or failed.
The progress percentage.
The creation time as a Unix timestamp.
The completion time as a Unix timestamp; present only when completed.
The actual elapsed time in seconds.
The cost. Zero for failed tasks.
The credits consumed.
The result object, present only in the completed state; absent while processing.
The unique song identifier.
The list of downloaded files; new code should read this field.
The file format.
The file download address. It may expire, so save it promptly.
A compatibility field for the old WAV endpoint, may still appear when requesting WAV. Not recommended for new code.
The failure reason; can be shown to the user with a retry option.
计费规则
| 情况 | 计费 |
|---|---|
| 一次请求选多个格式 | 只收一次费用 |
| 再次提交同一首歌，即使格式相同 | 产生新费用 |
| 换另一种格式下载 | 需新建任务，也产生新费用 |
| 下载失败 | 自动退款，cost 为 0 |
所以想拿多个格式，一次请求全选上最划算。分两次下载同一首歌会被收两遍钱。
| Case | Billing |
|---|---|
| Several formats in one request | Charged only once |
| Resubmitting the same song, even the same formats | Incurs a new charge |
| Downloading in a different format | Requires a new task and incurs a new charge |
| Download fails | Refunded automatically; cost is 0 |
So when you want several formats, selecting them all in one request is cheapest. Downloading the same song in two requests costs twice.
错误处理
HTTP 400 属于提交期参数错误，不创建任务、不扣费。常见对照：
| 错误信息 | 含义 |
|---|---|
formats is required / must contain at least one | 未提供下载格式 |
unsupported format | 包含 mp3、m4a、wav 之外的格式 |
task_id is required / invalid task_id format | 源任务 ID 缺失或格式错误 |
source task not found | 源任务不存在或不属于当前账户 |
audio_index N out of range | 歌曲序号超出源任务音轨数量 |
track #N has no music_id | 源任务未完成或该歌曲无音频 |
| HTTP | 说明 |
|---|---|
| 401 | 身份验证失败，检查 API 密钥 |
| 402 | 账户余额不足，需充值 |
| 403 | 模型价格未配置，错误码 model_price_not_configured，需联系平台支持 |
| 429 | 请求过于频繁，稍后重试 |
| 500 | 服务器内部错误，稍后重试 |
旧接口 POST /v1/music/generations/wav 已弃用，暂仍兼容，等价于新接口传 formats: ["wav"]。新代码请用本接口。
HTTP 400 means a parameter error at submission time — no task is created and nothing is charged. Common cases:
| Message | Meaning |
|---|---|
formats is required / must contain at least one | No download format supplied |
unsupported format | A format other than mp3, m4a, wav was included |
task_id is required / invalid task_id format | Source task ID missing or malformed |
source task not found | The source task doesn't exist or belongs to another account |
audio_index N out of range | The track index exceeds the source task's track count |
track #N has no music_id | The source task isn't complete, or that track has no audio |
| HTTP | Notes |
|---|---|
| 401 | Authentication failed; check the API key |
| 402 | Insufficient account balance; top up |
| 403 | Model price not configured, error code model_price_not_configured; contact platform support |
| 429 | Too many requests; retry later |
| 500 | Internal server error; retry later |
The old endpoint POST /v1/music/generations/wav is deprecated but still temporarily supported; it's equivalent to the new endpoint with formats: ["wav"]. New code should use this endpoint.
错误码
For error response formats, status codes, and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
提交一个任务并拿到 task_id：
提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。
Submit a task and get a task_id:
A successful submission only means the task was accepted. To get the actual output, poll the task query endpoint with the returned task_id; results appear only after status becomes completed.