Overview
When you submit an image generation task (text-to-image or image-to-image) you receive a task_id. Use this endpoint to poll the execution lifecycle until the task either completes successfully or fails.
Query every 3–5 seconds to maintain responsiveness without exceeding rate limits.
Endpoint
GET https://api.siray.ai/v1/images/generations/async/{task_id}
Headers
Authorization: Bearer <SIRAY_API_TOKEN>
Path parameters
| Name | Description |
|---|
task_id | ID returned in the async submission response. |
Response structure
{
"code": "success",
"message": "",
"data": {
"task_id": "image_a8813a4b4c9",
"status": "SUCCESS",
"progress": "100%",
"outputs": [
"https://api.siray.ai/redirect/example-output"
],
"start_time": 1763274702,
"finish_time": 1763274838,
"submit_time": 1763274672,
"fail_reason": ""
}
}
Fields
code / message: Service-level indicators for the request outcome.data.task_id: Echoes the submitted task identifier.data.status: Current lifecycle state — see the table below.data.progress: Human-readable percentage for UI display.data.outputs: Array of public URLs that host the generated image assets (present when status is SUCCESS).data.fail_reason: Populated if generation fails.data.submit_time, data.start_time, data.finish_time: Unix timestamps for auditing latency.
Status values
| Status | Meaning |
|---|
NOT_START | Task accepted but preprocessing has not started yet. |
SUBMITTED | Request stored and waiting to enter the queue. |
QUEUED | Task is scheduled and waiting for compute resources. |
IN_PROGRESS | Generation is currently running. |
SUCCESS | Outputs are ready; download them via the URLs in outputs. |
FAILURE | Irrecoverable error; inspect fail_reason for remediation steps. |
Usage example
curl -X GET "https://api.siray.ai/v1/images/generations/async/${TASK_ID}" \
-H "Authorization: Bearer ${SIRAY_API_TOKEN}"
Once status becomes SUCCESS, fetch the image(s) via the URLs in outputs. If the task fails, retry only after resolving the reported fail_reason.
