tripo-3d

Tripo 3D 资产生成

Tripo（VAST AI Research 的产品；消费品牌名为“Tripo AI”）可将文本、单张图像和多视图图像集转换为带纹理的 3D 网格，再通过后处理将其制作为可用于引擎的资产：PBR 纹理、重新拓扑、自动绑定、预设动画和格式转换。它以 Web Studio、移动应用和异步基于任务的 REST API（“Tripo OpenAPI”）的形式提供。本技能介绍如何通过该 API 和 Studio 制作可用于生产的资产。

下文使用的证据标签：[Doc] = Tripo 官方文档/SDK；[1P] = Tripo 第一方博客/营销声明（仅供参考，未经独立核实）；[3P] = 已披露的第三方来源；[Heuristic] = 生产经验判断，并非文档承诺。易变信息均标注了 verified 2026-07-10 日期；请重新核实，因为 Tripo 经常调整模型和定价。

何时使用 Tripo，何时不使用

Tripo 的优势在于速度和覆盖范围：几十秒到几分钟内即可生成可用的单物体网格，涵盖各种道具、角色和硬表面物体，并可通过一个 API 完成纹理处理、绑定和格式导出。[Heuristic] 如果你需要快速制作大量游戏/AR/预演/3D 打印资产，手头有概念图或清晰的参考图，或者希望先生成基础网格再手动细化，就可以考虑使用它。

在以下情形下，不要依赖 Tripo（或应相应调整预期）：

• 开箱即用的干净生产级拓扑。 原始生成结果通常是高密度的有机三角网格。变形或细分前，请在 DCC 工具中使用四边形重网格、智能低多边形或重新拓扑。[Heuristic]
• 完整场景/多物体布局。 每个任务只生成一个物体。请自行组合场景。
• 精确的尺寸/CAD 精度。 这是生成式重建，并非测量建模。用于 3D 打印时，请验证尺寸、壁厚和网格的流形性。
• 保证还原真实、可识别人物的相貌，或复刻受版权保护/带品牌标识的角色。 请将此类情况视为权利风险（参见“权利与许可”）。
• 文字、精细 Logo、细密格栅、透明/折射材质。 这些都是常见的失败类型。[Heuristic]

任务模型（API 的实际工作方式）——[Doc]，验证于 2026-07-10

一切都是异步任务。提交任务后会收到 task_id，然后轮询（或接收 Webhook），直至任务成功，再读取输出 URL。

• 基础 URL： https://api.tripo3d.ai/v2/openapi
• **身份验证：**请求头 Authorization: Bearer YOUR_API_KEY。在 platform.tripo3d.ai/api-keys 创建密钥。
• **创建任务：**使用 JSON 请求体调用 POST /v2/openapi/task，其中 type 用于选择操作。
• **轮询任务：**调用 GET /v2/openapi/task/{task_id}。响应包含 status、progress、output（下载 URL）以及 consumed_credit（该任务实际扣除的积分数）。
• 状态值：queued → running → success（也可能为 failed、cancelled、banned、expired、unknown）。轮询直至任务进入终态；成功后从 output 读取模型 URL。
• **上传：**输入图像可以通过 url（公开的 JPEG/PNG，最大 20 MB）、直接上传得到的 file_token，或 STS 上传得到的 object（bucket: "tripo-data"，key: <resource_uri>）传入。STS 上传是 Tripo 推荐的方式。输出下载 URL 有时效限制，请及时获取并保存。
• **任务串联：**后处理任务通过任务 ID 引用之前的任务（original_model_task_id / draft_model_task_id），因此模型 → 纹理 → 骨骼绑定 → 格式转换的流程是一系列任务，而不是每次都重新上传。

[Heuristic] 采用退避策略轮询（例如先等 2 s，再等 3–5 s），而不要紧密循环；生成耗时从几秒到几分钟不等，具体取决于模型和选项。对于批量或生产环境，如果集成方式支持 Webhook，优先使用 Webhook（原生 Webhook 支持因 API 接口和 fal/Runware 等代理提供商而异；后者会提供类似 X-Webhook-URL 的请求头 [3P]，验证于 2026-07-10。依赖此功能前，请先对照当前 Tripo 文档确认；否则请轮询）。

