Task Retrieval API

Poll Xenodia media and capability tasks and read normalized status, result payloads, or public failure guidance.

Use GET /v1/tasks/{taskId} after receiving a task response from media generation or an asynchronous capability.

Endpoint

GET https://api.xenodia.xyz/v1/tasks/{taskId}

cURL

curl "https://api.xenodia.xyz/v1/tasks/task_123" \
  -H "Authorization: Bearer $XENODIA_API_KEY"

Task states

Media tasks use these states:

State	Meaning
`waiting`	The task has been accepted and is waiting to be scheduled.
`queuing`	The task is queued by Xenodia.
`generating`	Generation is in progress.
`success`	The task completed and `result` is available.
`fail`	The task failed and failure details should be inspected.

Capability tasks use waiting, queued, running, succeeded, failed, or canceled.

Processing response shape

{
  "task_id": "task_123",
  "object": "task",
  "request_id": "req_abc",
  "model": "veo3.1_fast",
  "type": "video",
  "state": "generating",
  "request": {
    "prompt": "A cinematic close-up of a developer dashboard.",
    "resolution": "720p"
  },
  "result": {},
  "error": {},
  "progress": 42,
  "poll_url": "/v1/tasks/task_123",
  "created_at": 1760000000,
  "updated_at": 1760000030
}

Success response shape

{
  "task_id": "task_123",
  "object": "task",
  "request_id": "req_abc",
  "model": "gpt-image-2.5-flare",
  "type": "image",
  "state": "success",
  "request": {
    "prompt": "A clean product render",
    "n": 1,
    "response_format": "url",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  },
  "result": {
    "created": 1760000100,
    "data": [
      {
        "url": "https://cdn.example.com/generated.png"
      }
    ]
  },
  "error": {},
  "progress": 100,
  "poll_url": "/v1/tasks/task_123",
  "billing": {
    "status": "committed",
    "reserve_amount_micro_usdc": 100000,
    "actual_amount_micro_usdc": 100000,
    "released_amount_micro_usdc": 0
  },
  "created_at": 1760000000,
  "updated_at": 1760000100,
  "completed_at": 1760000100
}

Video results use the same envelope. The result object may include data, origin_data, full_result_data, and resolution, depending on the normalized task response.

Failure response shape

{
  "task_id": "task_123",
  "object": "task",
  "request_id": "req_abc",
  "model": "veo3.1_fast",
  "type": "video",
  "state": "fail",
  "request": {
    "prompt": "A cinematic close-up of a developer dashboard.",
    "resolution": "720p"
  },
  "result": {},
  "error": {
    "message": "The task could not be completed."
  },
  "progress": 100,
  "poll_url": "/v1/tasks/task_123",
  "created_at": 1760000000,
  "updated_at": 1760000100,
  "completed_at": 1760000100
}

Error statuses

Status	Meaning
`401`	Missing or invalid API key.
`403`	The task belongs to another account.
`404`	The task ID was not found.
`502`	The gateway could not refresh or read task state.

Polling guidance

Start with a short delay, then use exponential backoff.
For media, stop after success or fail. For capabilities, stop after succeeded, failed, or canceled.
Apply a client-side timeout for workflows where the user is waiting.
Persist the task ID if the user can navigate away.

Task Retrieval API

On this page