Skip to main content
GET
/
v1
/
3d
/
generations
/
{task_id}
Query 3D model generation task
curl --request GET \
  --url https://api.siray.ai/v1/3d/generations/{task_id} \
  --header 'Authorization: Bearer <token>'
{
  "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": ""
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.siray.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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
NameDescription
task_idID 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

StatusMeaning
NOT_STARTTask accepted but preprocessing has not started yet.
SUBMITTEDRequest stored and waiting to enter the queue.
QUEUEDTask is scheduled and waiting for compute resources.
IN_PROGRESSGeneration is currently running.
SUCCESSOutputs are ready; download the 3D model via the provided URLs.
FAILUREIrrecoverable 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.

Authorizations

​
Authorization
string
header
required

Bearer authentication using API key

Path Parameters

​
task_id
string
required

Identifier returned from the 3D model generation task submission

Response

200 - application/json

Task status and (if available) generated outputs

Async task status query response

​
code
string
required

Status code returned by the service

Example:

"success"

​
message
string
required

Additional information about the request result

Example:

""

​
data
object
required

Task execution details