模型版本——[Doc]/[1P]，验证于 2026-07-10

在生成任务中通过 model_version 选择。该信息可能变动，请重新查看更新日志。

系列	API model_version / 选择器	特点	面数／多边形数范围
v3.0（HD / "H3"）	v3.0-20250812	稳定，通用默认选项	最高约 1M–1.5M 个三角面 [Doc]
v3.1（HD / "H3.1"）	v3.1-20260211	几何密度更高、边缘更锐利、PBR 效果更出色	最高约 1.5M–2M 个三角面 [Doc]
P1（Smart Mesh P1.0）	p1 选择器（高级套餐）	原生 3D 扩散、适用于游戏的低多边形模型、方向控制、随机种子；速度极快	约 48–20,000 个面 [Doc/1P]

• v3.0——需要最高细节并计划之后重新拓扑时，适合作为稳妥的通用默认选项。[Heuristic]
• v3.1——需要“主视觉级”细节时可选：几何更密集，PBR 响应更好；计算资源和时间成本更高。主打主视觉级游戏资产、电影和产品展示图。[1P]
• P1——需要直接获得可用于引擎、且可控的低多边形模型时可选：可设置目标面数预算（face_limit 48–20,000）和 orientation（default 或 align_image），让资产朝向可预测的轴。该架构于 GDC 2026 发布，采用原生 3D 扩散技术，可在数秒内生成低多边形资产。[1P] 每个任务的积分成本高于 v3.x。旧版 Turbo-v1.0、v1.4 和 H2 也仍可用于旧版或低成本流程。[Doc]

营销名称“Hxx”与 API 的 model_version 字符串拼写并不完全一致——始终使用当前文档中的精确 model_version 字符串调用 API，不要使用博客中的名称。

生成任务及其参数——[Doc]，验证于 2026-07-10

text_to_model

• type: "text_to_model"、model_version、prompt（≤ 1024 个字符；支持多语言；不支持表情符号和特殊 Unicode 字符）。
• 可选：negative_prompt（≤ 255）、image_seed、model_seed、texture_seed、style。

image_to_model

• type: "image_to_model"、model_version，以及一个 file（通过 file_token | url | object 提供）。
• enable_image_autofix 可清理输入；texture_alignment 和 orientation 可控制纹理和资产朝向与图像的匹配方式。

multiview_to_model

• type: "multiview_to_model"，files = 一个有序列表 [front, left, back, right]。
• 必须提供正面视图；其他视图可以省略（对应位置留空）。至少使用 2 个视图。 视图越一致 → 背面／侧面重建效果越好。[Doc]

通用生成控制项

• texture（bool，默认值为 true；设为 false 仅生成几何体时可节省约 10 点数）。
• pbr（bool，默认值为 true）——生成适用于受光渲染流程的 PBR 贴图（基础色／金属度-粗糙度／法线）。
• texture_quality："standard"（默认值）或 "detailed"（+10 点数）。
• geometry_quality：在支持的版本中可选 "standard" 或 "detailed"（+20 点数）。
• face_limit（int）——限制输出三角形数量；这是控制引擎预算的实用参数。
• quad（bool，默认值为 false，+5 点数）——以四边形为主进行重网格化，获得更清晰的边流／细分效果。
• smart_low_poly（bool，默认值为 false，+10 点数）——在生成时自动低多边形化。
• auto_size（bool）——规范化真实世界的比例；compress 用于缩小 GLB；export_uv；generate_parts （+20 点数）用于拆分为带名称的部件；style 用于选择风格化几何体预设。

后处理流程 — [Doc]，已于 2026-07-10 验证

每个操作都会引用先前任务的 id，因此你可以在不重新生成的情况下进行优化：

