Skip to main content
3D Model Generation

Tripo-3D Model Generation

The Tripo 3D model generation supports text-to-3D model , single-image-to-3D model, and multi-image-to-3D model .

Related documentation: User guide
This document applies only to the China (Beijing) region. Use an API key from this region.

Prerequisites

  1. 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.
  2. Configure your API key: Select a region, get an API key, and then configure the API key as an environment variable.

HTTP calls

Since 3D model generation is time-consuming, the API uses an asynchronous call. 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.
  • 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.
If 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. Valid values:
  • Tripo/Tripo-H3.1: A high-fidelity 3D model generation that produces outputs with up to 2 million faces. Corresponds to Tripo official API version v3.1-20260211.
  • Tripo/Tripo-P1.0: A professional 3D model generation that produces outputs with up to 20,000 faces and offers faster generation. Corresponds to Tripo official API version P1-20260311.
input object (Required)The model input. The prompt, image, and images parameters are mutually exclusive; provide only one.

Properties

prompt string (Conditionally required)A text description of the desired 3D model. Required only for text-to-3D model.Multiple languages (such as Chinese and English) are supported. Each character, including Chinese characters and English letters, counts as one character. The maximum length is 1,024 characters.Example: a cute cat.image string (Conditionally required)The URL of a single image. Required only for single-image-to-3D model.Image requirements:
  • Format: JPEG, PNG.
  • Resolution: The width and height must be in the range of [20, 6000] pixels. We recommend that each dimension be greater than 256 pixels.
  • File size: Up to 20 MB.
Public URL:images array[object] (Conditionally required)A list of image objects. Required only for multi-image-to-3D model.The array length is fixed at 4, corresponding to the image order: front, left, back, right. Pass an empty object {} for views you don't need. The number of valid image objects should be 2 to 4. The requirements for each image are the same as for the image parameter. The images do not need to have the same resolution or aspect ratio.Each image object contains the following fields:
  • type: Image format. Valid values: jpeg or png.
  • file_token: The public URL of the image.
parameters object (Optional)Optional parameters to control 3D model generation.

Properties

texture_quality string (Optional)The quality of the texture. A texture is an image that wraps a 3D model's surface to define its visual appearance and details.Valid values:
  • standard: Default value. Standard-definition texture.
  • detailed: High-definition texture.
geometry_quality string (Optional)Supported model: Tripo/Tripo-H3.1.The geometric precision of the model.
  • standard: Default value. Standard version. The generated 3D model has up to 1.5 million faces.
  • ultra: Ultra-HD version. The generated 3D model has up to 2 million faces.
pbr boolean (Optional)Specifies whether to generate a PBR material model. Default value: true.When pbr is set to true, texturing is automatically enabled (texture is also set to true), and the result includes pbr_model_url.texture boolean (Optional)Specifies whether to generate a texture. Default value: true.To generate an untextured model, set both texture and pbr to false. The result includes base_model_url.
  • Text-to-3D model (textured)
  • Single-image-to-3D model (textured)
  • Multi-image-to-3D model (textured)
  • Multi-image-to-3D model (2 images)
  • Untextured generation
# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your Bailian 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-P1.0",
    "input": {
        "prompt": "a cute cat"
    },
    "parameters": {
        "texture_quality": "standard"
    }
}'

Response parameters

output objectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save 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"
}

Step 2: Query the task result

China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Polling recommendation: 3D model generation takes several minutes. We recommend using a polling mechanism with a reasonable interval, such as 15 seconds, to retrieve the result.
  • 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 result
Replace {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

outputobjectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe 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 → RUNNING → SUCCEEDED or FAILED.
  • The initial query status is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the generated video URL.
  • If the status is FAILED, check the error message and retry the task.
submit_time stringThe time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.resultsarrayThe generation results. This field is returned only when the task status is SUCCEEDED.

Properties

pbr_model_url stringThe download URL of the PBR material model (GLB format). Returned when the request parameter pbr is true (default). The link is valid for 2 hours. Please download it promptly.base_model_url stringThe download URL of the untextured base model (GLB format). Returned when both texture and pbr are set to false. The link is valid for 2 hours. Please download it promptly.rendered_image_url stringThe URL for the rendered preview image of the 3D model. The link is valid for 2 hours. Please download it promptly.
orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectUsage statistics for the task. Only successful tasks are counted.

Properties

3d_task_type stringThe type of 3D model generation task.
  • text-to-3d: text-to-3D model
  • image-to-3d: single-image-to-3D model
  • multi-image-to-3d: multi-image-to-3D model
count integerThe number of generated 3D models.texture_quality stringThe texture quality.geometry_quality stringThe geometric precision.
  • Task succeeded
  • Task failed
  • Task expired
{
    "request_id": "c11018a8-3f83-9591-a636-xxxxxx",
    "output": {
        "task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-26 14:13:14.373",
        "scheduled_time": "2026-04-26 14:13:14.419",
        "end_time": "2026-04-26 14:14:13.679",
        "results": [
            {
                "pbr_model_url": "https://openapi.cdn.tripo3d.com/xxxx.glb?auth_key=xxxx",
                "rendered_image_url": "https://openapi.cdn.tripo3d.com/xxxx.webp?auth_key=xxxx"
            }
        ]
    },
    "usage": {
        "3d_task_type": "text-to-3d",
        "count": 1,
        "texture_quality": "standard"
    }
}

Error messages

If an API call fails, refer to Error messages for troubleshooting.
API Usage
Text Generation
Image Generation
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Translation models
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More