# 智能 UV

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

**Endpoint:** `POST /mesh/uv`

为 3D 模型重新展 UV，并把原有贴图、骨骼与动画映射到新的 UV 布局上。除模型外，结果还会额外返回一张 UV 布局预览图。

## Request Parameters

### input

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

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

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



- 输入模型不得超过 **80,000 个等效三角面**（一个四边面按两个计）。 超出的模型在创建时不会被拒，但任务会失败并退还积分 —— 请先降低面数，例如使用重拓扑。

### model

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

智能 UV 模型版本。仅支持 `default`。
### bake

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

是否把原有贴图烘焙到新的 UV 布局上。设为 false 则跳过贴图烘焙，仅返回带 UV 的几何。
### export_orientation

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

导出模型朝向，可选 `+x`、`-x`、`+y`、`-y`。
### compress

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

压缩类型。
- `geometry`：meshopt 压缩，减小文件体积。



- 以下参数仅在 `model ≥ v3.0-20250812` 时有效：`texture_quality`、`geometry_quality`、`auto_size`、`quad`、`smart_low_poly`、`generate_parts`、`compress`。


## Request Example

### task_id 引用

```bash
curl --request POST \
  --url https://openapi.tripo3d.ai/v3/mesh/uv \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "task_abc123"
}'
```

### file_token，不烘焙贴图

```bash
curl --request POST \
  --url https://openapi.tripo3d.ai/v3/mesh/uv \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "file_<your-upload-token>",
  "model": "default",
  "bake": false
}'
```


## Response Example

### 创建任务

```json
{
  "code": 0,
  "data": {
    "task_id": "task_abc123"
  }
}
```

### 任务结果

```json
{
  "code": 0,
  "data": {
    "task_id": "task_abc123",
    "type": "mesh_uv",
    "status": "success",
    "progress": 100,
    "output": {
      "model_url": "https://cdn.tripo3d.ai/output/model.glb",
      "uv_render_url": "https://cdn.tripo3d.ai/output/uv_render.webp"
    },
    "credits_consumed": 20.00,
    "created_at": "2026-09-20T12:00:00Z",
    "completed_at": "2026-09-20T12:01:30Z"
  }
}
```