Generates a 3D Gaussian Splat file in the .splat format from a single image. Gaussian Splatting is a new 3D representation designed for high-quality real-time rendering and photorealistic scene reconstruction. The output .splat file can be loaded by mainstream Gaussian Splat viewers and renderers.
Use this API for real-time rendering or photorealistic scene reconstruction. If you need meshes, textures, or editable 3D assets, use Tripo-Text/Image to 3D.
ImportantThis document applies only to the China (Beijing) region. Use an API key from this region.
Prerequisites
- Enable the service: Go to the Alibaba Cloud Model Studio console, search for "Tripo", find the Tripo model card, and click Enable Now. In the dialog box, confirm the authorization.
- Configure your API key: Select a region, get an API key, and then configure the API key as an environment variable.
HTTP calls
The API uses asynchronous calls. The process involves two steps: create a task and then poll for the result.
Step 1: Create a task
China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation
Replace {WorkspaceId} with your actual workspace ID.
Note
- After the task is created, use the returned
task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
- For guidance for beginners, see Call APIs with Postman or cURL.
Request parameters Request headers Content-Type string (Required) The content type of the request. Must be application/json. Authorization string (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. X-DashScope-Async string (Required) Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable. ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned. Request body model string (Required) The model name. Fixed value: Tripo/Tripo-ImageToSplat. input object (Required) The model input. Properties image string (Required) The source image used to generate the Gaussian Splat. Pass a publicly accessible image URL. Image limits:
- Format: PNG, JPEG, WebP.
- File size: Up to 20 MB.
- Resolution: At least 256 × 256 pixels is recommended. The subject should be clearly visible, with a clean background and minimal occlusion.
parameters object (Optional) The generation parameters. Properties model_seed integer (Optional) The random seed. Valid range: -2147483648 to 2147483647. The same seed and the same input produce an identical .splat result. If not set, a random seed is used each time. | Image to Gaussian Splat# The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "Tripo/Tripo-ImageToSplat",
"input": {
"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/cfbxhg/tripo-single.jpg"
}
}'
|
Response parameters output object The task output information. Properties task_id string The task ID. Valid for queries for 24 hours. task_status string The status of the task. Enumeration values
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN: The task does not exist or its status is unknown.
request_id string Unique request identifier for tracing and troubleshooting. code string Error code. Returned only for failed requests. See Error codes. message string Detailed error message. Returned only for failed requests. See Error codes. | Successful responseSave the task_id to query the task status and result. {
"output": {
"task_status": "PENDING",
"task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
},
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
Error responseTask creation failed. See Error codes. {
"code": "InvalidApiKey",
"message": "No API-key provided.",
"request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}
|
Step 2: Query the task result
China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Note
- Polling recommendation: We recommend using a polling mechanism: query 10 seconds after submitting the task, and then every 15 to 30 seconds.
- Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
- Task ID validity: The task ID is valid for 24 hours. After this period, you can no longer query the result, and the API returns the task status as
UNKNOWN.
- RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure asynchronous task callbacks.
- More operations: To query tasks in batches or cancel a task, see Manage Asynchronous Tasks.
Request parameters Request headers Authorization string (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. Path parameters task_id string (Required) The ID of the task. | Query task resultReplace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours. Replace {WorkspaceId} with your actual workspace ID. curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
Response parameters output object The task output information. Properties task_id string The task ID. Valid for queries for 24 hours. task_status string The status of the task. Enumeration values
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
- PENDING (queued) → RUNNING (processing) → SUCCEEDED (successful) / FAILED (failed).
- The status of the first query is usually PENDING or RUNNING.
- When the status changes to SUCCEEDED, the response contains the URL of the generated Gaussian Splat file.
- If the status is FAILED, check the error message and retry.
- If the status is CANCELED, the task was canceled. To continue, submit a new task.
- If the status is UNKNOWN, the task does not exist or its status is unknown. This can occur if the task_id does not exist or has exceeded its 24-hour validity period.
submit_time string The time when the task was submitted. Format: YYYY-MM-DD HH:mm:ss.SSS. scheduled_time string The time when the task started running. Format: YYYY-MM-DD HH:mm:ss.SSS. end_time string The time when the task was completed. Format: YYYY-MM-DD HH:mm:ss.SSS. results array The list of generation results. Returned only when task_status is SUCCEEDED. Properties model_url string The URL of the Gaussian Splat file (.splat format). The URL is a signed temporary link that is valid for 2 hours. Please download it promptly. code string Error code. Returned only for failed requests. See Error codes. message string Detailed error message. Returned only for failed requests. See Error codes. usage object The output statistics. Returned only when the task succeeds. Properties 3d_task_type string The task type. Fixed to image-to-splat for Image to Gaussian Splat. credits_consumed integer The credits consumed by the task. Image to Gaussian Splat is billed per task and has no additional billable parameters. | Task succeeded{
"request_id": "a9dce7ab-b5e9-97af-b956-xxxxxx",
"output": {
"task_id": "7bce9a3a-3159-4391-8ee6-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-10-19 09:15:32.042",
"scheduled_time": "2026-10-19 09:15:32.105",
"end_time": "2026-10-19 09:15:50.715",
"results": [
{
"model_url": "https://openapi.cdn.tripo3d.com/xxxx/xxxx_output.splat?auth_key=xxxx"
}
]
},
"usage": {
"3d_task_type": "image-to-splat",
"credits_consumed": 30
}
}
Task failedIf the task fails, task_status is set to FAILED, and an error code and message are returned. See Error codes. {
"request_id": "e5d70b02-ebd3-98ce-9fe8-xxxxxx",
"output": {
"task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
"task_status": "FAILED",
"code": "InvalidParameter",
"message": "The parameter is invalid xxxxxx"
}
}
Task query expiredThe task_id is valid for queries for 24 hours. After this period, the following response is returned. {
"request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
"output": {
"task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
"task_status": "UNKNOWN"
}
}
|
Error messages
If the model call fails and returns an error message, see Error messages for solutions.