Tripo format conversion converts a 3D model to formats such as GLTF, USDZ, FBX, OBJ, STL, and 3MF, and supports mesh processing, texture baking, and export settings.
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.
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-ConvertFormat.input object (Required)The model input.
Properties original_model_task_id string (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.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 (Required)The target export format. Valid values:
format also accepts glb, which has the same effect as GLTF.object (Optional)The format conversion parameters.
Properties quad boolean (Optional)Specifies whether to output a quad mesh instead of a triangle mesh. Default value: false.If enabled, the output format is forced to FBX. If face_limit is not set, the default face count is 10,000.If set to true, the task is billed as an advanced conversion.force_symmetry boolean (Optional)Specifies whether to force the model to be symmetric. Default value: false. Takes effect only when quad is true.face_limit integer (Optional)The maximum number of faces of the output model. We recommend a value of at least 100.Default value: null, which means no limit and the face count of the original model is kept. If quad is enabled, the default face count is 10,000.If set to a non-null value, the task is billed as an advanced conversion.flatten_bottom boolean (Optional)Specifies whether to flatten the bottom of the model. Default value: false. If set to true, the task is billed as an advanced conversion.flatten_bottom_threshold number (Optional)The depth threshold for flattening the bottom. Default value: 0.01. Takes effect only when flatten_bottom is true. If set to a value other than 0.01, the task is billed as an advanced conversion.texture_size integer (Optional)The size of the diffuse texture, in pixels. We recommend a value from 512 to 8192. The value does not need to be a power of 2.Default value: 4096. If set to a value other than 4096, the task is billed as an advanced conversion.texture_format string (Optional)The texture format. If set to a value other than JPEG, the task is billed as an advanced conversion. Valid values:
boolean (Optional)Specifies whether to move the pivot of the model to the bottom center. Default value: false. If set to true, the task is billed as an advanced conversion.scale_factor number (Optional)The scale factor of the exported model. The value must be greater than 0.Default value: 1.0. Passing 0 or a negative value does not return an error, but the conversion result is not guaranteed. If set to a value other than 1.0, the task is billed as an advanced conversion.bake boolean (Optional)Specifies whether to bake advanced materials into base textures. Default value: true.pack_uv boolean (Optional)Specifies whether to pack all UVs into a unified layout. Default value: false.with_animation boolean (Optional)Specifies whether to include skeleton and animation data. Default value: true.animate_in_place boolean (Optional)Specifies whether to export in-place animations, without root bone movement. Default value: false.part_names array[string] (Optional)The names of the parts to export.
boolean (Optional)Specifies whether to export vertex colors. Default value: false. Takes effect only for the OBJ and GLTF formats.export_orientation string (Optional)The orientation (forward axis) of the exported model. Valid values:
string (Optional)The compatibility preset for the FBX format. 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: Format conversion usually takes 10 to 30 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 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 conversion 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 converted 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 convert-3d-format for format conversion.credits_consumed integerThe credits consumed by the task, which equal convert_level.convert_level integerThe credits consumed by the format conversion, calculated based on the conversion complexity (basic or advanced). For the conditions, see Billing and parameter notes. |
|
Billing and parameter notes
- Billing tiers: Format conversion is billed in two tiers, basic and advanced. Advanced conversions consume more credits. A task is billed as an advanced conversion if any of the following conditions is met. Otherwise, it is billed as a basic conversion. For the actual credits consumed, see
usage.convert_levelin the query result.quadistrue.face_limitis set to a non-nullvalue.flatten_bottomistrue.flatten_bottom_thresholdis not0.01.texture_sizeis not4096.texture_formatis notJPEG.pivot_to_center_bottomistrue.scale_factoris not1.0.
- Unsupported parameter:
smart_low_poly(smart low-poly) is a parameter of the Tripo-Text/Image to 3D API and is not supported by the format conversion API. If a request includes it, for example when reusing the parameters of a generation task, it is ignored. No error is returned and no credits are charged for it. - Unlisted parameters: Except for
smart_low_poly, passing a parameter not listed in this topic returns a 400 error (InvalidParameter).