Skip to Content
3D 模型生成

3D 模型生成

tripo-v3.1tripo-v3.0tripo-v2.5tripo-p1tripo-p2tripo-splat

3D 生成以异步任务运行。创建成功后保存 data.task_id,并使用查询接口获取进度和结果。

图片输入应使用可公开访问的 HTTP(S) 图片 URL。任务成功后及时保存 data.output.model_url。

创建文本生成 3D 任务

POST /v3/generation/text-to-model

请求参数

参数类型必填说明
modelstring是使用 tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1 或 tripo-p2。
promptstring是生成描述,1 至 1024 个字符。
negative_promptstring否需要避免的内容,最多 255 个字符。
image_seedinteger否文本生成使用的图片种子。
model_seedinteger否模型生成种子。
其他网格参数-否可传入网格生成参数中的选项。
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

请求参数

参数类型必填说明
modelstring是使用 tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1 或 tripo-p2。
inputstring是单张图片的公网 HTTP(S) URL。
model_seedinteger否模型生成种子。
其他网格参数-否可传入网格生成参数中的选项。
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

请求参数

参数类型必填说明
modelstring是使用 tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1 或 tripo-p2。
inputsarray是2 至 4 个视角,必须包含 front 和至少一个其他视角。视角键支持 front、left、back、right。
model_seedinteger否模型生成种子。
其他网格参数-否可传入网格生成参数中的选项。

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

请求参数

参数类型必填说明
modelstring是固定为 tripo-splat。
inputstring是单张图片的公网 HTTP(S) URL。
model_seedinteger否模型生成种子。
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。

参数类型必填说明
textureboolean否是否生成纹理。
pbrboolean否是否生成 PBR 材质。
texture_qualitystring否fast、standard、detailed 或 extreme。fast 需同时设置 texture_version 为 v3.5-20260815。
texture_versionstring否v3.5-20260815、v3.0-20250812 或 v2.5-20250123。
geometry_qualitystring否standard 或 detailed。
texture_seedinteger否纹理生成种子。
face_limitinteger否面数上限,必须为正整数;可用范围与模型及其他几何参数有关。
texture_alignmentstring否original_image 或 geometry。
orientationstring否default 或 align_image。
auto_sizeboolean否是否自动调整模型尺寸。
delightboolean否是否对纹理执行光照优化。
quadboolean否是否生成四边面网格。
smart_low_polyboolean否是否启用智能低模。
generate_partsboolean否是否按部件生成。启用时 texture 和 pbr 均须为 false。
compressstring否geometry,压缩几何数据。
export_uvboolean否是否导出 UV 信息。
export_orientationstring否+x、-x、-y 或 +y。
enable_image_autofixboolean否是否启用输入图片自动修复。

查询 3D 生成任务

GET /v3/tasks/{task_id}

调用示例

curl "https://api.example.com/v3/tasks/task_01JEXAMPLE3D" \ -H "Authorization: Bearer <YOUR_API_KEY>"

响应参数

字段类型说明
codeinteger请求结果码,成功时为 0。
data.task_idstring公开任务 ID。
data.typestringtext_to_model、image_to_model、multiview_to_model 或 image_to_splat。
data.statusstringqueued、running、success、failed、banned、expired 或 cancelled。
data.progressinteger任务进度,范围为 0 至 100。
data.created_atstring创建时间,RFC 3339 格式。
data.completed_atstring完成时间,RFC 3339 格式;任务完成后返回。
data.output.model_urlstring成功时生成的 3D 模型地址。
data.output.rendered_image_urlstring可用时返回的渲染预览图片地址。
data.output.generated_image_urlstring可用时返回的生成图片地址。
data.error_codeinteger失败时的错误码,可能不返回。
data.error_messagestring失败原因。
{ "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。

Last updated on