# 贴图
**Base URL:** `https://openapi.tripo3d.ai/v3`
**Endpoint:** `POST /models/texture`
为现有模型重新生成贴图。
## 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](http://localhost:4173/docs/files)上传 3D 模型文件，然后传入返回的 token。
示例： `file_abc123`
- URL：可公开访问的 3D 模型文件直链。
示例： `https://example.com/model.glb`
- 支持格式：`GLB`、`GLTF`、`FBX`、`OBJ`、`STL`
- 最大文件大小：**150 MB**
### model
- **Type:** string
- **Required:** 可选
- **Default:** `v3.0-20250812`
贴图模型版本。请根据源 3D 模型的生成版本选择：
- `v3.0-20250812`：默认。推荐用于 `v3.0-20250812` 或 `v3.1-20260211` 生成的模型。
- `v2.5-20250123`：推荐用于 `v2.5-20250123` 生成的模型。
### texture_prompt
- **Type:** object
- **Required:** 可选
贴图引导输入。如果模型是通过 Tripo 生成的则可选。**`text` / `image` / `images` 三者互斥，只能选其一（`style_image` 可与 `text` 搭配）。**
- text：描述期望贴图风格的文本提示词。
示例： `{"text": "磨损的皮革带划痕"}`
- style_image：风格参考图片，仅可与 `text` 模式搭配使用。 接受 `file_token` 或 `url`。建议分辨率：至少 256×256 px。
示例： `{"text": "赛博朋克风格", "style_image": {"url": "https://..."}}`
- image：单张参考图片用于贴图生成。接受 file_token 或 URL。
- images：恰好 4 张参考图片，顺序为 [正面, 左侧, 背面, 右侧]，用于多角度贴图引导。
- 若基于已有 TaskID 发起贴图任务，**强烈建议**在本次请求中重新传入参考图。
- `text`、`image` 和 `images` 三者互斥，只能选其一。
- 可选的 `style_image` 可与 `text` 搭配使用，用于影响艺术风格。
### pbr
- **Type:** boolean
- **Required:** 可选
- **Default:** `true`
启用 PBR 材质生成。
### texture_seed
- **Type:** integer
- **Required:** 可选
贴图生成的随机种子。使用相同种子将生成相同的贴图。若未设置，每次会使用随机种子。如需获取相同几何体但不同贴图的模型，请保持 model_seed 不变并更改 texture_seed。
### texture_alignment
- **Type:** string
- **Required:** 可选
- **Default:** `original_image`
贴图对齐优先级。
- `original_image`：优先匹配输入图像的颜色。
- `geometry`：优先匹配生成的几何体。
### texture_quality
- **Type:** string
- **Required:** 可选
- **Default:** `standard`
贴图质量等级。
- `standard`：质量与速度的平衡。
- `detailed`：更高保真度，生成速度较慢。
- `extreme`：8K 贴图，最高保真度。相比 detailed 额外消耗积分。
### part_names
- **Type:** string[]
- **Required:** 可选
来自之前网格分割任务的部件名称列表。如不填写，则对所有部件进行贴图。
### compress
- **Type:** string
- **Required:** 可选
压缩类型。
- `geometry`：meshopt 压缩，减小文件体积。
- 以下参数仅在 `model ≥ v3.0-20250812` 时有效：`texture_quality`、`geometry_quality`、`auto_size`、`quad`、`smart_low_poly`、`generate_parts`、`compress`。
### bake
- **Type:** boolean
- **Required:** 可选
- **Default:** `true`
将高级材质效果烘焙到基础贴图中，以提高兼容性。
## Request Example
### 基础示例（v2.5 模型）
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/models/texture \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "task_abc123",
"model": "v2.5-20250123",
"texture_quality": "detailed",
"pbr": true
}'
```
### v3.x 模型贴图
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/models/texture \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "task_abc123",
"model": "v3.0-20250812",
"texture_quality": "detailed",
"pbr": true
}'
```
### 带提示词示例
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/models/texture \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "task_abc123",
"model": "v3.0-20250812",
"texture_prompt": {
"text": "worn leather with scratches"
},
"texture_quality": "detailed"
}'
```
## 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"
}
}
```
Base URL: https://openapi.tripo3d.ai/v3
Endpoint: POST /models/texture
为现有模型重新生成贴图。
- 此接口需要 API Key 认证。请在 Authorization 请求头中传入 Bearer {api_key}。
- 此接口为异步 API。提交请求后，请使用 任务查询接口 轮询获取结果，或配置 Webhook 接收任务完成时的自动通知。
请求参数
请求体
inputstring必选
模型来源。接受 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
- 支持格式：
GLB、GLTF、FBX、OBJ、STL - 最大文件大小：150 MB
modelstring默认值: v3.0-20250812
贴图模型版本。请根据源 3D 模型的生成版本选择：
v3.0-20250812：默认。推荐用于 v3.0-20250812 或 v3.1-20260211 生成的模型。v2.5-20250123：推荐用于 v2.5-20250123 生成的模型。
texture_promptobject
贴图引导输入。如果模型是通过 Tripo 生成的则可选。
text / image / images 三者互斥，只能选其一（style_image 可与 text 搭配）。
- text：描述期望贴图风格的文本提示词。
示例： {"text": "磨损的皮革带划痕"} - style_image：风格参考图片，仅可与
text 模式搭配使用。 接受 file_token 或 url。建议分辨率：至少 256×256 px。
示例： {"text": "赛博朋克风格", "style_image": {"url": "https://..."}} - image：单张参考图片用于贴图生成。接受 file_token 或 URL。
- images：恰好 4 张参考图片，顺序为 [正面, 左侧, 背面, 右侧]，用于多角度贴图引导。
- 若基于已有 TaskID 发起贴图任务，强烈建议在本次请求中重新传入参考图。
text、image 和 images 三者互斥，只能选其一。- 可选的
style_image 可与 text 搭配使用，用于影响艺术风格。
pbrboolean默认值: true
启用 PBR 材质生成。
texture_seedinteger
贴图生成的随机种子。使用相同种子将生成相同的贴图。若未设置，每次会使用随机种子。如需获取相同几何体但不同贴图的模型，请保持 model_seed 不变并更改 texture_seed。
texture_alignmentstring默认值: original_image
贴图对齐优先级。
original_image：优先匹配输入图像的颜色。geometry：优先匹配生成的几何体。
texture_qualitystring默认值: standard
贴图质量等级。
standard：质量与速度的平衡。detailed：更高保真度，生成速度较慢。extreme：8K 贴图，最高保真度。相比 detailed 额外消耗积分。
part_namesstring[]
来自之前网格分割任务的部件名称列表。如不填写，则对所有部件进行贴图。
compressstring
压缩类型。
geometry：meshopt 压缩，减小文件体积。
- 以下参数仅在
model ≥ v3.0-20250812 时有效：texture_quality、geometry_quality、auto_size、quad、smart_low_poly、generate_parts、compress。
bakeboolean默认值: true
将高级材质效果烘焙到基础贴图中，以提高兼容性。
示例
{
"input": "task_abc123",
"model": "v2.5-20250123",
"texture_quality": "detailed",
"pbr": true
}
{
"input": "task_abc123",
"model": "v3.0-20250812",
"texture_quality": "detailed",
"pbr": true
}
{
"input": "task_abc123",
"model": "v3.0-20250812",
"texture_prompt": {
"text": "worn leather with scratches"},
"texture_quality": "detailed"}
{
"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"}
}
