Suno 通用约定与任务查询

• Suno 音乐接口的公共说明：认证、异步任务生命周期、model / version、源音轨引用
• 任务查询：GET /v1/music/tasks/:task_id，轮询直到 completed / failed

认证

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

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

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

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

1. 提交

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

```json
{ "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）

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

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

Response

</ResponseField>

响应示例

json { "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" } ] } } }

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