Tripo Texturing generates textures for an existing 3D model and supports PBR materials and up to 8K texture quality.
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.
- 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_idinoriginal_model_task_id. Alternatively, skip the preceding task and pass the public URL of a model file inmodel_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.
- After the task is created, use the returned
task_idto query the result. Thetask_idis 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 parametersRequest headersContent-Typestring (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.Request bodymodelstring (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:
string (Conditionally required)The publicly accessible URL of the 3D model file. Specify either this parameter or original_model_task_id.Model limits:
object (Optional)The texturing parameters.
Properties texture_quality string (Optional)The texture quality. Valid values:
string (Optional)The texture model version. Select a version based on the version that generated the source 3D model. Valid values:
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.
style_image, image, and images) must be public URLs. Each image cannot exceed 20 MB. We recommend the JPG, PNG, or WebP format.If you start a texturing task with original_model_task_id, we recommend that you pass the reference images again in the request.string (Optional)The texture alignment priority. Valid values:
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.
string (Optional)The compression mode. If not specified, no compression is applied. Valid values:
|
|
Response parametersoutputobjectThe task output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
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. |
Save the task_id to query the task status and result. |
Step 2: Query the task result
China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
- 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 parametersRequest headersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Path parameterstask_idstring (Required)The ID of the task. |
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. |
Response parametersoutputobjectThe task output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
stringThe time when the task was submitted. Format: YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task started running. Format: YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. Format: YYYY-MM-DD HH:mm:ss.SSS.results arrayThe 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 stringThe URL of the textured 3D model.pbr_model_url stringThe URL of the PBR material model. Returned as needed.rendered_image_url stringThe URL of the preview rendering of the 3D model.stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectThe output statistics. Returned only when the task succeeds.
Properties 3d_task_type stringThe task type. Fixed to texture for texturing.credits_consumed integerThe credits consumed by the task, which equal texture_quality.texture_quality integerThe credits consumed for generating textures, calculated based on texture quality. |
|