Skip to main content
停掉还没结束的任务。幂等:对已经 completedfailedcancelled 的任务调用取消,会返回 HTTP 200 + 当前状态,不报错。可以从和 /tasks/query 抢跑的轮询器里安全调用。

何时选用

  • 用户改主意了 —— 在你的 UI 里渲染中按了「取消」
  • 触发了成本上限 —— 账号刚到软 credit 上限,想停掉 in-flight 工作
  • 卡在 pending —— 任务异常排队过久,取消后用不同参数重投

Request

按 task_id(path-param 形式,主用)

按 out_task_id(body 形式,备选)

只有幂等键在手时:

Body

只有 out_task_id 形式才需要 body。 恰好一个标识符要能解析。同时给 task_idout_task_id、或两个都不给, 返回 400 invalid_param。如果 path-param 和 body 里的 task_id 都有, path-param 优先。

Response

结构与 /tasks/query 相同 —— 任务的取消后状态。
如果 cancel 到达时任务已经在终态,响应反映那个状态(无字段变化):
这让重试安全的调用方可以把 200 当作「任务不再 in-flight」,不需要 对竞态分支。

扣费语义

要确认 running 状态的退款,cancel 返回后检查 credits_used。字段缺失 即未扣费;存在即为最终金额。

错误

幂等

cancel 在终态任务上幂等:对 completed / failed / cancelled 任务调用 cancel 会返回 HTTP 200 + 当前状态,而不是报错。这是有意的 —— 并行运行 /tasks/query 和 cancel 按钮的客户端不该分支处理「任务在 我的 cancel 到达前几毫秒结束了?」。

价格

cancel 调用本身免费。任何 credits_used 的退款在 cancel 过程里完成, 不是事后。

下一步