API リファレンス
Task Retrieval API
Xenodia の非同期 media task を polling し、標準化された status、result payload、failure details を読む。
async media job を送信した後、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 | task は受理され、schedule 待ち。 |
queuing | upstream または internal worker で queue 中。 |
generating | generation in progress。 |
success | task 完了、result が利用可能。 |
fail | task failed。error を確認する。 |
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": "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",
"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": "task failed"
},
"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 を使う。
successまたはfailで polling を止める。- ユーザーが待つ workflow には client-side timeout を設定する。
- ユーザーが画面を離れる可能性があるなら task ID を保存する。