媒体与音乐
任务与 Webhook
大多数 AI 音乐路由都是异步的。您的应用应始终保存返回的 taskId，并将轮询作为备用方案，同时把 webhook 视为主要完成信号。
大多数 AI 音乐路由都是异步的。您的应用应始终保存返回的 taskId，并将轮询作为备用方案，同时把 webhook 视为主要完成信号。
查询路由
| 路由 | 用途 |
|---|---|
GET /suno/query/task?taskId={taskId} | 歌曲生成和封面任务 |
GET /suno/query/lyrics?taskId={taskId} | 歌词任务 |
GET /suno/query/vocal-removal?taskId={taskId} | 分轨或人声移除任务 |
GET /suno/query/wav?taskId={taskId} | WAV 转换任务 |
GET /suno/query/mp4?taskId={taskId} | MV 生成任务 |
GET /suno/query/cover?taskId={taskId} | 封面图任务 |
音乐任务状态
| 状态 | 含义 |
|---|---|
PENDING | 排队中 |
TEXT_SUCCESS | 文本或歌词阶段已完成 |
FIRST_SUCCESS | 第一段音频已完成 |
SUCCESS | 全部任务已完成 |
CREATE_TASK_FAILED | 任务创建失败 |
GENERATE_AUDIO_FAILED | 生成失败 |
Webhook 回调
所有异步音乐路由都可以调用您的 callBackUrl.
当前回调阶段
callbackType | 含义 |
|---|---|
文本 | 文本或歌词阶段已完成 |
first | 第一段音频结果已就绪 |
complete | 完整工作流已完成 |
回调示例
{
"callbackType": "complete",
"task_id": "5c79****be8e",
"data": [
{
"id": "e231****8cad",
"audio_url": "https://cdn.example.com/track1.mp3",
"stream_audio_url": "https://cdn.example.com/stream/track1.mp3",
"image_url": "https://cdn.example.com/cover1.jpeg",
"title": "夏日微风",
"tags": "pop, R&B",
"duration": 91.2
}
]
}常见 AI 音乐错误代码
| 代码 | 含义 |
|---|---|
400 | 参数无效 |
401 | 认证失败 |
405 | 频率限制超出 |
413 | 文本过长 |
429 | 配额耗尽 |
430 | 请求频率过高 |
455 | 系统维护 |
500 | 服务器错误 |
推荐的集成模式
- 保存每一次提交的
taskId - 以幂等方式接收 webhook 回调
- 如果 webhook 延迟，则将轮询作为备用
- 仅在以下情况后才将资产标记为就绪
SUCCESS或最终回调
实用的 webhook 建议
- 在信任有效载荷之前先验证 webhook 来源
- 将回调回执与用于轮询的同一任务记录一起保存
- 保持回调处理程序快速，并将繁重的后处理工作单独排队