Tripo3D

v2 to v3 Migration Guide

v2 to v3 Migration Guide

This document helps you migrate existing code from Tripo API v2 to v3.

Move from V2 to V3 with the Skill

You do not need to understand every API difference first. Download this Skill, place it in the project directory you want to migrate, and ask your AI coding tool to use it. It will help find V2 calls in your project and migrate them to V3 step by step.

Step 1: Download the Skill

Download

You will get a file named SKILL.md. Keep the filename unchanged.

Step 2: Place the Skill in your project and use it

Place the downloaded SKILL.md in the project directory you want to migrate. Then open the project and tell your AI to use this Skill.

Step 3: Copy this prompt to start

Open the project you want to migrate. Copy the full prompt below and send it to your AI coding tool:

Use the `SKILL.md` file in this project directory to move this project's Tripo API integration from V2 to V3. First show me what needs to change. Wait for my confirmation, then make the changes. Finally, use the checklist in the file to make sure nothing was missed.

The tool will first find the V2 calls and show you a plan, so you do not need to search every file yourself.

Major Changes

1. Base URL Change

# v2
https://api.tripo3d.ai/v2/openapi/

# v3
https://openapi.tripo3d.ai/v3/

2. Universal Endpoint Split into Dedicated Endpoints

v2 uses a single POST /v2/openapi/task endpoint and a type field to distinguish task types. v3 provides a dedicated endpoint for each capability, so the type field is no longer required.

JSON
// v2
POST /v2/openapi/task
{ "type": "text_to_model", "prompt": "a cat" }

// v3
POST /v3/generation/text-to-model
{ "prompt": "a cat" }

3. File Inputs Unified as the input Field

In v2, different field names are used depending on the input source, such as file, file_token, url, and object. In v3, they are unified under the input field, and the system automatically infers the input type.

JSON
// v2 - different field names are required
{ "type": "refine_model", "draft_model_task_id": "task_abc123" }
{ "type": "convert_model", "original_model_task_id": "task_abc123" }

// v3 - use input consistently
{ "input": "task_abc123" }
{ "input": "https://example.com/model.glb" }
{ "input": "file_token_abc123" }

4. Standardized Field Names

v2 Field v3 Field
create_time created_at
consumed_credit credits_consumed

5. Text-to-Image and Image-to-Image Split

In v2, text-to-image and image-to-image share the same API. In v3, they are split into dedicated endpoints:

  • POST /v3/generation/text-to-image - Generate an image from text-only input
  • POST /v3/generation/image-to-image - Generate or edit an image based on a reference image

Endpoint Mapping

Generation

v2 type Value v3 Endpoint
text_to_model POST /v3/generation/text-to-model
image_to_model POST /v3/generation/image-to-model
multiview_to_model POST /v3/generation/multiview-to-model
text_to_image POST /v3/generation/text-to-image
generate_image POST /v3/generation/image-to-image
generate_multiview_image POST /v3/generation/image-to-multiview
edit_multiview_image POST /v3/generation/edit-multiview

Model Processing

v2 type Value v3 Endpoint
refine_model POST /v3/models/refine
convert_model POST /v3/models/convert
import_model POST /v3/models/import
stylize_model POST /v3/models/stylize
texture_model POST /v3/models/texture

Animation

v2 type Value v3 Endpoint
animate_prerigcheck POST /v3/animations/rig-check
animate_rig POST /v3/animations/rig
animate_retarget POST /v3/animations/retarget

Mesh Editing

v2 type Value v3 Endpoint
mesh_segmentation POST /v3/mesh/segment
mesh_completion POST /v3/mesh/complete
highpoly_to_lowpoly POST /v3/mesh/decimate

Tasks and Files

v2 Endpoint v3 Endpoint
GET /v2/openapi/task/{task_id} GET /v3/tasks/{task_id}
POST /v2/openapi/upload POST /v3/files

Migration Steps

Step 1: Update the Base URL

Python
# v2
BASE_URL = "https://api.tripo3d.ai/v2/openapi"

# v3
BASE_URL = "https://openapi.tripo3d.ai/v3"

Step 2: Replace Endpoints Using the Mapping Table

Python
# v2
response = requests.post(f"{BASE_URL}/task", json={
    "type": "text_to_model",
    "prompt": "a cat"
})

# v3
response = requests.post(f"{BASE_URL}/generation/text-to-model", json={
    "prompt": "a cat"
})

Step 3: Remove the type Field

In v3, the endpoint path already implies the task type, so the request body no longer needs the type field.

Step 4: Replace Input Fields with input

Python
# v2 - different task types use different field names
payload = {"type": "refine_model", "draft_model_task_id": "task_abc123"}
payload = {"type": "convert_model", "original_model_task_id": "task_abc123"}

# v3 - use input consistently
payload = {"input": "task_abc123"}

Step 5: Update Response Field Names

Python
# v2
created = task["create_time"]
cost = task["consumed_credit"]

# v3
created = task["created_at"]
cost = task["credits_consumed"]

Step 6: Test and Validate

  1. Replace and test each endpoint one at a time
  2. Verify that task creation and polling work correctly
  3. Confirm that download links are available
  4. Check that credit deduction and balance queries work correctly

Notes

  • v2 and v3 can run in parallel. We recommend migrating gradually instead of switching all at once
  • API Keys are shared between v2 and v3. You do not need to create new keys
  • The task ID format remains unchanged. Tasks created in v2 can be queried in v3