completed、failed、cancelled
的任务调用取消,会返回 HTTP 200 + 当前状态,不报错。可以从和
/tasks/query 抢跑的轮询器里安全调用。
何时选用
- 用户改主意了 —— 在你的 UI 里渲染中按了「取消」
- 触发了成本上限 —— 账号刚到软 credit 上限,想停掉 in-flight 工作
- 卡在
pending—— 任务异常排队过久,取消后用不同参数重投
Request
按 task_id(path-param 形式,主用)
按 out_task_id(body 形式,备选)
只有幂等键在手时:Body
只有 out_task_id 形式才需要 body。
恰好一个标识符要能解析。同时给
task_id 和 out_task_id、或两个都不给,
返回 400 invalid_param。如果 path-param 和 body 里的 task_id 都有,
path-param 优先。
Response
结构与/tasks/query 相同 —— 任务的取消后状态。
200 当作「任务不再 in-flight」,不需要
对竞态分支。
扣费语义
要确认 running 状态的退款,cancel 返回后检查
credits_used。字段缺失
即未扣费;存在即为最终金额。
错误
幂等
cancel 在终态任务上幂等:对completed / failed / cancelled
任务调用 cancel 会返回 HTTP 200 + 当前状态,而不是报错。这是有意的 ——
并行运行 /tasks/query 和 cancel 按钮的客户端不该分支处理「任务在
我的 cancel 到达前几毫秒结束了?」。
价格
cancel 调用本身免费。任何credits_used 的退款在 cancel 过程里完成,
不是事后。