Task lifecycle

A task ends in one of three terminal states: SUCCEEDED, FAILED, or CANCELLED. Before that it's PENDING (queued) or PROCESSING (adapter executing).

States

Code	Meaning
PENDING	Accepted, waiting for a free provider account in the BullMQ queue.
PROCESSING	Account selected, adapter is calling the upstream provider.
SUCCEEDED	Files were generated and uploaded successfully. result is populated.
FAILED	Terminal failure. error_code describes why (see /docs/errors).
CANCELLED	Task was cancelled (by user or by system on timeout).

Polling for status

docs.taskLifecyclePollingBody

GET https://api.aigenway.com/v1/tasks/<task_id>
Authorization: Bearer sk_live_...

Don't poll more than once per second or you may hit rate_limit_exceeded.
Stop polling once status is SUCCEEDED, FAILED, or CANCELLED — those are terminal.
Prefer webhooks over polling when possible — they're more reliable and cheaper.

Success response

{
  "id": "cmomwuy0m000qbr0371src20a",
  "status": "SUCCEEDED",
  "mode": "ASYNC",
  "started_at":  "2026-05-01T12:50:33.671Z",
  "finished_at": "2026-05-01T12:50:51.831Z",
  "result": {
    "type": "image",
    "url": "https://api.aigenway.com/v1/files/results/<userId>/<taskId>/image_0-....png",
    "mime_type": "image/png",
    "available_until": "2026-05-31T12:50:51.831Z",
    "files": [ /* same shape, repeated for multi-image methods */ ]
  }
}

result.url is the primary file (PNG/JPEG for image methods). Download with a plain GET — no auth required.
result.files is an array of all generated files (up to 4 for multi-image methods). result.url duplicates the first entry for convenience.
result.available_until — after this date the file is removed from storage. Download and persist on your side within that window.

docs.taskLifecycleResultSection

docs.taskLifecycleResultBody

GET https://api.aigenway.com/v1/tasks/<task_id>/result
Authorization: Bearer sk_live_...

Failure response

{
  "id": "cmomv0k9g000e5v03epq70stm",
  "status": "FAILED",
  "error_code": "provider_outage",
  "error_message": "No provider capacity is available for this method right now. Please retry shortly."
}

provider_outage and service_unavailable are transient — retry after 30–60s with exponential backoff.
provider_rejected, content_rejected, and invalid_parameters won't recover on a blind retry — fix parameters.

Cancellation

docs.taskLifecycleCancelBody