Tripo-Text/Image to 3D

Updated at:

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

Related documentation: User guide

ImportantThis 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.

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. 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, in the order: front, left, back, right.

  • Pass an empty object {} for views you don't need. The front view (first element) must contain an image; valid image count is 2 to 4.
  • Each image follows the same limits as the image parameter. Resolutions and aspect ratios do not need to match.
  • We recommend all images show the same object from different views under consistent lighting. Multi-view input improves geometric accuracy and texture coverage.

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 that balances quality and speed.
  • detailed: High-definition texture with higher fidelity and slower generation.
  • extreme: 8K texture with the highest fidelity.

geometry_quality string (Optional)

Supported model: Tripo/Tripo-H3.1. Tripo/Tripo-P1.0 ignores this parameter without returning an error.

The geometric precision of the model. Valid values:

  • standard: Default value. Standard version that balances quality and speed. The generated 3D model has up to 1.5 million faces.
  • ultra: Ultra-HD version with finer geometric details. The generated 3D model has up to 2 million faces. Equivalent to detailed in the Tripo official API.

pbr boolean (Optional)

Specifies whether to generate a PBR material model. PBR materials include base color (base_color), metallic, roughness, and normal maps. 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.

quad boolean (Optional)

Supported model: Tripo/Tripo-H3.1. Tripo/Tripo-P1.0 ignores this parameter without returning an error.

Specifies whether to output a quad mesh instead of triangles. Default value: false.

When enabled, the output format is forced to FBX. If face_limit is not set, the default face count is 10,000.

smart_low_poly boolean (Optional)

Supported model: Tripo/Tripo-H3.1. Tripo/Tripo-P1.0 ignores this parameter without returning an error.

Specifies whether to generate a smart low-poly model, which has a hand-crafted style and clean topology. Default value: false. Best suited for simple inputs. Generation may occasionally fail for complex models.

When enabled, face_limit ranges from 500 to 20,000 for triangle faces and from 500 to 10,000 for quad faces. If generate_parts is also enabled, generate_parts does not take effect.

generate_parts boolean (Optional)

Supported model: Tripo/Tripo-H3.1. Tripo/Tripo-P1.0 ignores this parameter without returning an error.

Specifies whether to generate editable segmented parts. Default value: false.

When enabled, this parameter is incompatible with the following parameters:

  • texture and pbr: If not passed, both default to false. A 400 error is returned if texture or pbr is set to true, or if texture_quality is passed.
  • quad: If set to true, it is ignored, and the returned parts are triangle meshes.
  • smart_low_poly: If also enabled, smart_low_poly takes precedence and no parts are generated.

To generate parts, omit texture and pbr or set them to false, and do not pass texture_quality, quad, or smart_low_poly.

compress string (Optional)

Supported model: Tripo/Tripo-H3.1.

The compression mode. If not specified, no compression is applied. Valid values:

  • geometry: Compresses geometry data using meshopt to reduce file size.

negative_prompt string (Optional)

The negative prompt, which describes content you do not want in the 3D model. Maximum length: 255 characters.

face_limit integer (Optional)

The maximum number of faces in the generated 3D model. If not specified, the model determines it adaptively. Valid range:

  • Tripo/Tripo-H3.1: Up to 1,500,000 triangle faces (up to 2,000,000 when geometry_quality is ultra); up to 150,000 quad faces (when quad is true). When smart_low_poly is disabled, we recommend a value of at least 500. For a lower face count, enable smart_low_poly or use Tripo-Retopology. For the range when smart_low_poly is enabled, see that parameter.
  • Tripo/Tripo-P1.0: 50 to 20,000. A 400 error is returned if the value is out of range.

Recommended values: 50,000 to 100,000 for game assets, and 10,000 to 50,000 for web and mobile.

model_seed integer (Optional)

The random seed for geometry generation. Valid range: -2147483648 to 2147483647.

The same seed and input produce the same 3D mesh. If not set, a random seed is used each time.

image_seed integer (Optional)

The random seed for the image generation step. Valid range: -2147483648 to 2147483647.

It is mainly used to generate the reference image from the prompt in text-to-3D model. For single-image-to-3D and multi-image-to-3D model, it takes effect only when enable_image_autofix is enabled or texture_quality is detailed or extreme, and usually does not need to be set.

texture_seed integer (Optional)

The random seed for texture generation. Valid range: -2147483648 to 2147483647.

The same seed produces the same texture. If not set, a random seed is used each time. To get models with the same geometry but different textures, keep model_seed unchanged and change texture_seed.

texture_alignment string (Optional)

The texture alignment method. Valid values:

  • original_image: Default value. Prioritizes matching the colors of the input image.
  • geometry: Prioritizes matching the generated geometry.

orientation string (Optional)

The model orientation. Takes effect only when texture is true. Valid values:

  • default: Default value. Automatic orientation.
  • align_image: Aligns the model to the view of the input image.

export_orientation string (Optional)

