CQTAI
Suno · 音乐

单曲下载NEW

📌 这是什么：把 Suno 上的一首歌下载成可保存的音频文件：官方页面上的音频是加密流，直接存下来是乱码；本接口把它还原成完整音频并转存到我方 CDN，返回一条能直接下载的直链。
💡 什么时候用：需要把成品歌曲保存到本地、投放到自己的播放器/剪辑软件，或做二次处理时用。三种给歌方式任选：歌曲片段 ID、Suno 歌曲页地址，或直接给平台的 suno 任务 ID（自动反查这个任务出的歌，省得先查一次结果拿 ID）。支持任意公开歌曲（不限于你自己创作的），单曲上限 64MB。
⚡ 同步接口：一次请求直接返回下载直链，不用再轮询查结果。正常耗时 5~20 秒（取回 + 转存），请把客户端超时设到 60 秒以上。

接口地址

用途方法路径
同步调用POST/api/cqt/v2/suno/download

请求参数

参数类型必填说明
clipIdstring—歌曲片段 ID。clipId / url / taskId 三选一，必须传其中一个（同时传时优先级 clipId > url > taskId）
urlstring—Suno 歌曲页地址，如 https://suno.com/song/<clipId>，系统自动提取 ID（三选一）
taskIdstring—平台的 suno 任务 ID（即提交生成后拿到、用 GET /api/cqt/info/suno?id= 查结果的那个），自动反查该任务出的歌曲 ID（三选一）。查得到结果就下得到，同样不校验任务归属；导出类任务（mp4 / wav / 时间轴 / 节拍）没有歌曲列表时，自动取该任务提交时用的歌曲 ID
clipIndexnumber—配合 taskId 使用：一个生成任务通常出 2 首，选第几首（从 0 开始，默认 0）。一次调用只下一首；越界时错误信息会告诉你这个任务实际有几首

请求示例

curl -X POST https://api.cqtai.com/api/cqt/v2/suno/download \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "clipId":"e1a78bfe-2e53-4207-9cd8-c764c4bfc621" }'
# 也可以直接传歌曲页地址：
#  -d '{ "url":"https://suno.com/song/e1a78bfe-2e53-4207-9cd8-c764c4bfc621" }'
# 或者用平台的 suno 任务 ID 反查（clipIndex 选第几首，默认 0）：
#  -d '{ "taskId":"<task id>", "clipIndex":1 }'
# -> { "code":200, "data":{ "url":"https://<cdn>/suno-download/....m4a", "format":"m4a", ... } }

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "clipId": "e1a78bfe-2e53-4207-9cd8-c764c4bfc621",
    "title": "两只老虎",
    "url": "https://cdn.cqtai.com/suno-download/1757300000000_ab12cd34.m4a",
    "format": "m4a",
    "bytes": 4213760,
    "cached": false
  }
}

响应字段说明

字段类型说明
codenumber状态码，200 表示成功；非 200 时 msg 为失败原因，积分全额退回
msgstring提示信息
data.clipIdstring歌曲片段 ID
data.titlestring歌曲名
data.urlstring可直接下载的音频直链（CDN）
data.formatstring文件格式，m4a 或 webm
data.bytesnumber文件字节数
data.cachedbool是否命中缓存（缓存 30 天）。true 表示直接复用上次的文件，返回更快；计费不变

常见错误

msg含义
param_invalid: clipId, url or taskId is required三个入参一个都没给（以下 param_invalid 全部在扣费前拦截，不计费）
param_invalid: unrecognized clipId: ...传的既不是歌曲片段 ID 也不是 Suno 歌曲页地址
param_invalid: task not found: ...平台里没有这个 suno 任务 ID
param_invalid: task has no clip yet, status=running这个任务还没出结果，等它完成后再下载
param_invalid: clipIndex out of range, this task has N clip(s)clipIndex 超出范围，N 是这个任务实际的歌曲首数（从 0 开始数）
clip not found: ...歌曲页打不开、或页面里没有音频地址（歌曲不存在或未公开）
rights unavailable: ...这首歌未授予下载许可（受限或暂不可下载），换一首或稍后重试
decrypt failed还原出的内容不是可识别的音频文件 —— 宁可报错也不会把坏文件当成品返回
Points insufficient积分余额不足
The request is too fast. Please try again later同时下载的请求已达上限（默认 5 个并发），稍后重试；此情况不扣费