Task Retrieval API

轮询 Xenodia 媒体与 capability 任务，并读取标准化状态、结果或公开失败提示。

从媒体生成或异步 capability 获得 task response 后，使用 GET /v1/tasks/{taskId}。

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`	任务已接受，等待调度。
`queuing`	任务正在等待 Xenodia 处理。
`generating`	正在生成。
`success`	任务完成，`result` 可用。
`fail`	任务失败，应检查 `error`。

Capability 任务使用 waiting、queued、running、succeeded、failed 或 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",
  "created_at": 1760000000,
  "updated_at": 1760000100,
  "completed_at": 1760000100
}

Video result 使用同一 envelope。result 可能包含 data、origin_data、full_result_data 和 resolution。

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"
}

Error statuses

Status	Meaning
`401`	缺少或无效 API key。
`403`	task 属于另一个 account。
`404`	task ID 不存在。
`502`	gateway 无法刷新或读取 task state。

Polling guidance

从短延迟开始，再指数退避。
媒体任务在 success 或 fail 后停止轮询；capability 任务在 succeeded、failed 或 canceled 后停止。
用户等待时设置 client-side timeout。
如果用户可以离开页面，要持久化 task ID。

Task Retrieval API

本页内容