The orientation (forward axis) of the exported model. Valid values:

  • +x: Default value. The positive X axis faces forward.
  • -x: The negative X axis faces forward.
  • +y: The positive Y axis faces forward.
  • -y: The negative Y axis faces forward.

Note

  • This parameter applies only to the current generation. If you plan to use the model in subsequent post-processing tasks, such as texturing, rigging, retargeting, or format conversion, we recommend that you do not set this parameter.
  • If you set this parameter and then post-process the model, the incorrect model orientation may affect the final result. However, the task status is still SUCCEEDED and no error is returned.
  • If you plan to post-process the model, leave this parameter unset and adjust the orientation through format conversion in the final step.

auto_size boolean (Optional)

Specifies whether to automatically scale the model to real-world size. Default value: false. When enabled, the model size is in meters, which suits AR/VR or game engine scenarios.

export_uv boolean (Optional)

Specifies whether to perform UV unwrapping during generation. Default value: true. Set it to false to speed up generation and reduce file size. UV unwrapping is then handled in the texturing stage.

enable_image_autofix boolean (Optional)

Specifies whether to automatically fix the input image. Default value: false. Takes effect only for single-image-to-3D model (when image is passed).

Text-to-3D model (textured)

# 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"
    }
}'

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

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

Single-image-to-3D model (H3.1 ultra)

Only Tripo/Tripo-H3.1 supports geometry_quality and quad.

# 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-H3.1",
    "input": {
        "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/cfbxhg/tripo-single.jpg"
    },
    "parameters": {
        "texture_quality": "detailed",
        "geometry_quality": "ultra",
        "quad": true
    }
}'

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

# 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": {
        "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.

# 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": {
        "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.

# 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": false,
        "pbr": false
    }
}'

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 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": "Invalid 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: 3D model generation usually takes 30 to 120 seconds. 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 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

outputobject

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 3D model 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.

resultsarray

The generation results. This field is returned only when the task status is SUCCEEDED. Each URL is a signed temporary link that is valid for 2 hours. Please download it promptly.

Properties

model_url string

The URL of the 3D model. Returned for all generation tasks.

pbr_model_url string

The URL of the PBR material model, in GLB format when quad is disabled or FBX format when quad is enabled. Returned when pbr is true (default) and generate_parts is not enabled. Not returned when texture is true and pbr is false. In this case, get the textured model from model_url.

base_model_url string

The URL of the untextured base model, in GLB format when quad is disabled or FBX format when quad is enabled. Returned when both texture and pbr are set to false.

rendered_image_url string

The URL for the rendered preview image of the 3D model.

generated_image_url string

The URL of the intermediate image generated from the prompt in text-to-3D model tasks.

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. Returned only when the task succeeds. Not returned for failed tasks.

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

credits_consumed integer

The credits consumed by the task. Formula:

credits_consumed = Base item credits + texture_quality + geometry_quality + quad + smart_low_poly + generate_parts

  • The base item credits are determined by the model and task type and are not returned separately. For the credits of each billing item, see Model inference pricing.
  • The billable parameters in the formula are the credit increments returned in usage. Billable parameters with a credit increment of 0 are not returned and count as 0.

texture_quality integer

The additional credits for generating textures, calculated based on texture quality. If textures are generated without texture_quality, including when no texture parameters are passed, the task is billed as standard. Not returned when an untextured model is generated (both texture and pbr are false).

geometry_quality integer

The additional credits for using Ultra geometric precision. Returned only for Tripo/Tripo-H3.1 when geometry_quality is ultra.

quad integer

The additional credits for outputting a quad mesh. Returned only when quad is enabled for Tripo/Tripo-H3.1.

smart_low_poly integer

The additional credits for generating a smart low-poly model. Returned only when smart_low_poly is enabled for Tripo/Tripo-H3.1.

generate_parts integer

The additional credits for generating parts. Returned only when generate_parts is enabled and takes effect for Tripo/Tripo-H3.1.

Task succeeded

{
    "request_id": "5fc8c4c2-f8b1-9ea2-bdda-xxxxxx",
    "output": {
        "task_id": "ca51d54a-ffba-4ecc-8e42-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-10-16 16:39:53.349",
        "scheduled_time": "2026-10-16 16:39:53.388",
        "end_time": "2026-10-16 16:41:36.379",
        "results": [
            {
                "rendered_image_url": "https://openapi.cdn.tripo3d.com/xxxx/legacy_mesh.webp?auth_key=xxxx",
                "model_url": "https://openapi.cdn.tripo3d.com/xxxx/tripo_base_model_xxxx.glb?auth_key=xxxx",
                "generated_image_url": "https://openapi.cdn.tripo3d.com/xxxx/text2image_xxxx.jpeg?auth_key=xxxx"
            }
        ]
    },
    "usage": {
        "3d_task_type": "text-to-3d",
        "credits_consumed": 40,
        "texture_quality": 10
    }
}

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

Error messages

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