Skip to Content

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. Only queued tasks can be canceled.
  • running: Actively generating.
  • succeeded: Terminal state. Outputs appear in output and cost.status is "settled".
  • failed: Terminal state. Error details appear in error and cost.status is "refunded".
  • canceled: Terminal state. Canceled while queued; cost.status is "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 with status, model, and source; limit is 1–100 (default 20). When has_more is true, pass next_cursor as cursor for the next page.
  • Cancel a queued task: POST /v1/tasks/{id}/cancel cancels a queued task and immediately refunds the hold. If the task is already running or finished, the API returns HTTP 409 (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_seconds in GET /v1/models/{id}). Timed-out tasks fail with timeout and refund in full.
  • Retention: Generated files expire 7 days after completion (expires_at). Task metadata and ledger entries are kept permanently.