Tripo3D

v2 → v3 迁移指南

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

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 中查询