3D Model Task Status API

Monitor asynchronous 3D model generation tasks and download the produced 3D assets.

GET /v1/3d/generations/{task_id}

Query 3D model generation task

cURL

curl --request GET \
  --url https://api.siray.ai/v1/3d/generations/{task_id} \
  --header 'Authorization: Bearer <token>'

200

{
  "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": ""
  }
}

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.

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

Show child attributes