Tripo3D

图像生成 3D 模型 — P 系列

http
Base URL: https://openapi.tripo3d.ai/v3
Endpoint: POST /generation/image-to-model
使用 P 系列根据图像生成 3D 模型。针对低面数输出和干净拓扑优化。
注意
  • 此接口需要 API Key 认证。请在 Authorization 请求头中传入 Bearer {api_key}。
  • 此接口为异步 API。提交请求后，请使用 任务查询接口 轮询获取结果，或配置 Webhook 接收任务完成时的自动通知。

请求参数

请求体

inputstring必选
图像来源。主体应清晰可见，遮挡最少。 接受以下输入类型：
以下三种方式任选其一，不可同时传入多种类型。
  • file_token：先通过文件上传 API上传图像，然后传入返回的 token。
    示例： file_abc123
  • URL：可公开访问的图像直链。
    示例： https://example.com/photo.png
  • task_id：此前图像生成任务（text_to_image 或 image_to_image）返回的任务 ID。系统会自动提取输出图像。
    示例： task_abc123
说明
  • 支持格式：PNG、JPEG、WebP
  • 最大文件大小：20 MB
  • 推荐分辨率：至少 256 × 256 px。主体应清晰可见，背景干净，遮挡尽量少。
modelstring必选
P 系列模型版本。调用 P 系列必须指定；不传会按默认的 H 系列 v3.1-20260211 生成。
  • P1-20260311：针对低面数生成优化。
  • P2-20260801：新一代 P 系列，支持四边面输出。 预览版
enable_image_autofixboolean默认值: false
是否在生成前自动优化输入图像。用于AI补全和3D效果增强。启用后，系统将增强低分辨率或低质量图像以改善 3D 生成效果。默认为 false。
texture_alignmentstring默认值: original_image
贴图对齐优先级。
  • original_image：优先匹配输入图像的颜色。
  • geometry：优先匹配生成的几何体。
orientationstring默认值: default
模型朝向。
  • default：自动朝向。
  • align_image：将模型对齐至输入图像的视角。
仅当 texture 为 true 时生效。未开启贴图时此参数无效。
model_seedinteger
几何体生成的随机种子。使用相同种子和相同输入将生成相同的 3D 网格。若未设置，每次会使用随机种子。
face_limitinteger
输出网格的最大面数。
说明
  • P1-20260311：50 – 20,000
  • P2-20260801 三角面：48 – 50,000；quad=true 时：48 – 25,000
  • 省略时自适应确定面数。
最佳质量建议：简单模型从 150 面起步，复杂模型从 250 面起步。面数过低可能导致生成质量下降。
textureboolean默认值: true
是否为模型生成贴图。设为 false 可获取无贴图的纯几何体。默认为 true。
pbrboolean默认值: true
启用 PBR 材质贴图（base_color、metallic、roughness、normal）。
当 pbr 设为 true 时，texture 会自动强制设为 true。
texture_seedinteger
贴图生成的随机种子。使用相同种子将生成相同的贴图。若未设置，每次会使用随机种子。如需获取相同几何体但不同贴图的模型，请保持 model_seed 不变并更改 texture_seed。
texture_qualitystring默认值: standard
贴图质量等级。
  • fast：生成最快，以细节换速度；输出贴图尺寸与 standard 相同。 需要贴图版本 v3.5-20260815；积分与 standard 相同。
  • standard：质量与速度的平衡。
  • detailed：更高保真度，生成速度较慢。
  • extreme：8K 贴图，最高保真度。相比 detailed 额外消耗积分。
说明
fast 仅在贴图版本 v3.5-20260815 下可用。生成接口需将 texture_version 设为该版本；/v3/models/texture 则是 model。其它贴图版本会返回 1004，不会静默回退到 standard。
texture_versionstring
独立指定贴图模型，与几何体 model 解耦。
  • v3.5-20260815：最新贴图模型。使用 texture_quality=fast 与 delight 时必填。
  • v3.0-20250812：v3.x 与 P 系列几何体的默认值。
  • v2.5-20250123：v2.5-20250123 几何体的默认值。
省略时按上表根据几何体 model 自动推导。
delightboolean默认值: true
贴图前去除参考图中的光照信息。设为 false 可保留原有明暗。仅 v3.5-20260815 贴图模型支持，更早的贴图版本会忽略该参数。
auto_sizeboolean默认值: false
是否自动将生成的模型缩放至真实世界尺寸。启用后，模型尺寸将以米为单位，适用于 AR/VR 或游戏引擎场景。默认为 false。
export_uvboolean默认值: true
控制 UV 展开。设为 false 可加快生成速度并减小文件体积。
export_orientationstring默认值: +x
导出朝向（前向轴）。
  • +x：默认，X 轴正方向朝前。
  • -x：X 轴负方向朝前。
  • -y：Y 轴负方向朝前。
  • +y：Y 轴正方向朝前。
说明
  • 仅作用于本次生成。如需用于后续的贴图、绑定、重定向、格式转换等后处理任务，不建议设置该参数。
  • 设置该参数后，用于其他后处理任务时，可能因模型方向错误影响最终效果，但任务状态仍为success、不会报错，请谨慎使用该参数。
  • 若计划对模型做后处理，建议本参数留空，改为在最后一步用/v3/models/convert 转换朝向。
quadboolean默认值: false
仅 P2-20260801 支持。是否输出四边面网格。

示例

P 系列示例
{
  "input": "https://example.com/image.png",
  "model": "P1-20260311",
  "face_limit": 5000,
  "texture": true,
  "pbr": true
}
P2 系列示例
{
  "input": "https://example.com/image.png",
  "model": "P2-20260801",
  "quad": true,
  "texture": true,
  "pbr": true
}
创建任务
{
  "code": 0,
  "data": {
    "task_id": "task_abc123"}
}
任务结果
{
  "code": 0,
  "data": {
    "task_id": "task_abc123",
    "type": "text_to_model",
    "status": "success",
    "progress": 100,
    "output": {
      "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb",
      "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"},
    "credits_consumed": 100.00,
    "created_at": "2026-04-28T12:00:00Z",
    "completed_at": "2026-04-28T12:01:30Z"}
}
上一个图片生成 3D 模型 — H 系列下一个多视图生成 3D 模型 — H 系列