Skip to Content

任务与轮询

了解任务状态机、同步等待、轮询查询、取消任务以及结果文件的保留周期。

任务生命周期

每次生成请求都会创建一个任务对象(object: "task"),状态流转如下:

  • queued:已受理并冻结预估费用,等待开始执行。只有 queued 状态的任务可以取消。
  • running:生成中。
  • succeeded:终态。生成文件在 output 中返回,cost.status 为 "settled"。
  • failed:终态。失败原因在 error 中返回,cost.status 为 "refunded",冻结金额全额退回。
  • canceled:终态。在排队阶段被取消,cost.status 为 "refunded"。

同步等待与轮询

对于耗时较短的图片模型,可在 POST /v1/tasks 中传入 wait_seconds(1–60 秒),在一次请求内等待结果。对于视频等长耗时任务,建议使用默认 wait_seconds: 0,通过 Webhook 接收回调,或每隔 2–5 秒轮询一次 GET /v1/tasks/{id}。

curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \
  -H "Authorization: Bearer $KEROX_API_KEY"

列表查询与取消任务

  • 任务列表:GET /v1/tasks?status=succeeded&model=bytedance/seedance-2.5&limit=20&cursor=... 按时间倒序返回你的任务,覆盖 API、Studio 和 MCP 三种来源。可以按 status、model、source 筛选;limit 为 1–100(默认 20)。has_more 为 true 时,把 next_cursor 作为 cursor 传入取下一页。
  • 取消排队任务:POST /v1/tasks/{id}/cancel 可取消 queued 任务并立即释放冻结资金;若任务已开始或结束,则返回 HTTP 409(task_not_cancelable)。

透传字段、超时与保留期

  • 透传字段 metadata:支持传入不超过 4 KB 的任意 JSON 对象(例如 {"order_id": "A1001"}),查询与 Webhook 回调会原样带回。
  • 任务超时:默认图片任务 10 分钟、视频任务 60 分钟(单个模型的精确上限见 GET /v1/models/{id} 的 timeout_seconds)。超时的任务会判为失败(timeout)并全额退回。
  • 文件保留期:生成结果与上传文件保留 7 天(详见 expires_at);任务记录与钱包流水永久保留。