# 模型格式转换

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

**Endpoint:** `POST /models/convert`

将 3D 模型转换为其他格式，支持可选的网格处理、贴图烘焙和导出设置。

## Request Parameters

### input

- **Type:** string
- **Required:** 必选

模型来源。接受 task_id 或 file_token。 接受以下输入类型：**以下三种方式任选其一**，不可同时传入多种类型。

- task_id：此前 3D 生成任务（`text_to_model`、`image_to_model` 或 `multiview_to_model`）返回的任务 ID。系统会自动使用该任务的 3D 模型输出。
示例： `task_abc123`
- file_token：先通过[文件上传 API](http://localhost:4173/docs/files)上传 3D 模型文件，然后传入返回的 token。
示例： `file_abc123`
- URL：可公开访问的 3D 模型文件直链。
示例： `https://example.com/model.glb`



- 支持格式：`GLB`、`GLTF`、`FBX`、`OBJ`、`STL`
- 最大文件大小：**150 MB**

### format

- **Type:** string
- **Required:** 必选

目标导出格式。
- `GLTF`：Web 查看器、WebGL 引擎。
- `FBX`：Unreal、Unity、DCC 工具。
- `USDZ`：Apple AR Quick Look。
- `OBJ`：传统交换格式，无动画。
- `STL`：3D 打印，仅几何体。
- `3MF`：3D，单色。



- `GLTF`：Web 查看器、WebGL 引擎（Three.js、Babylon.js）。
- `FBX`：Unreal、Unity、DCC 工具（Maya、Blender）。
- `USDZ`：Apple AR Quick Look、RealityKit。
- `OBJ`：传统交换格式，不支持动画。
- `STL` / `3MF`：3D 打印，仅几何体。

### quad

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

是否输出四边面网格（四边形多边形）而非三角面。若未设置 `face_limit`，默认面数为 10,000。启用 `quad` 会强制输出格式为 `FBX`。

### force_symmetry

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

强制对称。仅 quad 为 true 时有效。
### face_limit

- **Type:** integer
- **Required:** 可选

转换时的输出网格最大面数。不传时保持原模型面数。
### flatten_bottom

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

展平模型底部。
### flatten_bottom_threshold

- **Type:** float
- **Required:** 可选
- **Default:** `0.01`

展平深度阈值。
### texture_size

- **Type:** integer
- **Required:** 可选
- **Default:** `4096`

漫反射贴图尺寸（像素）。
### texture_format

- **Type:** string
- **Required:** 可选
- **Default:** `JPEG`

贴图图像格式。
- `JPEG`：默认，文件体积最小。
- `PNG`：无损，支持透明度。
- `WEBP`：现代 Web 格式。
- `BMP` / `DPX` / `HDR` / `OPEN_EXR` / `TARGA` / `TIFF`：专业用途。

### bake

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

将高级材质烘焙为基础贴图。
### pack_uv

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

将所有 UV 打包为统一布局。
### export_vertex_colors

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

包含顶点颜色。**仅对 `OBJ` 和 `GLTF` 有效。**
### pivot_to_center_bottom

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

将轴心点移至底部中心。
### scale_factor

- **Type:** float
- **Required:** 可选
- **Default:** `1`

导出模型的缩放系数。
### with_animation

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

包含骨骼和动画数据。
### animate_in_place

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

原地动画（无根骨位移）。
### part_names

- **Type:** string[]
- **Required:** 可选

要导出的部件名称，来自网格/分割数据。
### export_orientation

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

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

### fbx_preset

- **Type:** string
- **Required:** 可选
- **Default:** `blender`

FBX 兼容性预设。
- `blender`：针对 Blender 导入优化。
- `3dsmax`：针对 3ds Max 导入优化。
- `mixamo`：兼容 Mixamo 绑骨。


## Request Example

### 导出 FBX

```bash
curl --request POST \
  --url https://openapi.tripo3d.ai/v3/models/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "task_abc123",
  "format": "FBX",
  "texture_size": 2048,
  "texture_format": "PNG",
  "pivot_to_center_bottom": true,
  "fbx_preset": "blender"
}'
```

### 导出 GLTF

```bash
curl --request POST \
  --url https://openapi.tripo3d.ai/v3/models/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "task_abc123",
  "format": "GLTF",
  "texture_size": 4096,
  "bake": 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"
  }
}
```