失败任务的 API 重试方法与自动化处理
重试接口的形态
官方文档里查询与重试是同一条路径的两种方法：
- 查询：
GET /api/task/{任务ID} - 重试：
POST /api/task/{任务ID}
任务 ID 同样支持逗号分隔批量，把失败的那批 ID 拼起来一次 POST 全部重试：
curl -X POST <接口地址>/api/task/tid1,tid2 \
-H 'X-API-KEY: 你的密钥'什么时候触发重试
轮询循环里发现任务到达失败终态时进入重试分支。但重试前先分类——不是所有失败都值得原样再跑：
| 失败类型 | 特征 | 处理 |
|---|---|---|
| 偶发失败（官方口径） | 网络与并发导致的随机失败 | 直接重试，见放大失败怎么办 |
| 参数问题 | 8x/16x 超权限、参数非法 | 改参数重新走创建接口，重试救不了 |
| 源图问题 | 文件超限、地址失效、格式异常 | 回到上传段换文件，见上传原图 |
| 持续失败 | 同一任务重试两次仍失败 | 挂起人工检查，别再打接口 |
自动化重试骨架
def retry_failed(failed_ids):
# 失败任务批量重试，返回重试后的任务 ID 串
ids = ",".join(failed_ids)
r = requests.post(f"{root}/api/task/{ids}",
headers=HEADERS)
return r
def run_with_retry(all_ids, max_retry=2):
done, dead = [], []
pending = list(all_ids)
for attempt in range(max_retry + 1):
failed = poll_until_terminal(pending) # 轮询到终态，见查询一节
done.extend(t for t in failed if t.ok)
dead = [t for t in failed if not t.ok]
if not dead or attempt == max_retry:
break
pending = [t.id for t in dead]
retry_failed(pending) # 对失败任务发起重试
return done, dead（骨架里的 poll_until_terminal 与字段解析见查询放大结果的做法。）
重试策略两条纪律
- 上限两次——官方口径失败本就是小几率，两次仍失败大概率是参数或源图问题，自动重试到此为止；
- 重试也算任务——重试消耗与额度计费的关系以账户实际计数为准，批量任务把重试次数写进日志，月底好对账，见月度张数怎么算。
错峰重试
偶发失败多与服务器拥挤相关，自动化脚本里给重试加一个随机延迟（几分钟级）+ 换时段兜底（深夜补跑队列），成功率观感最好，见排队时长。