Skip to main content
POST
POST /v1/music/generations/wav 接口已弃用。旧接口暂时兼容,等价于调用新接口并传入 formats: ["wav"];新代码请统一使用 POST /v1/music/generations/download
指定源歌曲: 传入生成源音轨时获得的 task_id,并用 audio_index 指定结果 music[] 中的第几首歌曲。audio_index 从 1 开始,默认值为 1。

认证

string
必填
所有接口均使用 Bearer Token 认证。访问 API Key 管理页面 获取 API Key。

请求参数

string
默认值:"suno"
模型名称。当前填写 suno;省略时默认为 suno
string
必填
生成源歌曲时返回的任务 ID。源任务必须:
  • 属于当前账户
  • 已完成
  • 包含可下载的音轨
音乐生成、延长、翻唱、分轨等音频任务均可作为来源;歌词、BPM 等仅返回文本的任务无法下载。
integer
默认值:"1"
要下载源任务结果 music[] 中的第几首歌曲。
  • 1 开始计数
  • 默认:1
  • 不得超过源任务实际包含的歌曲数量
string[]
要下载的文件格式数组,至少包含一项。可选值:
  • mp3
  • m4a
  • wav
支持同时请求多个格式;格式名大小写不敏感,重复值会自动去重。结果顺序与请求顺序一致。
string
只下载一种格式时,可使用此字段代替 formats示例:"format": "mp3"
formatsformat 选择一种写法即可。两者均未提供或格式列表为空时,请求会返回 HTTP 400。

提交响应

成功提交后返回下载任务自己的 task_id
返回的 data 是数组,请读取 data[0].task_id。它是新建的下载任务 ID,与请求中的源歌曲 task_id 不同。

查询下载结果

使用提交响应中的下载任务 ID 查询:
文件通常已在提交阶段准备完成,因此提交后可以立即查询一次。如果状态不是 completedfailed,再每 2 秒轮询一次,最多等待 60 秒。

下载完成

读取 result.files[] 获取下载文件:
result.wavUrl 仅用于兼容旧 WAV 接口。新代码请统一读取 result.files[]

处理中

此时没有 result 字段,请继续轮询。

下载失败

失败任务会自动退款,cost0。可向用户显示 error.message 并提供重试操作。

文件 URL

下载结果通常使用 APIMart 文件域名。少数转存失败的情况下可能返回上游 CDN 地址,该地址的有效期无法保证。
请在获得 URL 后尽快下载并保存文件,不要将临时 URL 作为长期存储地址。

错误处理

提交期参数错误会返回 HTTP 400,不创建任务、不扣费: HTTP 403 且错误码为 model_price_not_configured 时,表示后台未配置 suno@download 价格,请联系平台支持。

计费与重复下载

下载接口按请求计费:
  • 一次请求选择多个格式只收取一次费用
  • 再次提交同一首歌曲,即使格式相同,也会产生新费用
  • 下载另一种格式需要新建任务,也会产生新费用
  • 下载失败会自动退款
请保存已返回的文件 URL,并在请求处理中禁用下载按钮,避免重复提交和重复扣费。

从旧接口迁移

旧接口仍可暂时使用,但新功能和新代码应切换到 /generations/download

Response

integer
响应状态码,成功时为 200
array
提交响应数据。