Tripo-Texturing

Updated at:

Tripo Texturing generates textures for an existing 3D model and supports PBR materials and up to 8K texture quality.

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.
  3. Prepare a preceding task: Create a task that outputs a 3D model, such as a Tripo-Text/Image to 3D task. After the task succeeds, pass its task_id in original_model_task_id. Alternatively, skip the preceding task and pass the public URL of a model file in model_url.

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

input object (Required)

The model input.

Properties

original_model_task_id string (Conditionally required)

The preceding task ID. Pass the task_id returned when the preceding task is created. The system automatically uses the 3D model output by the task. Specify either this parameter or model_url.

The preceding task can be any task that outputs a 3D model file (such as GLB), for example a Tripo-Text/Image to 3D task. The following conditions apply:

  • The preceding task must have succeeded.
  • The account that makes this call must be the same as the account of the preceding task. Referencing a task created by another account returns a 400 error.
  • If the preceding task is not a Tripo-Text/Image to 3D task, you must also pass texture_prompt.
  • If you use part_names, pass the task_id of a Tripo-Mesh Segmentation task.

model_url string (Conditionally required)

The publicly accessible URL of the 3D model file. Specify either this parameter or original_model_task_id.

Model limits:

  • Supported formats: GLB, GLTF, FBX, OBJ, and STL.
  • File size: Up to 150 MB.

parameters object (Optional)

The texturing parameters.

Properties

texture_quality string (Optional)

The texture quality. Valid values:

  • standard: Default value. Standard-definition textures that balance quality and speed.
  • detailed: High-definition textures with higher fidelity and slower generation.
  • extreme: 8K textures with the highest fidelity. Consumes more credits than detailed.

model_version string (Optional)

The texture model version. Select a version based on the version that generated the source 3D model. Valid values:

  • v3.0-20250812: Default value. Recommended for models generated by v3.0-20250812 or v3.1-20260211.
  • v2.5-20250123: Recommended for models generated by v2.5-20250123.

pbr boolean (Optional)

Specifies whether to generate PBR materials. Default value: true.

texture_prompt object (Optional)

The texture guidance input, which guides texture generation with text or reference images. Optional if the model to texture was generated by Tripo. However, it is required if the preceding task is not a Tripo-Text/Image to 3D task, such as a mesh segmentation task. Otherwise, the task fails. text, image, and images are mutually exclusive, so specify only one of them. style_image can be used only together with text.

  • text: A text prompt that describes the desired texture style. Example:

    {"text": "worn leather with scratches"}
    
  • style_image: The public URL of a style reference image. It can be used only together with text. We recommend a resolution of at least 256 × 256 pixels. Example:

    {"text": "cyberpunk style", "style_image": "https://.../xx.png"}
    
  • image: The public URL of a single reference image.

  • images: Multi-view reference images. The front view is required and at least 2 views must be provided. The following two formats are supported:

    • Key-value format (recommended): Pass an object in which each key is a view name and each value is the public URL of the image. Valid view names are front, left, back, and right. Omit views that you do not have.

      {
          "images": {
              "front": "https://.../front.png",
              "left": "https://.../left.png"
          }
      }
      
    • Array format: Pass an array of 4 elements that contains the public URLs of the images in the order of front, left, back, and right. Use null or "" as a placeholder for a missing view.

      {
          "images": [
              "https://.../front.png",
              "https://.../left.png",
              null,
              null
          ]
      }
      

Reference images (style_image, image, and images) must be public URLs. Each image cannot exceed 20 MB. We recommend the JPG, PNG, or WebP format.

NoteIf you start a texturing task with original_model_task_id, we recommend that you pass the reference images again in the request.

texture_alignment string (Optional)

The texture alignment priority. Valid values:

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

texture_seed integer (Optional)

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

The same seed produces the same textures. If not set, a random seed is used each time.

bake boolean (Optional)

Specifies whether to bake advanced material effects into the base textures to improve compatibility. Default value: true.

part_names array[string] (Optional)

The names of the parts to texture.

  • Part names are taken from the part node names of the preceding mesh segmentation task's result model (GLB), in the form tripo_part_0, tripo_part_1. The task result fields do not return part names separately, and the numbering may be non-contiguous, so read the GLB node names to obtain them.
  • Effective only when the preceding task is a Tripo-Mesh Segmentation task (or the seg_task_id returned by Tripo-Smart Segmentation).
  • If not specified, all parts are processed.
  • Passing a name that does not exist does not error and is still billed.

compress string (Optional)

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

  • geometry: Compresses geometry data with meshopt to reduce the file size.

Model URL + text guidance

# 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-Texture",
    "input": {
        "model_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260507/ffaaxt/tripo-text-to-3d-result.glb"
    },
    "parameters": {
        "texture_quality": "standard",
        "texture_prompt": {
            "text": "an orange and white short-haired cat"
        }
    }
}'

Task ID + reference image guidance

# 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-Texture",
    "input": {
        "original_model_task_id": "57f62a73-a9f0-4846-9627-xxxxxx"
    },
    "parameters": {
        "texture_quality": "detailed",
        "pbr": false,
        "bake": true,
        "texture_alignment": "geometry",
        "texture_prompt": {
            "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/liafix/tripo-images-1.png"
        }
    }
}'

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

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 textured 3D model.
  • 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 texturing results. Returned only when 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 textured 3D model.

pbr_model_url string

The URL of the PBR material model. Returned as needed.

rendered_image_url string

The URL of the preview rendering of the 3D model.

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 texture for texturing.

credits_consumed integer

The credits consumed by the task, which equal texture_quality.

texture_quality integer

The credits consumed for generating textures, calculated based on texture quality.

Task succeeded

{
    "request_id": "26070204-a08e-998e-9366-xxxxxx",
    "output": {
        "task_id": "0cc7f681-4547-4183-af5e-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-10-19 09:20:29.666",
        "scheduled_time": "2026-10-19 09:20:29.731",
        "end_time": "2026-10-19 09:21:36.232",
        "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_texture_xxxx.glb?auth_key=xxxx"
            }
        ]
    },
    "usage": {
        "3d_task_type": "texture",
        "credits_consumed": 10,
        "texture_quality": 10
    }
}

Task failed

If 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 expired

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