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

# 图像生成 3D 模型 — P 系列 **Base URL:** `https://openapi.tripo3d.ai/v3` **Endpoint:** `POST /generation/image-to-model` 使用 P 系列根据图像生成 3D 模型。针对低面数输出和干净拓扑优化。 ## Request Parameters ### input - **Type:** string - **Required:** 必选 图像来源。主体应清晰可见，遮挡最少。 接受以下输入类型：**以下三种方式任选其一**，不可同时传入多种类型。 - file_token：先通过[文件上传 API](http://localhost:4173/docs/files)上传图像，然后传入返回的 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**。主体应清晰可见，背景干净，遮挡尽量少。 ### model - **Type:** string - **Required:** 必选 P 系列模型版本。 - `P1-20260311`：针对低面数生成优化。 ### enable_image_autofix - **Type:** boolean - **Required:** 可选 - **Default:** `false` 是否在生成前自动优化输入图像。启用后，系统将增强低分辨率或低质量图像以改善 3D 生成效果。默认为 false。 ### texture_alignment - **Type:** string - **Required:** 可选 - **Default:** `original_image` 贴图对齐优先级。 - `original_image`：优先匹配输入图像的颜色。 - `geometry`：优先匹配生成的几何体。 ### orientation - **Type:** string - **Required:** 可选 - **Default:** `default` 模型朝向。 - `default`：自动朝向。 - `align_image`：将模型对齐至输入图像的视角。 仅当 `texture` 为 `true` 时生效。未开启贴图时此参数无效。 ### model_seed - **Type:** integer - **Required:** 可选 几何体生成的随机种子。使用相同种子和相同输入将生成相同的 3D 网格。若未设置，每次会使用随机种子。 ### face_limit - **Type:** integer - **Required:** 可选 输出网格的最大面数。 - 支持范围：**50 – 20,000** - 省略时自适应确定面数。 最佳质量建议：简单模型从 **150** 面起步，复杂模型从 **250** 面起步。面数过低可能导致生成质量下降。 ### texture - **Type:** boolean - **Required:** 可选 - **Default:** `true` 是否为模型生成贴图。设为 false 可获取无贴图的纯几何体。默认为 true。 ### pbr - **Type:** boolean - **Required:** 可选 - **Default:** `true` 启用 PBR 材质贴图（`base_color`、`metallic`、`roughness`、`normal`）。当 `pbr` 设为 `true` 时，`texture` 会自动强制设为 `true`。 ### texture_seed - **Type:** integer - **Required:** 可选 贴图生成的随机种子。使用相同种子将生成相同的贴图。若未设置，每次会使用随机种子。如需获取相同几何体但不同贴图的模型，请保持 model_seed 不变并更改 texture_seed。 ### texture_quality - **Type:** string - **Required:** 可选 - **Default:** `standard` 贴图质量等级。 - `standard`：质量与速度的平衡。 - `detailed`：更高保真度，生成速度较慢。 - `extreme`：8K 贴图，最高保真度。相比 detailed 额外消耗积分。 ### auto_size - **Type:** boolean - **Required:** 可选 - **Default:** `false` 是否自动将生成的模型缩放至真实世界尺寸。启用后，模型尺寸将以米为单位，适用于 AR/VR 或游戏引擎场景。默认为 false。 ### compress - **Type:** string - **Required:** 可选 压缩类型。 - `geometry`：meshopt 压缩，减小文件体积。 - 以下参数仅在 `model ≥ v3.0-20250812` 时有效：`texture_quality`、`geometry_quality`、`auto_size`、`quad`、`smart_low_poly`、`generate_parts`、`compress`。 ### export_uv - **Type:** boolean - **Required:** 可选 - **Default:** `true` 控制 UV 展开。设为 `false` 可加快生成速度并减小文件体积。 ## Request Example ### P 系列示例 ```bash curl --request POST \ --url https://openapi.tripo3d.ai/v3/generation/image-to-model \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "input": "https://example.com/image.png", "model": "P1-20260311", "face_limit": 5000, "texture": true, "pbr": true }' ``` ## Response Example ### 创建任务 ```json { "code": 0, "data": { "task_id": "task_abc123" } } ``` ### 任务结果 ```json { "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, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z" } } ```

{
  "input": "https://example.com/image.png",
  "model": "P1-20260311",
  "face_limit": 5000,
  "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,
    "created_at": "2026-04-28T12:00:00Z",
    "completed_at": "2026-04-28T12:01:30Z"}
}