直接答案：提交生成后只轮询查询接口，建议每 3–5 秒一次；
pending/submitted/processing继续等，completed/playable才下载，failed读取错误并停止。业务超时只代表本次等待结束，不代表上游失败，更不应重新提交收费任务。
生成任务的完整生命周期
| 阶段 | 行为 | 客户端动作 |
|---|---|---|
| 提交 | POST /api/music/create 创建任务 | 保存响应、请求 ID 和最终 song_id |
| 等待 | pending/submitted/processing | 间隔 3–5 秒查询，暂停下载逻辑 |
| 完成 | completed/playable | 获取媒体地址并下载 |
| 失败 | failed 或返回明确错误 | 记录错误，按规则退款或人工处理 |
推荐的轮询代码
const startedAt = Date.now();
const hardDeadline = startedAt + 10 * 60 * 1000;
let delay = 3000;
while (Date.now() < hardDeadline) {
const result = await querySong(songId);
const status = String(result?.data?.status || "").toLowerCase();
if (["completed", "complete", "playable"].includes(status)) {
return result;
}
if (["failed", "error"].includes(status)) {
throw new Error(JSON.stringify(result));
}
await sleep(delay);
delay = Math.min(Math.round(delay * 1.25), 10_000);
}超时后应该怎么做
- 保留
song_id，不要丢掉浏览器或任务队列里的记录。 - 提示用户“仍在生成中”，允许后台继续查询。
- 只有明确返回
failed才进入失败处理。 - 不要为了刷新状态重新调用生成接口。
429 与普通等待不一样
429 是请求频率限制，不是歌曲生成失败。优先读取 Retry-After，没有该响应头时从 10 秒开始退避。批量任务应限制同时在途的轮询请求数。
常见问题
多久可以播放？
多数任务几分钟内完成，但高峰和复杂编辑会更久。以查询接口状态为准，不以提交后经过的固定秒数判断。
网络断开会取消生成吗？
客户端断开不等于上游任务立即取消。恢复后继续用原 song_id 查询，不要重新下单。
音频地址为空是不是失败？
不是。任务未完成时地址通常为空；状态完成后再判断是否确实缺少媒体。
相关页面：Python、Node.js、查询 API、错误排查。
