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

**Base URL:** `https://openapi.tripo3d.com/v3`

**Endpoint:** `POST /generation/multiview-to-model`

使用 P 系列根据多视图图像生成 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:** 必选

P 系列模型版本。
- `P1-20260311`：针对低面数生成优化。
- `P2-20260801`：新一代 P 系列，支持四边面输出。 preview版

### 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:** 可选

输出网格的最大面数。


- `P1-20260311`：**50 – 20,000**
- `P2-20260801` 三角面：**48 – 50,000**；`quad=true` 时：**48 – 25,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。
### export_uv

- **Type:** boolean
- **Required:** 可选
- **Default:** `true`

控制 UV 展开。设为 `false` 可加快生成速度并减小文件体积。
### export_orientation

- **Type:** string
- **Required:** 可选
- **Default:** `+x`

导出朝向（前向轴）。
- `+x`：默认，X 轴正方向朝前。
- `-x`：X 轴负方向朝前。
- `-y`：Y 轴负方向朝前。
- `+y`：Y 轴正方向朝前。



- 仅作用于本次生成。如需用于后续的贴图、绑定、重定向、格式转换等后处理任务，不建议设置该参数。
- 设置该参数后，用于其他后处理任务时，可能因模型方向错误影响最终效果，但任务状态仍为`success`、不会报错，请谨慎使用该参数。
- 若计划对模型做后处理，建议本参数留空，改为在最后一步用`/v3/models/convert` 转换朝向。

### quad

- **Type:** boolean
- **Required:** 可选
- **Default:** `false`

**仅 P2-20260801 支持。**是否输出四边面网格。

## 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": "P1-20260311",
  "texture": true,
  "pbr": true
}'
```

### P2 系列示例

```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"
    }
  ],
  "model": "P2-20260801",
  "quad": true,
  "texture": true,
  "pbr": true
}'
```

### 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": "P1-20260311",
  "texture": true,
  "pbr": true
}'
```

### 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": "P1-20260311",
  "texture": true,
  "pbr": true
}'
```

### 复用多视图任务

```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": "P1-20260311",
  "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"
  }
}
```