# 图像生成 3D 模型 — H 系列
**Base URL:** `https://openapi.tripo3d.ai/v3`
**Endpoint:** `POST /generation/image-to-model`
根据图像生成 3D 模型。系统从输入中推断几何体和贴图。
## Request Parameters
### input
- **Type:** string
- **Required:** 必选
图像来源。主体应清晰可见，遮挡最少。 接受以下输入类型：**以下三种方式任选其一**，不可同时传入多种类型。
- file_token：先通过[文件上传 API](http://localhost:4173/docs/files)上传图像，然后传入返回的 token。
示例： `file_abc123`
- URL：可公开访问的图像直链。
示例： `https://example.com/photo.png`
- task_id：此前图像生成任务（`text_to_image` 或 `image_to_image`）返回的任务 ID。系统会自动提取输出图像。
示例： `task_abc123`
- 支持格式：`PNG`、`JPEG`、`WebP`
- 最大文件大小：**20 MB**
- 推荐分辨率：至少 **256 × 256 px**。主体应清晰可见，背景干净，遮挡尽量少。
### model
- **Type:** string
- **Required:** 必选
AI 模型版本。
- `v3.1-20260211`：最新版，最佳质量。
- `v3.0-20250812`：稳定版，高级功能。
- `v2.5-20250123`：均衡版。
### enable_image_autofix
- **Type:** boolean
- **Required:** 可选
- **Default:** `false`
是否在生成前自动优化输入图像。启用后，系统将增强低分辨率或低质量图像以改善 3D 生成效果。默认为 false。
### texture_alignment
- **Type:** string
- **Required:** 可选
- **Default:** `original_image`
贴图对齐优先级。
- `original_image`：优先匹配输入图像的颜色。
- `geometry`：优先匹配生成的几何体。
### orientation
- **Type:** string
- **Required:** 可选
- **Default:** `default`
模型朝向。
- `default`：自动朝向。
- `align_image`：将模型对齐至输入图像的视角。
仅当 `texture` 为 `true` 时生效。未开启贴图时此参数无效。
### face_limit
- **Type:** integer
- **Required:** 可选
输出网格的最大面数。
- 省略时模型使用自适应拓扑。
各模式面数上限
| 模式 | 标准 | 超清 |
| 纯三角面 — v3.1 | **1,500,000** | **2,000,000** |
| 纯三角面 — v3.0 | **1,000,000** | **2,000,000** |
| 纯三角面 — v2.5 | **500,000** | / |
| 四边面（`quad: true`） | **150,000** |
- 游戏资产推荐：**50,000 – 100,000**。Web/移动端：**10,000 – 50,000**。
- 开启 `smart_low_poly: true` 时，面数限制与模型版本无关，统一为： 三角面 **500 – 20,000**，四边面 **500 – 10,000**。
### 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 额外消耗积分。
### geometry_quality
- **Type:** string
- **Required:** 可选
- **Default:** `standard`
几何体质量等级。
- `standard`：质量与速度的平衡。
- `detailed`：Ultra 模式，更精细的几何细节。
该参数只对 v3.0 以上模型版本生效，v2.5 切勿使用该参数。
### auto_size
- **Type:** boolean
- **Required:** 可选
- **Default:** `false`
是否自动将生成的模型缩放至真实世界尺寸。启用后，模型尺寸将以米为单位，适用于 AR/VR 或游戏引擎场景。默认为 false。
### quad
- **Type:** boolean
- **Required:** 可选
- **Default:** `false`
是否输出四边面网格（四边形多边形）而非三角面。若未设置 `face_limit`，默认面数为 10,000。启用 `quad` 会强制输出格式为 `FBX`。
### smart_low_poly
- **Type:** boolean
- **Required:** 可选
- **Default:** `false`
是否生成具有手工风格、干净拓扑的低面数模型。最适合简单、非复杂的输入。复杂模型可能偶尔失败。默认为 false。
### generate_parts
- **Type:** boolean
- **Required:** 可选
- **Default:** `false`
生成可编辑的分割部件。与 `texture=true`、`pbr=true` 或 `quad=true` 不兼容。要使用此功能，需将这三者均设为 `false`。
### compress
- **Type:** string
- **Required:** 可选
压缩类型。
- `geometry`：meshopt 压缩，减小文件体积。
- 以下参数仅在 `model ≥ v3.0-20250812` 时有效：`texture_quality`、`geometry_quality`、`auto_size`、`quad`、`smart_low_poly`、`generate_parts`、`compress`。
### model_seed
- **Type:** integer
- **Required:** 可选
几何体生成的随机种子。使用相同种子和相同输入将生成相同的 3D 网格。若未设置，每次会使用随机种子。
### export_uv
- **Type:** boolean
- **Required:** 可选
- **Default:** `true`
控制生成过程中的 UV 展开。设为 `false` 可加快生成速度并减小文件体积。UV 展开将在贴图阶段处理。
## Request Example
### URL 示例
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/generation/image-to-model \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "https://example.com/image.png",
"model": "v3.1-20260211",
"texture": true,
"pbr": true,
"texture_quality": "detailed"
}'
```
### Autofix 示例
```bash
curl --request POST \
--url https://openapi.tripo3d.ai/v3/generation/image-to-model \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"input": "file_abc123",
"model": "v3.1-20260211",
"enable_image_autofix": true,
"orientation": "align_image"
}'
```
## 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"
}
}
```
请求参数
请求体
inputstring必选
图像来源。主体应清晰可见，遮挡最少。 接受以下输入类型：
以下三种方式任选其一，不可同时传入多种类型。
- file_token：先通过文件上传 API上传图像，然后传入返回的 token。
示例： file_abc123 - URL：可公开访问的图像直链。
示例： https://example.com/photo.png - task_id：此前图像生成任务（
text_to_image 或 image_to_image）返回的任务 ID。系统会自动提取输出图像。
示例： task_abc123
- 支持格式：
PNG、JPEG、WebP - 最大文件大小：20 MB
- 推荐分辨率：至少 256 × 256 px。主体应清晰可见，背景干净，遮挡尽量少。
modelstring必选
AI 模型版本。
v3.1-20260211：最新版，最佳质量。v3.0-20250812：稳定版，高级功能。v2.5-20250123：均衡版。
enable_image_autofixboolean默认值: false
是否在生成前自动优化输入图像。启用后，系统将增强低分辨率或低质量图像以改善 3D 生成效果。默认为 false。
texture_alignmentstring默认值: original_image
贴图对齐优先级。
original_image：优先匹配输入图像的颜色。geometry：优先匹配生成的几何体。
orientationstring默认值: default
模型朝向。
default：自动朝向。align_image：将模型对齐至输入图像的视角。
仅当 texture 为 true 时生效。未开启贴图时此参数无效。
face_limitinteger
输出网格的最大面数。
各模式面数上限
| 模式 | 标准 | 超清 |
|---|
| 纯三角面 — v3.1 | 1,500,000 | 2,000,000 |
| 纯三角面 — v3.0 | 1,000,000 | 2,000,000 |
| 纯三角面 — v2.5 | 500,000 | / |
四边面（quad: true） | 150,000 |
- 游戏资产推荐：50,000 – 100,000。Web/移动端：10,000 – 50,000。
- 开启
smart_low_poly: true 时，面数限制与模型版本无关，统一为： 三角面 500 – 20,000，四边面 500 – 10,000。
textureboolean默认值: true
是否为模型生成贴图。设为 false 可获取无贴图的纯几何体。默认为 true。
pbrboolean默认值: true
启用 PBR 材质贴图（
base_color、
metallic、
roughness、
normal）。
当 pbr 设为 true 时，texture 会自动强制设为 true。
texture_seedinteger
贴图生成的随机种子。使用相同种子将生成相同的贴图。若未设置，每次会使用随机种子。如需获取相同几何体但不同贴图的模型，请保持 model_seed 不变并更改 texture_seed。
texture_qualitystring默认值: standard
贴图质量等级。
standard：质量与速度的平衡。detailed：更高保真度，生成速度较慢。extreme：8K 贴图，最高保真度。相比 detailed 额外消耗积分。
geometry_qualitystring默认值: standard
几何体质量等级。
standard：质量与速度的平衡。detailed：Ultra 模式，更精细的几何细节。
该参数只对 v3.0 以上模型版本生效，v2.5 切勿使用该参数。
auto_sizeboolean默认值: false
是否自动将生成的模型缩放至真实世界尺寸。启用后，模型尺寸将以米为单位，适用于 AR/VR 或游戏引擎场景。默认为 false。
quadboolean默认值: false
是否输出四边面网格（四边形多边形）而非三角面。若未设置
face_limit，默认面数为 10,000。
启用 quad 会强制输出格式为 FBX。
smart_low_polyboolean默认值: false
是否生成具有手工风格、干净拓扑的低面数模型。最适合简单、非复杂的输入。复杂模型可能偶尔失败。默认为 false。
generate_partsboolean默认值: false
生成可编辑的分割部件。
与 texture=true、pbr=true 或 quad=true 不兼容。要使用此功能，需将这三者均设为 false。
compressstring
压缩类型。
geometry：meshopt 压缩，减小文件体积。
- 以下参数仅在
model ≥ v3.0-20250812 时有效：texture_quality、geometry_quality、auto_size、quad、smart_low_poly、generate_parts、compress。
model_seedinteger
几何体生成的随机种子。使用相同种子和相同输入将生成相同的 3D 网格。若未设置，每次会使用随机种子。
export_uvboolean默认值: true
控制生成过程中的 UV 展开。设为 false 可加快生成速度并减小文件体积。UV 展开将在贴图阶段处理。
示例
{
"input": "https://example.com/image.png",
"model": "v3.1-20260211",
"texture": true,
"pbr": true,
"texture_quality": "detailed"}
{
"input": "file_abc123",
"model": "v3.1-20260211",
"enable_image_autofix": true,
"orientation": "align_image"}
{
"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"}
}
