直接答案：
request_id是异步受理回执，用来查“订单处理到哪一步”；tasks[].song_id是真正生成的歌曲 ID，用来查状态、参数和下载媒体。tasks[].index只是这一单里的第几首，也不是歌曲 ID。
一次生成会经过哪些对象
| 字段 | 属于什么 | 下一步用途 |
|---|---|---|
Idempotency-Key | 你自定义的请求幂等键 | 网络重试时复用，防止同一业务重复下单 |
request_id | 平台生成的异步受理号 | 调用 GET /api/music/requests/{request_id} |
tasks[].index | 一次受理中的任务位置 | 和 request_id 一起保存，便于恢复进度 |
song_id | 真实歌曲 ID | 查询歌曲、下载 MP3/WAV、读取详情 |
client_request_id | 平台留存的业务请求标识 | 在详情接口里辅助追踪来源 |
受理回执长什么样
{
"success": true,
"data": {
"request_id": "ac_2026102709000000000000000001",
"status": "processing",
"tasks": [
{
"index": 0,
"status": "processing",
"song_id": "f3fa09f5-3d55-4953-826c-0d23f043ec57"
},
{
"index": 1,
"status": "pending"
}
]
}
}这时第一首已经有 song_id，第二首还没有。正确做法是按任务项分别记录，不要等两首都出现后才保存已有结果，也不要自己用字符串拼接伪造第二个 ID。
受理状态与歌曲状态不是同一层
| 层级 | 常见 status | 含义 |
|---|---|---|
| 受理单 | queued | 已扣预授权额度，还没登记歌曲 |
| 受理单 | processing | 已提交，任务正在生成 |
| 受理单 | partial | 一次两首中已有部分完成 |
| 受理单 | completed | 两首都完成，可读真实 song_id |
| 受理单 | failed | 受理失败，费用退回，读取 error_message |
| 单首歌曲 | pending / processing | 仍在生成，媒体字段可以为空 |
| 单首歌曲 | completed / playable | 可进入下载流程 |
| 单首歌曲 | failed | 这一首生成失败，按单首结果处理 |
查询歌曲时 song_ids 怎么写
当前文档推荐英文逗号分隔字符串，不是 JSON 数组：
curl -X POST "https://www.suno-api.io/api/music/query" -H "Authorization: Bearer $SUNO_API_KEY" -H "Content-Type: application/json" -d '{
"model": "suno-v6",
"song_ids": "id_one,id_two"
}'接口通常直接返回歌曲数组，而不是再包一层 data。如果你的代码同时支持旧响应，请先按数组解析，再把旧信封作为兼容回退，不要用固定下标猜结构。
关键结果字段
| 字段 | 用途 | 注意 |
|---|---|---|
song_id | 后续查询、详情、下载的主键 | 必须持久化到数据库 |
status | 判断是否继续等待 | 不要只看 URL 是否为空 |
audio_url | MP3 媒体地址 | 未完成时可为空，默认 7 天有效 |
wav_url | 已准备的 WAV 地址 | 可能需要先调用 WAV 接口准备 |
cover_url | 封面图 | 用于列表和播放器 |
lyrics | 歌曲歌词 | 不是逐词时间轴 |
duration | 时长，单位秒 | 前端格式化后展示 |
parameters | 详情接口留存的生成参数 | 历史字段可能缺失，不要猜值 |
排查顺序
- 只有 request_id：继续查受理进度，真实 song_id 还没登记。
- 有 song_id 但没有音频：查单首 status；pending 或 processing 时地址为空正常。
- song_ids 返回空数组：确认 ID 不是
pending:占位值，且歌曲属于当前 Key 的主账号。 - completed 但媒体仍为空：改调下载接口获取地址；仍为空时记录 song_id 联系客服。
- 旧地址 404：重新调用查询或 download-url 获取新地址，不重新生成歌曲。
最小落库模型
generation_request:
client_request_id
idempotency_key
request_id
request_status
created_at
generated_song:
request_id
task_index
song_id
song_status
title
duration
media_url
fetched_at常见问题
request_id 能拿来下载歌曲吗？
不能。request_id 只定位受理单；下载使用受理结果的 tasks[].song_id 或歌曲查询结果里的 song_id。
song_ids 传数组还是逗号字符串？
当前推荐逗号分隔字符串。旧版数组写法可能在兼容层存在，但新接入不应依赖它。
查询返回空数组怎么办？
先排除 pending: 占位 ID，再确认账号数据范围。空数组表示没查到可用歌曲，不等于上游任务已经失败。
相关接口：生成 API、查询 API、媒体下载、轮询与超时。
