DocsICP FilingConsole
官方文档
首页

Tripo-3D Model Generation

更新时间：
复制 MD 格式
产品详情
我的收藏

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

Important

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://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/3d-generation

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

Text-to-3D model (textured)

curl --location 'https://dashscope.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"
    }
}'

Single-image-to-3D model (textured)

curl --location 'https://dashscope.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": {
        "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/cfbxhg/tripo-single.jpg"
    },
    "parameters": {
        "texture_quality": "standard"
    }
}'

Multi-image-to-3D model (textured)

curl --location 'https://dashscope.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": {
        "images": [
            { "type": "png", "file_token": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/liafix/tripo-images-1.png" },
            { "type": "png", "file_token": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/slgluy/tripo-images-2.png" },
            { "type": "png", "file_token": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/zjqhyn/tripo-images-3.png" },
            { "type": "png", "file_token": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mqfzww/tripo-images-4.png" }
        ]
    },
    "parameters": {
        "texture_quality": "standard"
    }
}'

Multi-image-to-3D model (2 images)

The image order is front, left, back, right. Pass an empty object {} for views you don't need.
curl --location 'https://dashscope.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": {
        "images": [
            { "type": "png", "file_token": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/liafix/tripo-images-1.png" },
            {},
            { "type": "png", "file_token": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/zjqhyn/tripo-images-3.png" },
            {}
        ]
    },
    "parameters": {
        "texture_quality": "standard"
    }
}'

Untextured generation

You must set both texture and pbr to false.
curl --location 'https://dashscope.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": false,
        "pbr": false
    }
}'
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.

Important

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:

  • HTTP and HTTPS protocols are supported.

  • Example: https://xxx/xxx.jpg.

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.

Response parameters

Successful 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"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

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.

Step 2: Query the task result

China (Beijing): GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • 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

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.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
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.

Response parameters

Task succeeded

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

Task failed

When a task fails, task_status is FAILED with an error code and message. 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 expired

The task_id is valid for 24 hours. After this period, queries return the following error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

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 → 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 string

The time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.

results array

The generation results. This field is returned only when the task status is SUCCEEDED.

Properties

pbr_model_url string

The 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 string

The 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 string

The URL for the rendered preview image of the 3D model. The link is valid for 2 hours. Please download it promptly.

orig_prompt string

The original input prompt, corresponding to the request parameter prompt.

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

Usage statistics for the task. Only successful tasks are counted.

Properties

3d_task_type string

The 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 integer

The number of generated 3D models.

texture_quality string

The texture quality.

geometry_quality string

The geometric precision.

Error messages

If an API call fails, refer to Error messages for troubleshooting.

Previous：3D model generationNext：Audio