Task Retrieval API

Xenodia の media / capability task を polling し、標準化された status、result、公開 failure guidance を読む。

media generation または async 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

Media task は次の state を使います：

State	Meaning
`waiting`	task は受理され、schedule 待ち。
`queuing`	Xenodia で処理待ちです。
`generating`	generation in progress。
`success`	task 完了、`result` が利用可能。
`fail`	task failed。`error` を確認する。

Capability task は 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 を refresh / read できない。

Polling guidance

短い delay から始め、exponential backoff を使う。
Media task は success / fail、capability task は succeeded / failed / canceled で polling を止める。
ユーザーが待つ workflow には client-side timeout を設定する。
ユーザーが画面を離れる可能性があるなら task ID を保存する。

Task Retrieval API

このページ