Overview
All text-to-video or image-to-video submissions return a task_id. Use the video task status endpoint to poll the job until it finishes. The payload mirrors the async submission response and includes downloadable asset URLs when the task succeeds.
Poll every 3–5 seconds to balance freshness with API usage efficiency.
Endpoint
GET https://api.siray.ai/v1/video/generations/{task_id}
Headers
Authorization: Bearer <SIRAY_API_TOKEN>
Path parameters
| Name | Description |
|---|
task_id | ID returned when the video task was created. |
Response structure
{
"code": "success",
"message": "",
"data": {
"task_id": "video_69196fafcc9c8190acccf32e9b560c3f0da8a6d1948cfaa5",
"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 polling request.data.task_id: Echo of the video task identifier.data.status: Lifecycle state — values listed below.data.progress: Human-readable progress string.data.outputs: URLs pointing to the generated video assets (present when status is SUCCESS).data.fail_reason: Explains why processing stopped when status is FAILURE.data.submit_time, data.start_time, data.finish_time: Unix timestamps that help track total 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 the video via the provided URLs. |
FAILURE | Irrecoverable error; inspect fail_reason for remediation steps. |
Usage example
curl -X GET "https://api.siray.ai/v1/video/generations/${TASK_ID}" \
-H "Authorization: Bearer ${SIRAY_API_TOKEN}"
When status reaches SUCCESS, stream or download the video from the URLs in outputs. If the task fails, retry after resolving the underlying issue noted in fail_reason.
