# v2 → v3 迁移指南

本文档帮助你将现有代码从 Tripo API v2 迁移到 v3。

## 用 Skill 快速从 V2 升级到 V3

不用先看懂所有 API 差异。下载这份 Skill，把它放到需要迁移的项目目录中，再让 AI 编程工具使用它。它会帮你找到项目里的 V2 调用，并一步步迁移到 V3。

### 第 1 步：下载 Skill

<a class="plugin-download-button" href="/assets/developer/tripo-v2-to-v3-migration/SKILL.md" download="SKILL.md">下载</a>

下载后会得到一个名为 `SKILL.md` 的文件，请不要修改文件名。

### 第 2 步：放入项目并使用 Skill

将下载的 `SKILL.md` 放到需要迁移的项目目录中。然后打开该项目，直接告诉 AI 使用这个 Skill。

### 第 3 步：复制这句话开始迁移

打开需要迁移的项目，把下面这句话完整发送给你的 AI 编程工具：

```text
请使用项目目录中的 `SKILL.md`，帮我把当前项目中的 Tripo API 从 V2 迁移到 V3。先告诉我需要改哪些地方，等我确认后再修改。最后按照文件里的清单检查，确保没有漏改。
```

工具会先找到 V2 调用并给出迁移计划，不需要你手动逐个文件查找。

## 主要变化

### 1. Base URL 变更

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

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

### 2. 万能端点拆分为独立端点

v2 使用单一 `POST /v2/openapi/task` 端点加 `type` 字段区分任务类型。v3 为每种能力提供独立端点，无需 `type` 字段。

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

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

### 3. 文件输入统一为 `input` 字段

v2 中根据输入来源使用不同字段名（`file`、`file_token`、`url`、`object`）。v3 统一为 `input` 字段，系统自动推断输入类型。

```json
// v2 — 需要指定不同字段名
{ "type": "refine_model", "draft_model_task_id": "task_abc123" }
{ "type": "convert_model", "original_model_task_id": "task_abc123" }

// v3 — 统一使用 input
{ "input": "task_abc123" }
{ "input": "https://example.com/model.glb" }
{ "input": "file_token_abc123" }
```

### 4. 字段名规范化

| v2 字段 | v3 字段 |
| :-: | :-: |
| `create_time` | `created_at` |
| `consumed_credit` | `credits_consumed` |

### 5. 文生图与图生图分离

v2 中文生图和图生图共用接口，v3 拆分为独立端点：

- `POST /v3/generation/text-to-image`：纯文本输入生成图片
- `POST /v3/generation/image-to-image`：基于参考图片生成/编辑图片

## 端点映射表

### 生成

| v2 type 值 | v3 端点 |
| :-: | :-: |
| `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` |

### 模型处理

| v2 type 值 | v3 端点 |
| :-: | :-: |
| `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` |

### 动画

| v2 type 值 | v3 端点 |
| :-: | :-: |
| `animate_prerigcheck` | `POST /v3/animations/rig-check` |
| `animate_rig` | `POST /v3/animations/rig` |
| `animate_retarget` | `POST /v3/animations/retarget` |

### 网格编辑

| v2 type 值 | v3 端点 |
| :-: | :-: |
| `mesh_segmentation` | `POST /v3/mesh/segment` |
| `mesh_completion` | `POST /v3/mesh/complete` |
| `highpoly_to_lowpoly` | `POST /v3/mesh/decimate` |

### 任务与文件

| v2 端点 | v3 端点 |
| :-: | :-: |
| `GET /v2/openapi/task/{task_id}` | `GET /v3/tasks/{task_id}` |
| `POST /v2/openapi/upload` | `POST /v3/files` |

## 迁移步骤

### 第 1 步：更新 Base URL

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

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

### 第 2 步：按映射表替换端点

```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"
})
```

### 第 3 步：移除 `type` 字段

v3 端点路径已隐含任务类型，请求体中不再需要 `type` 字段。

### 第 4 步：替换输入字段为 `input`

```python
# v2 — 不同任务类型使用不同字段名
payload = {"type": "refine_model", "draft_model_task_id": "task_abc123"}
payload = {"type": "convert_model", "original_model_task_id": "task_abc123"}

# v3 — 统一使用 input
payload = {"input": "task_abc123"}
```

### 第 5 步：更新响应字段名

```python
# v2
created = task["create_time"]
cost = task["consumed_credit"]

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

### 第 6 步：测试验证

1. 逐个端点替换并测试
2. 验证任务创建和轮询流程正常
3. 确认下载链接可用
4. 检查积分扣除和余额查询正常

## 注意事项

- v2 和 v3 可以并行运行，建议逐步迁移而非一次性切换
- API Key 在 v2 和 v3 之间通用，无需重新创建
- 任务 ID 格式不变，v2 创建的任务可在 v3 中查询