Suno 通用约定与任务查询

任务查询：GET /v1/music/tasks/:task_id，轮询直到 completed / failed

信息

本页是所有 Suno 音乐接口的公共约定，配合每个端点单独文档使用。所有生成 / 编辑接口均为异步任务：提交拿 task_id，再轮询本页的查询接口取结果。

认证

所有请求都需要在请求头中携带：

Authorization: Bearer <你的API Key>
Content-Type: application/json

访问 API Key 管理页面获取 API Key。

任务生命周期（所有接口均为异步）

1. 提交

POST /v1/music/generations/<操作> → 立即返回 task_id：

{ "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }

2. 轮询

GET /v1/music/tasks/:task_id 直到 status 为 completed 或 failed。生成中 status 为 pending，progress 排队 10 → 就绪 50 → 完成 100。建议轮询间隔 3–5s；音乐生成通常 30–120s。

3. 取结果

完成后从 data.result.music[] 取 audio_url / image_url / video_url 等。

任务状态流转：submitted → pending → completed / failed。失败时 data.error.message 给出原因，且预扣额度自动退回。

版本 version

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5，影响音质与计费；不传使用默认。各端点的可用版本与默认值不同——部分端点只支持子集，部分端点无版本维度；以各端点自身文档为准。

引用源音轨：task_id + audio_index

基于已有歌曲的操作（续写 / 翻唱 / 分轨 / 加人声 / 裁剪…）不需要记任何额外 id，只传：

task_id：产出源音轨那次任务的 task_id
audio_index：该任务结果 music[] 里第几首（1-based，默认 1；一次生成通常 2 首：1 和 2）

警告

无法解析源时（任务未完成 / 序号越界 / task_id 不存在），提交期直接返回 400。

查询任务：GET /v1/music/tasks/:task_id

task_id string

提交接口返回的 task_id。

轮询该接口直到 status 为 completed 或 failed。完成后从 data.result.music[] 取产物。

Response

task_id string

任务唯一标识符

status string

任务状态：submitted / pending / completed / failed

progress integer

进度：排队 10 → 就绪 50 → 完成 100

data object

结果数据

result object

status 为 completed 时存在

music array

产物列表（一次生成通常 2 首）

audio_id string

音轨 id，供后续操作用 audio_index 定位

title string

标题

duration number

时长（秒）

lyrics string

歌词

tags string

风格标签

audio_url string

音频文件 URL

image_url string

封面图 URL

image_large_url string

大图封面 URL

video_url string

MV 视频 URL（若已生成）

error object

status 为 failed 时存在

message string

失败原因（预扣额度自动退回）

响应示例

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<音轨id，供后续操作 audio_index 定位>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}