• texture_model——为现有网格重新贴图。关键输入：original_model_task_id、texture、pbr、 texture_quality、texture_alignment、texture_seed、part_names、bake，以及用于调整外观的 text_prompt、 image_prompt 或 style_image。
• refine_model——优化草稿网格（draft_model_task_id）。
• mesh_segmentation（40 点数）／mesh_completion（50 点数）——拆分为多个部件／填补孔洞并完成 部分几何体。
• smart_lowpoly（30 点数）——将高多边形网格重新拓扑为低多边形网格，可使用 face_limit、quad、bake、part_names。
• stylize_model——应用风格化 style：LEGO、VOXEL、VORONOI、MINECRAFT，并设置 block_size。

骨骼绑定与动画 — [Doc]，已于 2026-07-10 验证

1. check_riggable（type: "check_riggable"，免费）——在付费绑定骨骼之前，验证网格是否可自动绑定。对于角色，务必先进行此项检查。
2. rig_model（25 点数）——自动绑定骨骼。参数：original_model_task_id、out_format（"glb" | "fbx"）、 rig_type、spec（骨架规格，例如 humanoid）。自动绑定骨骼要求网格大致直立、对称，且只包含一个角色，四肢清晰分离。[Heuristic]
3. retarget_animation（每个动画 10 点数）——为绑定骨骼的网格应用预设动作。 animation 接受一个或一组 "preset:<name>" 值：preset:idle、preset:walk、preset:run、 preset:jump、preset:climb、preset:dive、preset:fall、preset:turn、preset:slash、 preset:shoot、preset:hurt，以及适用于非人形角色的四足、六足、八足、蛇形和水生变体。 out_format、bake_animation 和 export_with_geometry 用于控制导出的动画片段。

格式转换／导出 — [Doc]，已于 2026-07-10 验证

• convert_model——original_model_task_id + format ∈ GLTF、USDZ、FBX、OBJ、STL、3MF （基础费用 5 点数，使用额外选项时 +5）。原生生成输出为 GLB；请转换为目标格式。
  • 引擎／工具映射 [Heuristic]：Unity／Unreal → FBX 或 glTF/GLB；Blender → GLB/glTF 或 FBX；USD 工作流／Apple AR Quick Look → USDZ；3D 打印 → STL 或 3MF（STL 会丢失颜色；3MF 会保留颜色／材质）。

提示词和输入图像策略 — [启发式]，另有标注的除外

文本转 3D 提示词描述的是一个物体，而非场景：主体 + 形状 + 材质 + 风格。具体描述轮廓和材质（“一个低多边形风格的木质宝箱，带铁箍，箱盖关闭”）。 使用 negative_prompt 来抑制反复出现的瑕疵（“多余的肢体、悬浮的部件、文字”）。文本转 3D 对不可见的侧面存在固有歧义；请准备迭代调整 model_seed/image_seed。

在保真度和可控性方面，图像转 3D/多视图优于文本。 要获得最佳单图效果：

• 主体干净、居中，背景为纯色或透明；主体填满画面的大部分区域。
• 光照均匀、中性；避免硬阴影/高光过曝被模型烘焙进几何体/纹理中。
• 对于单图输入，约 3/4 角度的“主视觉”视角比平面正交正面更能体现体积感。
• 设置 orientation/texture_alignment，确保生成的资产朝向和纹理与图像保持一致。

多视图是可控性最高的方案：提供同一物体一致的正面/左侧/背面/右侧渲染图（光照、比例相同）。这能解决单图和文本输入常见的“背面幻觉”问题。正面必不可少；有多少真实视角就添加多少。

迭代与修复工作流 — [启发式]

1. 先进行低成本初次尝试： 使用 texture:false（仅几何体）或较低档位生成，以便在花费纹理成本前评估形状。先确定轮廓，再使用 texture_model 为选中的几何体重新生成纹理，而不是重新生成模型。
2. 先更换种子，而不是提示词。 如果几何体有 80% 符合预期，先多次重新生成 model_seed，再改写提示词。
3. 有目的地逐级提升模型档位： v3.0 → v3.1 以增加细节；只有在确实需要可控的低多边形/定向游戏资产时才使用 P1。不要为 v3.1 的细节付费后又马上对其进行抽稀。
4. 修复，而非重新生成： 有孔洞 → mesh_completion；过于密集 → smart_lowpoly/quad；部件粒度不合适 → mesh_segmentation；只有纹理不好 → texture_model。
5. 先检查再绑定： 在运行 rig_model 前运行 check_riggable；如果检查失败，通常需要先清理网格，确保其直立且四肢拓扑彼此分离。

