Task Retrieval

After creating an async media request, use GET /v1/tasks/:taskId to fetch status and results. Xenodia returns its own normalized task resource rather than the upstream provider's raw response format.

Endpoint

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

Path Parameter

taskId:
  in: path
  type: string
  required: true
  description: Xenodia task_id returned when the async media task was created.

Response Schema

type: object
required:
  - task_id
  - object
  - model
  - type
  - state
  - request
  - result
  - error
  - progress
  - created_at
  - updated_at
properties:
  task_id:
    type: string
    description: Xenodia task identifier.
  object:
    type: string
    enum:
      - task
  model:
    type: string
    description: Model ID used by the task.
  type:
    type: string
    enum:
      - image
  state:
    type: string
    enum:
      - waiting
      - queuing
      - generating
      - success
      - fail
  request:
    type: object
    description: Normalized request snapshot captured when the task was created.
  result:
    type: object
    description: Final generated payload when the task succeeds; usually an empty object before completion.
  error:
    type: object
    description: Failure payload when the task fails; usually an empty object before completion.
  progress:
    type: integer
    minimum: 0
    maximum: 100
  created_at:
    type: integer
    description: Unix timestamp in seconds.
  updated_at:
    type: integer
    description: Unix timestamp in seconds.
  completed_at:
    type: integer
    nullable: true
    description: Present only after the task reaches a terminal state.

Task States

• waiting: task created and waiting to enter the upstream queue.
• queuing: task is queued.
• generating: task is actively running.
• success: task finished and result is available.
• fail: task failed and error is available.

Polling Guidance

• Start with a 2 to 3 second polling interval.
• Use backoff when polling for longer-running jobs.
• Download generated URLs promptly after success.
• Stop polling once the state is success or fail.

In-Progress Response

{
  "task_id": "0f6b9f2f-4d2a-4e1a-ae49-3e5d4f88dc2f",
  "object": "task",
  "model": "nano-banana-pro",
  "type": "image",
  "state": "generating",
  "request": {
    "prompt": "A cinematic banana pilot standing on a wet neon runway.",
    "aspect_ratio": "16:9",
    "resolution": "4K",
    "output_format": "png"
  },
  "result": {},
  "error": {},
  "progress": 50,
  "created_at": 1760002222,
  "updated_at": 1760002235
}

Success Response

{
  "task_id": "0f6b9f2f-4d2a-4e1a-ae49-3e5d4f88dc2f",
  "object": "task",
  "model": "nano-banana-pro",
  "type": "image",
  "state": "success",
  "request": {
    "prompt": "A cinematic banana pilot standing on a wet neon runway.",
    "aspect_ratio": "16:9",
    "resolution": "4K",
    "output_format": "png"
  },
  "result": {
    "created": 1760002248,
    "data": [
      { "url": "https://cdn.xenodia.xyz/generated/a.png" }
    ]
  },
  "error": {},
  "progress": 100,
  "created_at": 1760002222,
  "updated_at": 1760002248,
  "completed_at": 1760002248
}

Failure Response

{
  "task_id": "0f6b9f2f-4d2a-4e1a-ae49-3e5d4f88dc2f",
  "object": "task",
  "model": "nano-banana-pro",
  "type": "image",
  "state": "fail",
  "request": { "resolution": "4K" },
  "result": {},
  "error": { "message": "media task failed" },
  "progress": 0,
  "created_at": 1760002222,
  "updated_at": 1760002241,
  "completed_at": 1760002241
}

Status Codes

200:
  description: Task resource returned successfully

401:
  description: Missing or invalid Bearer token

403:
  description: Task belongs to a different Xenodia account
  example:
    error: forbidden
    message: task does not belong to this account

404:
  description: task_id was not found
  example:
    error: not_found
    message: task not found

502:
  description: Xenodia could not refresh upstream task status
  example:
    error: task_lookup_failed
    message: unexpected task state "..."