Task Retrieval API

Poll asynchronous Xenodia media tasks and read normalized task status, result payloads, or failure details.

Use GET /v1/tasks/:taskId after submitting an async media job.

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

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

Processing response shape

{
  "task_id": "task_123",
  "object": "task",
  "request_id": "req_abc",
  "model": "veo3_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": "nano-banana-pro",
  "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 upstream response.

Failure response shape

{
  "task_id": "task_123",
  "object": "task",
  "request_id": "req_abc",
  "model": "veo3_fast",
  "type": "video",
  "state": "fail",
  "request": {
    "prompt": "A cinematic close-up of a developer dashboard.",
    "resolution": "720p"
  },
  "result": {},
  "error": {
    "message": "upstream task failed"
  },
  "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 upstream task state.

Polling guidance

Start with a short delay, then use exponential backoff.
Stop polling after success or fail.
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