Tasks & polling
Understand the task lifecycle, synchronous waiting, polling, cancellation, and result retention.
Task lifecycle
Every generation request creates a task object (object: "task") that moves through a fixed set of states:
queued: Accepted and funds held; waiting to start. Onlyqueuedtasks can be canceled.running: Actively generating.succeeded: Terminal state. Outputs appear inoutputandcost.statusis"settled".failed: Terminal state. Error details appear inerrorandcost.statusis"refunded".canceled: Terminal state. Canceled whilequeued;cost.statusis"refunded".
Synchronous wait vs. polling
For fast image models, pass wait_seconds (1–60) on POST /v1/tasks so the request waits until the task finishes or the timeout elapses. For video models or longer runs, submit with wait_seconds: 0 (the default) and either receive a Webhook or poll GET /v1/tasks/{id} every 2–5 seconds.
curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \
-H "Authorization: Bearer $KEROX_API_KEY"Listing & canceling tasks
- List tasks:
GET /v1/tasks?status=succeeded&model=bytedance/seedance-2.5&limit=20&cursor=...returns your tasks newest first, across API, Studio, and MCP. Filter withstatus,model, andsource;limitis 1–100 (default 20). Whenhas_moreistrue, passnext_cursorascursorfor the next page. - Cancel a queued task:
POST /v1/tasks/{id}/cancelcancels aqueuedtask and immediately refunds the hold. If the task is alreadyrunningor finished, the API returns HTTP409(task_not_cancelable).
Metadata, timeouts & retention
- Metadata: Attach up to 4 KB of arbitrary JSON in
metadata(for example{"order_id": "A1001"}); it is returned verbatim on queries and webhooks. - Timeouts: Image tasks time out after 10 minutes and video tasks after 60 minutes by default (exact per-model limit is
timeout_secondsinGET /v1/models/{id}). Timed-out tasks fail withtimeoutand refund in full. - Retention: Generated files expire 7 days after completion (
expires_at). Task metadata and ledger entries are kept permanently.