Tripo-Format Conversion
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.
ImportantThis document applies only to the China (Beijing) region. Use an API key from this region.
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.
Note
- 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-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. X-DashScope-Async Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned. Request bodymodel The model name. Fixed value: input The model input. parameters The format conversion parameters. | Basic conversionAdvanced conversion (quad mesh)Setting parameters such as |
Response parametersoutput The task output information. request_id Unique request identifier for tracing and troubleshooting. code Error code. Returned only for failed requests. See Error codes. message Detailed error message. Returned only for failed requests. See Error codes. | Successful responseSave the Error responseTask creation failed. See Error codes. |
Step 2: Query the task result
China (Beijing): GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Note
- 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 headersAuthorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. Path parameterstask_id The ID of the task. | Query task resultReplace |
Response parametersoutput The task output information. usage The output statistics. Returned only when the task succeeds. | Task succeededTask failedIf the task fails, task_status is set to FAILED, and an error code and message are returned. See Error codes. Task query expiredThe task_id is valid for queries for 24 hours. After this period, the following response is returned. |
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).
Error messages
If the model call fails and returns an error message, see Error messages for solutions.