多视图生成 3D 模型 — H 系列

# 多视图生成 3D 模型 — H 系列 **Base URL:** `https://openapi.tripo3d.com/v3` **Endpoint:** `POST /generation/multiview-to-model` 根据多视图图像生成 3D 模型。多角度输入可提高几何体精度和贴图覆盖度。 ## Request Parameters ### inputs - **Type:** object[] | string[] - **Required:** 必选 **三种格式三选一，不可混用。** - **view-key（推荐）**：对象数组，每项仅含一个键 `front`/`left`/`back`/`right`；值为 URL、`file_token` 或嵌套 `{url}` / `{file_token}` / `{object:{bucket,key}}`。顺序无关，服务端规范为 **[正面、左侧、背面、右侧]**。 - **legacy positional**：固定 4 个字符串，顺序为 **[front, left, back, right]**；无图视角传空字符串 `""`。 - **task_id**：传入此前 图像生成多视图 或编辑多视图任务的 ID，直接复用其 4 视角输出。仅接受 `[{"task_id":"<uuid>"}]`（单元素数组），不可与 view-key 或 positional 混用。原任务须为 `success`，类型为 `generate_multiview_image` 或 `edit_multiview_image`。 view-key 与 legacy positional 中，每个图像值支持： - file_token：先通过文件上传 API上传图像，然后传入返回的 token。 示例： `file_abc123` - URL：可公开访问的图像直链。 示例： `https://example.com/front.png` - 正面视图**不可省略**。其他视图可省略，但至少需要 2 张图像。 - 所有图像应在一致光照下拍摄同一物体。 - 支持格式：`PNG`、`JPEG`、`WebP` - 推荐分辨率：至少 **256 × 256 px**。 ### model - **Type:** string - **Required:** 必选 AI 模型版本。 - `v3.1-20260211`：最新版，最佳质量。 - `v3.0-20250812`：稳定版，高级功能。 - `v2.5-20250123`：均衡版。 ### texture_alignment - **Type:** string - **Required:** 可选 - **Default:** `original_image` 贴图对齐优先级。 - `original_image`：优先匹配输入图像的颜色。 - `geometry`：优先匹配生成的几何体。 ### orientation - **Type:** string - **Required:** 可选 - **Default:** `default` 模型朝向。 - `default`：自动朝向。 - `align_image`：将模型对齐至输入图像的视角。 仅当 `texture` 为 `true` 时生效。未开启贴图时此参数无效。 ### face_limit - **Type:** integer - **Required:** 可选 输出网格的最大面数。 - 省略时模型使用自适应拓扑。 各模式面数上限 | 模式 | 标准 | 超清 | | 纯三角面 — v3.1 | **1,500,000** | **2,000,000** | | 纯三角面 — v3.0 | **1,000,000** | **2,000,000** | | 纯三角面 — v2.5 | **500,000** | / | | 四边面（`quad: true`） | **150,000** | - 游戏资产推荐：**50,000 – 100,000**。Web/移动端：**10,000 – 50,000**。 - 开启 `smart_low_poly: true` 时，面数限制与模型版本无关，统一为： 三角面 **500 – 20,000**，四边面 **500 – 10,000**。 ### 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 额外消耗积分。 ### geometry_quality - **Type:** string - **Required:** 可选 - **Default:** `standard` 几何体质量等级。 - `standard`：质量与速度的平衡。 - `detailed`：Ultra 模式，更精细的几何细节。 该参数只对 v3.0 以上模型版本生效，v2.5 切勿使用该参数。 ### auto_size - **Type:** boolean - **Required:** 可选 - **Default:** `false` 是否自动将生成的模型缩放至真实世界尺寸。启用后，模型尺寸将以米为单位，适用于 AR/VR 或游戏引擎场景。默认为 false。 ### quad - **Type:** boolean - **Required:** 可选 - **Default:** `false` 是否输出四边面网格（四边形多边形）而非三角面。若未设置 `face_limit`，默认面数为 10,000。启用 `quad` 会强制输出格式为 `FBX`。 ### smart_low_poly - **Type:** boolean - **Required:** 可选 - **Default:** `false` 是否生成具有手工风格、干净拓扑的低面数模型。最适合简单、非复杂的输入。复杂模型可能偶尔失败。默认为 false。 ### generate_parts - **Type:** boolean - **Required:** 可选 - **Default:** `false` 生成可编辑的分割部件。与 `texture`、`pbr`、`quad`、`smart_low_poly` 不兼容： - `texture=true` 或 `pbr=true`（包括不传 `texture`，其默认值为 `true`）—— 请求被拒绝，返回错误码 `1004`。 - `quad=true` —— quad 被忽略，返回的分块为三角面网格。 - `smart_low_poly=true` —— smart_low_poly 优先，不会产出分块。 如需生成分块，请设置 `texture=false` 与 `pbr=false`，且不要传 `quad` 与 `smart_low_poly`。 ### compress - **Type:** string - **Required:** 可选 压缩类型。 - `geometry`：meshopt 压缩，减小文件体积。 - 以下参数仅在 `model ≥ v3.0-20250812` 时有效：`texture_quality`、`geometry_quality`、`auto_size`、`quad`、`smart_low_poly`、`generate_parts`、`compress`。 ### export_orientation - **Type:** string - **Required:** 可选 - **Default:** `+x` 导出朝向（前向轴）。 - `+x`：默认，X 轴正方向朝前。 - `-x`：X 轴负方向朝前。 - `-y`：Y 轴负方向朝前。 - `+y`：Y 轴正方向朝前。 - 仅作用于本次生成。如需用于后续的贴图、绑定、重定向、格式转换等后处理任务，不建议设置该参数。 - 设置该参数后，用于其他后处理任务时，可能因模型方向错误影响最终效果，但任务状态仍为`success`、不会报错，请谨慎使用该参数。 - 若计划对模型做后处理，建议本参数留空，改为在最后一步用`/v3/models/convert` 转换朝向。 ### model_seed - **Type:** integer - **Required:** 可选 几何体生成的随机种子。使用相同种子和相同输入将生成相同的 3D 网格。若未设置，每次会使用随机种子。 ### export_uv - **Type:** boolean - **Required:** 可选 - **Default:** `true` 控制生成过程中的 UV 展开。设为 `false` 可加快生成速度并减小文件体积。UV 展开将在贴图阶段处理。 ## Request Example ### view-key + URL ```bash curl --request POST \ --url https://openapi.tripo3d.com/v3/generation/multiview-to-model \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "inputs": [ { "front": "https://example.com/front.png" }, { "back": "https://example.com/back.png" }, { "right": "https://example.com/right.png" } ], "model": "v3.1-20260211", "texture": false, "geometry_quality": "detailed" }' ``` ### view-key + file_token ```bash curl --request POST \ --url https://openapi.tripo3d.com/v3/generation/multiview-to-model \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "inputs": [ { "front": "3154b4b0-4647-4032-aa82-827441ae92ef" }, { "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d" }, { "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6" } ], "model": "v3.1-20260211", "texture": false, "geometry_quality": "detailed" }' ``` ### legacy positional ```bash curl --request POST \ --url https://openapi.tripo3d.com/v3/generation/multiview-to-model \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "inputs": [ "https://example.com/front.png", "", "https://example.com/back.png", "https://example.com/right.png" ], "model": "v3.1-20260211", "texture": true, "pbr": true, "texture_quality": "detailed" }' ``` ### 复用多视图任务 ```bash curl --request POST \ --url https://openapi.tripo3d.com/v3/generation/multiview-to-model \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "inputs": [ { "task_id": "550e8400-e29b-41d4-a716-446655440000" } ], "model": "v3.1-20260211", "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.00, "created_at": "2026-04-28T12:00:00Z", "completed_at": "2026-04-28T12:01:30Z" } } ```

{
  "inputs": [
    {
      "front": "https://example.com/front.png"},
    {
      "back": "https://example.com/back.png"},
    {
      "right": "https://example.com/right.png"}
  ],
  "model": "v3.1-20260211",
  "texture": false,
  "geometry_quality": "detailed"}

{
  "inputs": [
    {
      "front": "3154b4b0-4647-4032-aa82-827441ae92ef"},
    {
      "back": "58ea3eab-6a08-4deb-98f9-e60f1802954d"},
    {
      "right": "584b0e07-8576-4eb4-bf49-2e149e0252f6"}
  ],
  "model": "v3.1-20260211",
  "texture": false,
  "geometry_quality": "detailed"}

{
  "inputs": [
    "https://example.com/front.png",
    "",
    "https://example.com/back.png",
    "https://example.com/right.png"],
  "model": "v3.1-20260211",
  "texture": true,
  "pbr": true,
  "texture_quality": "detailed"}

{
  "inputs": [
    {
      "task_id": "550e8400-e29b-41d4-a716-446655440000"}
  ],
  "model": "v3.1-20260211",
  "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"}
}