v2 → v3 迁移指南
本文档帮助你将现有代码从 Tripo API v2 迁移到 v3。
用 Skill 快速从 V2 升级到 V3
不用先看懂所有 API 差异。下载这份 Skill，把它放到需要迁移的项目目录中，再让 AI 编程工具使用它。它会帮你找到项目里的 V2 调用，并一步步迁移到 V3。
第 1 步：下载 Skill
下载后会得到一个名为 SKILL.md 的文件，请不要修改文件名。
第 2 步：放入项目并使用 Skill
将下载的 SKILL.md 放到需要迁移的项目目录中。然后打开该项目，直接告诉 AI 使用这个 Skill。
第 3 步：复制这句话开始迁移
打开需要迁移的项目，把下面这句话完整发送给你的 AI 编程工具：
请使用项目目录中的 `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", "model": "v3.1-20260211" }
3. 文件输入统一为 input 字段
v2 中根据输入来源使用不同字段名（file、file_token、url、object）。v3 统一为 input 字段，系统自动推断输入类型。
JSON
// v2 — 需要指定不同字段名
{ "type": "refine_model", "draft_model_task_id": "123e4567-e89b-42d3-a456-426614174000" }
{ "type": "convert_model", "original_model_task_id": "123e4567-e89b-42d3-a456-426614174000" }
// v3 — 统一使用 input
{ "input": "123e4567-e89b-42d3-a456-426614174000" }
{ "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",
"model": "v3.1-20260211"
})
第 3 步：移除 type 字段
v3 端点路径已隐含任务类型，请求体中不再需要 type 字段。
第 4 步：替换输入字段为 input
Python
# v2 — 不同任务类型使用不同字段名
payload = {"type": "refine_model", "draft_model_task_id": "123e4567-e89b-42d3-a456-426614174000"}
payload = {"type": "convert_model", "original_model_task_id": "123e4567-e89b-42d3-a456-426614174000"}
# v3 — 统一使用 input
payload = {"input": "123e4567-e89b-42d3-a456-426614174000"}
第 5 步：更新响应字段名
Python
# v2
created = task["create_time"]
cost = task["consumed_credit"]
# v3
created = task["created_at"]
cost = task["credits_consumed"]
第 6 步：测试验证
- 逐个端点替换并测试
- 验证任务创建和轮询流程正常
- 确认下载链接可用
- 检查积分扣除和余额查询正常
注意事项
- v2 和 v3 可以并行运行，建议逐步迁移而非一次性切换
- API Key 在 v2 和 v3 之间通用，无需重新创建
- 请使用各次创建任务响应返回的 ID。通过 v3 查询已有 v2 任务之前，请先验证兼容性。