Overview
All image-to-3D or text-to-3D submissions return a task_id. Use the 3D 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 5–10 seconds to balance freshness with API usage efficiency. 3D model generation typically takes longer than image or video tasks.
Endpoint
GET https://api.siray.ai/v1/3d/generations/{task_id}
Headers
Authorization: Bearer <SIRAY_API_TOKEN>
Path parameters
| Name | Description |
|---|
task_id | ID returned when the 3D generation task was created. |
Response structure
{
"code": "success",
"message": "",
"data": {
"task_id": "3d_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 3D task identifier.data.status: Lifecycle state — values listed below.data.progress: Human-readable progress string.data.outputs: URLs pointing to the generated 3D model 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 3D model via the provided URLs. |
FAILURE | Irrecoverable error; inspect fail_reason for remediation steps. |
Usage example
curl -X GET "https://api.siray.ai/v1/3d/generations/${TASK_ID}" \
-H "Authorization: Bearer ${SIRAY_API_TOKEN}"
When status reaches SUCCESS, download the 3D model from the URLs in outputs. If the task fails, retry after resolving the underlying issue noted in fail_reason.