检查生成的网格质量 — [启发式]

发布 Tripo 资产前，请检查：

• 面数与预算 — face_limit 是否达到所需范围？超出预算 → smart_lowpoly。
• 拓扑 — 原始输出由三角面构成，且通常不均匀；如果资产需要变形（绑定）或细分，应要求进行四边面重网格化/重拓扑。直接用于静态道具则可以接受原始三角网格。
• 水密性/流形性 — 3D 打印必需；检查是否存在孔洞、非流形边和翻转法线。
• UV 和纹理 — 检查接缝、拉伸、烘焙光照，以及文字/徽标上的细节分辨率是否过低。如果 pbr:true，应包含 PBR 贴图。若几何体良好但表面效果不佳，请重新生成纹理。
• 比例和轴心/朝向 — 确认实际尺寸（auto_size），以及轴心/朝向是否符合引擎约定（P1 的 orientation 有助于此）。
• 对称性和悬浮部件 — 检查是否存在不对称、脱落碎片、融合部件（使用 generate_parts / segmentation 进行分离）。

额度、费用和速率限制 — [Doc]/[3P]，已于 2026-07-10 验证

按额度计费：$1.00 = 100 个额度。新账户可获得 300 个免费额度，有效期约 2 周。 每个任务响应都会报告精确的 consumed_credit。有代表性的任务价格 [Doc]（可能变动）：

操作	v3.0/v3.1 (H2/H3)	P1
text_to_model	10（无 tex）/ 20（有 tex）	30 / 40
image_to_model	20 / 30	40 / 50
multiview_to_model	20 / 30	40 / 50
import model	免费	—

附加项 [Doc]：精细纹理 +10，智能低多边形 +10，四边面 +5，生成部件 +20， 精细几何体 +20。后处理：绑定 25，每个动画重定向 10，绑定前检查免费， mesh_segmentation 40，mesh_completion 50，smart_lowpoly 30，转换 5（使用选项时 +5）。

消费者版/Studio 订阅与 API 额度购买不同。报告的套餐等级 [3P]，已于 2026-07-10 验证：Basic 免费（每月约 300 个额度，1 个并发任务）、Pro/Professional 约 $15.90/月 （约 3,000 个额度，约 10 个并发任务）、Advanced 约 $39.90/月（约 8,000 个额度，约 15 个并发任务）。请将具体的美元/额度数值和套餐名称视为可能变动；引用前请在 tripo3d.ai/pricing 确认。

速率限制：超过限制会返回 HTTP 429；并发任务限制因套餐而异 （免费套餐约为 1）。错误中包含 code、message 和 suggestion（例如，代码 2002 = 不支持的任务类型）。 遇到 429 时应进行退避，并通过排队遵守并发上限。[Doc/3P]

权利与许可 — 请仔细阅读，这确实存在风险

[Doc/1P]，已于 2026-07-10 验证：

• 在 免费版/Basic 套餐中，生成的模型通常会公开发布，并以类似 Creative Commons CC BY 4.0 的许可发布——也就是说，其他人可以在注明出处的情况下使用这些模型，而你无法获得私有/独占资产。请勿将免费套餐的输出视为机密或独占内容。
• 付费套餐可解锁私有模型，并授予你对所生成几何体的商业使用权；生产、零售和打印用途都需要此权限。
• Tripo 的运营实体保留其软件、模型和技术的全部知识产权（背景知识产权）；许可涉及的是你生成的资产，而非平台。

[Heuristic] 给 Agent 的实用建议：

