Tasks
Task lifecycle, status polling, cancellation, and compensation.
Tasks
Tasks are the common unit for image, video, audio, and future model groups.
Lifecycle
| Status | Meaning |
|---|---|
pending |
The task was accepted and is waiting for a worker. |
running |
A worker has started processing the task. |
completed |
Outputs are ready. |
failed |
The task failed. User-facing pages hide detailed internal errors. |
canceled |
The task was canceled and eligible credits can be returned automatically. |
Status polling
Read one task with GET /api/omni/tasks/{portal_task_id}, or poll several active task IDs with POST /api/omni/tasks/status-batch. Stop polling after completed, failed, or canceled.
Example batch request:
{
"portal_task_ids": ["portal_task_..."]
}
The Public API does not publish estimated wait times or a global queue rank. Product consoles may show a narrow, scoped queue snapshot, but that private UI projection is not part of this Public API contract.
Outputs
After a task reaches completed, call GET /api/omni/tasks/{portal_task_id}/output-urls for fresh image, video, or audio download URLs. Each output item carries its own access and expiry fields. Text and JSON outputs remain inline in the task outputs array.
Priority
The platform uses three priority ranks:
0: Eco image tasks created by supported website flows.1: normal fast-credit tasks.2: boosted tasks after the extra boost charge is charged.
Public API task creation uses API keys and accepts Fast credits only. The field can be omitted or set to fast; eco is rejected before task creation or billing. Signed-in website users and the API Console Playground can still submit supported image tasks with Fast or Eco. Workers sample priority buckets instead of always draining the highest bucket, so website Eco work is slower but should not starve.
Cancellation and compensation
Pending tasks can be canceled before a worker claims them; cancellation and the full eligible credit compensation commit together. Users cannot cancel running tasks. Failed tasks and runtime deadline failures automatically compensate eligible charged credits exactly once. There is no queue timeout and no manual compensation action.