任务与轮询
了解任务状态机、同步等待、轮询查询、取消任务以及结果文件的保留周期。
任务生命周期
每次生成请求都会创建一个任务对象(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任务并立即释放冻结资金;若任务已开始或结束,则返回 HTTP409(task_not_cancelable)。
透传字段、超时与保留期
- 透传字段
metadata:支持传入不超过 4 KB 的任意 JSON 对象(例如{"order_id": "A1001"}),查询与 Webhook 回调会原样带回。 - 任务超时:默认图片任务 10 分钟、视频任务 60 分钟(单个模型的精确上限见
GET /v1/models/{id}的timeout_seconds)。超时的任务会判为失败(timeout)并全额退回。 - 文件保留期:生成结果与上传文件保留 7 天(详见
expires_at);任务记录与钱包流水永久保留。