• 对于任何商业交付物，请使用付费套餐生成，并自行确认当前条款 （tripo3d.ai/terms）——许可措辞会变动，CC BY 4.0 中“注明出处后可用于商业用途”的细节也很容易被误读。未经核实套餐和条款，请勿声称“你拥有该资产，享有完整商业权利”。
• 你仍需对输入内容负责：请勿输入你无权使用的受版权保护或带品牌标识的角色、受商标保护的设计，或可识别真实人物的图像，也不要将这些内容洗成“生成”资产。生成器不会授予你原始素材中本就没有的权利。
• 对于商业销售的 3D 打印产品，请同时确认 Tripo 许可套餐，并确保设计本身不构成侵权。

完整示例（仅供说明，并非必需公式）

意图： 根据概念图制作可用于 Unity 的游戏预算风格化木桶道具，然后转换为 FBX。提供商/模型： Tripo OpenAPI，P1（需要可控的低多边形模型和方向明确的资产）。

# 1) Create an image_to_model task with P1, budgeting ~4k faces, PBR on, image-aligned orientation.
curl -s https://api.tripo3d.ai/v2/openapi/task \
  -H "Authorization: Bearer $TRIPO_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "type": "image_to_model",
        "model_version": "p1",
        "file": { "type": "png", "url": "https://example.com/barrel_ref.png" },
        "face_limit": 4000,
        "texture": true,
        "pbr": true,
        "texture_quality": "detailed",
        "orientation": "align_image",
        "auto_size": true
      }'
# -> { "code":0, "data": { "task_id": "TASK_A" } }

# 2) Poll until success, then read output URLs and consumed_credit.
curl -s https://api.tripo3d.ai/v2/openapi/task/TASK_A \
  -H "Authorization: Bearer $TRIPO_API_KEY"
# status: queued -> running -> success; data.output has the GLB URL. Download it promptly (URL expires).

# 3) Convert the finished GLB to FBX for the Unity project (chained by task id).
curl -s https://api.tripo3d.ai/v2/openapi/task \
  -H "Authorization: Bearer $TRIPO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type":"convert_model", "original_model_task_id":"TASK_A", "format":"FBX" }'

采用这种结构的原因： 使用 P1 并明确设置 face_limit，可直接生成符合游戏预算的网格，而不是需要再进行抽稀的百万三角形网格；orientation:"align_image" 可让枢轴和朝向保持可预测，便于关卡设计；纹理和 PBR 可提供适用于光照管线的贴图；转换是基于同一 id 执行的低成本链式任务。 预期结果： 一个约 4k 三角形、带纹理的木桶，先生成 GLB，再转换为 FBX。可能的失败模式： 强烈的参考照片导致阴影被烘焙进模型（解决方法：使用光线更均匀的图片，或启用 enable_image_autofix）；模型凭空生成背面细节（解决方法：提供多视图图片组）；拓扑三角化程度过高，不利于后续变形（解决方法：设置 quad:true 或执行 smart_lowpoly 处理）。变体： 改用 multiview_to_model，并提供正面、背面、左侧和右侧渲染图，以忠实还原主角道具；也可以切换到 v3.0 并设置 texture:false，在投入额度前快速检查纯几何轮廓。

来源（已于 2026-07-10 核实）

• Tripo OpenAPI 文档——简介、快速入门、定价、模型生成页面：https://docs.tripo3d.ai/
• 官方 Python SDK API 参考（任务类型、参数、动画预设）： https://github.com/VAST-AI-Research/tripo-python-sdk/blob/master/docs/API.md
• Tripo 平台文档（计费、速率限制、错误处理、动画）：https://platform.tripo3d.ai/docs
• Tripo API 产品页面：https://www.tripo3d.ai/api；定价：https://www.tripo3d.ai/pricing
• Tripo 博客——H3.1 / Smart Mesh P1.0 公告（第一方声明）：https://www.tripo3d.ai/blog
• 条款 / 许可：https://www.tripo3d.ai/terms 和 tripo3d.ai 上的 3D 打印版权指南
• 第三方资料（已注明，供参考）：apidog 开发者指南 https://apidog.com/blog/how-to-use-tripo-3d-api/；3D AI Studio 的 Tripo P1 文档；fal / Runware 的 Tripo 模型页面（代理 Webhook 行为）