3D 模型生成
3D 生成以异步任务运行。创建成功后保存 data.task_id,并使用查询接口获取进度和结果。
图片输入应使用可公开访问的 HTTP(S) 图片 URL。任务成功后及时保存 data.output.model_url。
创建文本生成 3D 任务
POST /v3/generation/text-to-model
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 使用 tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1 或 tripo-p2。 |
prompt | string | 是 | 生成描述,1 至 1024 个字符。 |
negative_prompt | string | 否 | 需要避免的内容,最多 255 个字符。 |
image_seed | integer | 否 | 文本生成使用的图片种子。 |
model_seed | integer | 否 | 模型生成种子。 |
| 其他网格参数 | - | 否 | 可传入网格生成参数中的选项。 |
curl -X POST "https://api.example.com/v3/generation/text-to-model" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-v3.1",
"prompt": "一把带有雕刻细节的中世纪木椅,正面视角",
"negative_prompt": "模糊,破损",
"model_seed": 42,
"texture_quality": "standard",
"geometry_quality": "standard"
}'创建成功时返回公开任务 ID:
{
"code": 0,
"data": {
"task_id": "task_01JEXAMPLE3D"
}
}创建图片生成 3D 任务
POST /v3/generation/image-to-model
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 使用 tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1 或 tripo-p2。 |
input | string | 是 | 单张图片的公网 HTTP(S) URL。 |
model_seed | integer | 否 | 模型生成种子。 |
| 其他网格参数 | - | 否 | 可传入网格生成参数中的选项。 |
curl -X POST "https://api.example.com/v3/generation/image-to-model" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-v3.1",
"input": "https://example.com/images/chair-front.jpg",
"model_seed": 42,
"texture": true,
"pbr": true,
"face_limit": 10000
}'创建多视图 3D 任务
POST /v3/generation/multiview-to-model
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 使用 tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1 或 tripo-p2。 |
inputs | array | 是 | 2 至 4 个视角,必须包含 front 和至少一个其他视角。视角键支持 front、left、back、right。 |
model_seed | integer | 否 | 模型生成种子。 |
| 其他网格参数 | - | 否 | 可传入网格生成参数中的选项。 |
inputs 支持视角对象或四个位置的 URL 数组。视角对象的值可以是 URL 字符串,也可以是包含 url 的对象:
{
"model": "tripo-v3.1",
"inputs": [
{"front": "https://example.com/images/object-front.jpg"},
{"left": {"url": "https://example.com/images/object-left.jpg"}}
],
"model_seed": 42
}使用位置数组时必须提供四个槽位;没有图片的视角使用空字符串,正面图片放在第一项:
{
"model": "tripo-v3.1",
"inputs": [
"https://example.com/images/object-front.jpg",
"https://example.com/images/object-left.jpg",
"",
"https://example.com/images/object-right.jpg"
]
}调用示例
curl -X POST "https://api.example.com/v3/generation/multiview-to-model" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-v3.1",
"inputs": [
{"front": "https://example.com/images/object-front.jpg"},
{"back": "https://example.com/images/object-back.jpg"}
],
"texture_quality": "standard"
}'创建 Gaussian Splat 任务
POST /v3/generation/image-to-splat
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 固定为 tripo-splat。 |
input | string | 是 | 单张图片的公网 HTTP(S) URL。 |
model_seed | integer | 否 | 模型生成种子。 |
curl -X POST "https://api.example.com/v3/generation/image-to-splat" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-splat",
"input": "https://example.com/images/garden.jpg",
"model_seed": 42
}'网格生成参数
以下可选参数用于文本、图片和多视图生成任务。参数组合应符合所选模型的能力;例如,generate_parts 需要同时将 texture 和 pbr 设为 false。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
texture | boolean | 否 | 是否生成纹理。 |
pbr | boolean | 否 | 是否生成 PBR 材质。 |
texture_quality | string | 否 | fast、standard、detailed 或 extreme。fast 需同时设置 texture_version 为 v3.5-20260815。 |
texture_version | string | 否 | v3.5-20260815、v3.0-20250812 或 v2.5-20250123。 |
geometry_quality | string | 否 | standard 或 detailed。 |
texture_seed | integer | 否 | 纹理生成种子。 |
face_limit | integer | 否 | 面数上限,必须为正整数;可用范围与模型及其他几何参数有关。 |
texture_alignment | string | 否 | original_image 或 geometry。 |
orientation | string | 否 | default 或 align_image。 |
auto_size | boolean | 否 | 是否自动调整模型尺寸。 |
delight | boolean | 否 | 是否对纹理执行光照优化。 |
quad | boolean | 否 | 是否生成四边面网格。 |
smart_low_poly | boolean | 否 | 是否启用智能低模。 |
generate_parts | boolean | 否 | 是否按部件生成。启用时 texture 和 pbr 均须为 false。 |
compress | string | 否 | geometry,压缩几何数据。 |
export_uv | boolean | 否 | 是否导出 UV 信息。 |
export_orientation | string | 否 | +x、-x、-y 或 +y。 |
enable_image_autofix | boolean | 否 | 是否启用输入图片自动修复。 |
查询 3D 生成任务
GET /v3/tasks/{task_id}
调用示例
curl "https://api.example.com/v3/tasks/task_01JEXAMPLE3D" \
-H "Authorization: Bearer <YOUR_API_KEY>"响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 请求结果码,成功时为 0。 |
data.task_id | string | 公开任务 ID。 |
data.type | string | text_to_model、image_to_model、multiview_to_model 或 image_to_splat。 |
data.status | string | queued、running、success、failed、banned、expired 或 cancelled。 |
data.progress | integer | 任务进度,范围为 0 至 100。 |
data.created_at | string | 创建时间,RFC 3339 格式。 |
data.completed_at | string | 完成时间,RFC 3339 格式;任务完成后返回。 |
data.output.model_url | string | 成功时生成的 3D 模型地址。 |
data.output.rendered_image_url | string | 可用时返回的渲染预览图片地址。 |
data.output.generated_image_url | string | 可用时返回的生成图片地址。 |
data.error_code | integer | 失败时的错误码,可能不返回。 |
data.error_message | string | 失败原因。 |
{
"code": 0,
"data": {
"task_id": "task_01JEXAMPLE3D",
"type": "text_to_model",
"status": "success",
"progress": 100,
"created_at": "2026-10-21T08:30:00Z",
"completed_at": "2026-10-21T08:31:12Z",
"output": {
"model_url": "https://models.example.com/generated/chair.glb",
"rendered_image_url": "https://models.example.com/generated/chair-preview.png"
}
}
}创建任务后保存 data.task_id,以数秒间隔查询状态。任务为 queued 或 running 时继续等待;任务为 success 时读取 data.output.model_url;任务进入 failed、banned、expired 或 cancelled 时查看 data.error_message 并停止轮询。对 HTTP 429 和临时 5xx 响应采用带抖动的指数退避。
创建请求可选传入 Idempotency-Key 请求头,长度最多 128 个字符。同一 API Key 使用相同键和相同请求重试时会返回同一任务;相同键用于不同请求时返回 HTTP 409。