模型格式转换

# 模型格式转换 **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" } } ```

{
  "input": "task_abc123",
  "format": "FBX",
  "texture_size": 2048,
  "texture_format": "PNG",
  "pivot_to_center_bottom": true,
  "fbx_preset": "blender"}

{
  "input": "task_abc123",
  "format": "GLTF",
  "texture_size": 4096,
  "bake": 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"}
}