大模型服务平台 TokenHub Tripo 调用指南

一、简介

Tripo 生3d 接口，根据输入的文本描述/图片智能生成3d。

二、1. 获取 API Key

1. 进入 API Key 管理页面，单击创建 API Key。操作详情请参见创建 API Key。

2. 创建完成后，请你务必复制并妥善保管 API Key，在后续配置到工具的流程中将会使用该信息。

注意：说明：

注意：每个账户的密钥都只能当前账户查询，主账户的密钥信息子账户是看不到，子账户如果需要调用接口，需要使用账户自行创建密钥信息。

注意：如果子账户没有办法创建，可能是没有权限创建密钥，需要主账户授权，主账户登录之后点击用户列表，在对应的子账户后面选择授权，会弹出关联策略的弹窗，输入授权策略名称之后搜索，选择对应的策略点击确认。

注意：授权策略：QcloudTokenhubFullAccess

三、2. 并发额度

默认提供1个并发，代表最多能同时处理1个已提交的任务，上一个任务处理完毕后，才能开始处理下一个任务。

并发任务数：表示在调用对应服务的时段内最大可运行的任务数，该任务未完成时，无法提交下一个任务，该任务完成后，可提交下一个任务。

四、提交 Tripo 生3d 任务

输入参数

参数名称	必选	类型	参数描述
model	是	string	tripo 生3d 模型名称。可选项：tripo-3d-3.1、tripo-3d-p1、tripo-3d-p2。默认为 tripo-3d-3.1。示例值：tripo-3d-3.1
prompt	否	string	文本提示词，最多 1024 个字符。仅使用文生3D 功能时生效。描述形状、材质、风格和尺寸。
input	否	string	图片生成图像来源。仅使用图生3D 功能时生效。支持 PNG、JPEG、WebP，最大 20 MB，建议分辨率不低于 256 × 256 px。主体应清晰可见，背景干净，遮挡尽量少。示例值：https://cos.ap-guangzhou.myqcloud.com/image.jpg
inputs	否	array of object	多视图生成图像来源。仅使用多图生3D 功能时生效。主体应清晰可见，遮挡最少。正面视图不可省略。其他视图可省略，但至少需要 2 张图像。所有图像应在一致光照下拍摄同一物体。支持格式：PNG、JPEG、WebP推荐分辨率：至少 256 × 256 px。详情请参见 inputs 数据结构。
negative_prompt	否	string	反向提示词，最多 255 个字符。描述不希望在生成模型中出现的内容。示例值："blurry, low quality, broken mesh"。
image_seed	否	integer	内部文本转图像阶段的随机种子。控制从文本提示词生成的参考图像，然后再进行 3d 转换。若未设置，每次会使用随机种子。注意：建议谨慎使用该参数。由于不同 seed 可能产生不同质量的结果，固定 seed 可能会限制探索更优生成结果的机会。seed 取值范围：-2147483648 ~ 2147483647。
model_seed	否	integer	几何体生成的随机种子。使用相同种子和相同输入将生成相同的 3d 网格。若未设置，每次会使用随机种子。注意：建议谨慎使用该参数。由于不同 seed 可能产生不同质量的结果，固定 seed 可能会限制探索更优生成结果的机会。seed 取值范围：-2147483648 ~ 2147483647。
enable_image_autofix	否	boolean	是否在生成前自动优化输入图像。启用后，系统将增强低分辨率或低质量图像以改善 3d 生成效果。默认为 false。
face_limit	否	integer	输出网格的最大面数。省略时模型使用自适应拓扑。model 为 tripo-3d-3.1时：纯三角面标准模式面数上限 1,500,000，超清模式上限 2,000,000。四边面（quad: true）标准模式面数上限 150,000。游戏资产推荐：50,000 – 100,000。web/移动端：10,000 – 50,000。开启 smart_low_poly: true 时，面数限制与模型版本无关，统一为：三角面 500 – 20,000，四边面 500 – 10,000。model 为 tripo-3d-p1时：输出网格的最大面数。支持范围：50 – 20,000。省略时自适应确定面数。最佳质量建议：简单模型从 150 面起步，复杂模型从 250 面起步。面数过低可能导致生成质量下降。model 为 tripo-3d-p2时：输出网格最大面数。三角面范围为 48–50,000；quad=true 时范围为 48–25,000；省略时自动确定。最佳质量建议：简单模型从 150 面起步，复杂模型从 250 面起步。面数过低可能导致生成质量下降。
texture	否	boolean	是否为模型生成贴图。设为 false 可获取无贴图的纯几何体。默认为 true。
pbr	否	boolean	启用 pbr 材质贴图（base_color、metallic、roughness、normal）。当 pbr 设为 true 时，texture 会自动强制设为 true。默认为 true。
texture_seed	否	integer	贴图生成的随机种子。使用相同种子将生成相同的贴图。若未设置，每次会使用随机种子。如需获取相同几何体但不同贴图的模型，请保持 model_seed 不变并更改 texture_seed。注意：建议谨慎使用该参数。由于不同 seed 可能产生不同质量的结果，固定 seed 可能会限制探索更优生成结果的机会。seed 取值范围：-2147483648 ~ 2147483647。
texture_alignment	否	string	确定 3d 模型中纹理对齐的优先级。仅单图和多图输入时生效。可选值包括：original_image、geometry。original_image：优先保证与源图像的视觉保真度，生成纹理与原图更相似，但可能导致轻微 3d 不一致。geometry：优先保证三维结构精度，使纹理更好地贴合模型几何形状，但可能与原图外观略有偏差。默认值为 original_image。
texture_quality	否	string	贴图质量等级。可选值包括：fast，standard，detailed，extreme。fast：生成最快，以细节换速度；输出贴图尺寸与 standard 相同。需要贴图版本 v3.5-20260815；积分与 standard 相同。standard：质量与速度的平衡。detailed：更高保真度，生成速度较慢。extreme：8k 贴图，最高保真度。相比 detailed 额外消耗积分。默认为 standard。fast 仅在贴图版本 v3.5-20260815 下可用。生成接口需将 texture_version 设为该版本。
texture_version	否	string	独立指定贴图模型，与几何体 model 解耦。v3.5-20260815：最新贴图模型。使用 texture_quality=fast 与 delight 时必填。v3.0-20250812：v3.x 与 P 系列几何体的默认值。v2.5-20250123：v2.5-20250123 几何体的默认值。省略时按上表根据几何体 model 自动推导。
delight	否	boolean	贴图前去除参考图中的光照信息。设为 false 可保留原有明暗。仅 v3.5-20260815 贴图模型支持，更早的贴图版本会忽略该参数。默认为 true。
auto_size	否	boolean	是否自动将生成的模型缩放至真实世界尺寸。启用后，模型尺寸将以米为单位，适用于 ar/vr 或游戏引擎场景。默认为 false。
orientation	否	string	设置模型方向。仅单图和多图输入时生效；default：自动朝向。align_image：将模型对齐至输入图像的视角。仅当 texture 为 true 时生效，未开启贴图时此参数无效。默认值为 default。
quad	否	boolean	model 为 tripo-3d-p2时有效。是否输出四边面网格，默认 false；开启后 face_limit 上限为25000。
compress	否	string	model 为 tripo-3d-3.1时有效。压缩类型。geometry：meshopt 压缩，减小文件体积。
smart_low_poly	否	boolean	model 为 tripo-3d-3.1时有效。是否生成具有手工风格、干净拓扑的低面数模型。最适合简单、非复杂的输入。复杂模型可能偶尔失败。默认为 false。
generate_parts	否	boolean	model 为 tripo-3d-3.1时有效。生成可编辑的分割部件。与 texture=true、pbr=true 或 quad=true 不兼容。要使用此功能，需将这三者均设为 false。默认为 false。
export_uv	否	boolean	控制生成过程中的 uv 展开。设为 false 可加快生成速度并减小文件体积。uv 展开将在贴图阶段处理。默认为 true。
geometry_quality	否	string	model 为 tripo-3d-3.1时有效。几何体质量等级。standard：质量与速度的平衡。detailed：ultra 模式，更精细的几何细节。默认为 standard。

输出参数

参数名称	类型	描述
id	string	任务 id（有效期24小时）。示例值：1315932989749215232
request_id	string	唯一请求 id，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 request_id）。定位问题时需要提供该次请求的 request_id。
object	string	返回对象类型。3d 任务固定返回 3d_job。
created_at	integer	任务创建时间。
status	string	completed：任务成功，failed：任务失败，in_progress：执行中，queued：等待中。示例值：completed

五、查询 Tripo 生3d 任务

输入参数

参数名称	必选	类型	描述
model	是	string	tripo 生3d 模型名称。可选项：tripo-3d-3.1、tripo-3d-p1、tripo-3d-p2。默认为 tripo-3d-3.1。示例值：tripo-3d-3.1
id	是	string	任务 id。示例值：1357237233311637504

输出参数

参数名称	类型	描述
status	string	completed：任务成功，failed：任务失败，in_progress：执行中，queued：等待中。示例值：completed
request_id	string	唯一请求 id，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 request_id）。定位问题时需要提供该次请求的 request_id。
input	object	本次任务实际使用的输入信息。详情请参见 input 数据结构。
output	object	任务生成结果。详情请参见 output 数据结构。
object	string	返回对象类型。3d 任务固定返回 3d_job。
created_at	integer	任务创建时间。
completed_at	integer	任务完成时间。
credits_consumed	number	当前任务实际消耗的积分数。

六、提交 Tripo 生3d 任务

输入示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/api/3d/submit' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "tripo-3d-3.1", "prompt": "一只可爱的小猫" }'

输出示例

{ "id": "14721*****320", "request_id": "11f64379-bb0b-46b2-b89f-17d75fc12365", "object": "3d_job", "created_at": 1784885898, "status": "queued"}

七、查询 Tripo 生3d 任务

输入示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/api/3d/query' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "tripo-3d-3.1", "id": "14721*****320" }'

输出示例

{ "status": "completed", "input": { "prompt": "一只可爱的小猫", "pbr": true, "texture": true, "export_uv": true, "geometry_quality": "standard", "texture_alignment": "geometry", "model_version": "v3.1-20260211" }, "output": { "type": "text_to_model", "model_url": "https://vcg-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/**********12.glb", "generated_image_url": "https://vcg-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/**********12.png", "rendered_image_url": "https://vcg-prod-1258344699.cos.ap-guangzhou.tencentcos.cn/**********12.png" }, "credits_consumed": 50, "created_at": 1785989483, "completed_at": 1785989483}

八、inputs

本次任务实际使用的输入信息。

参数名称	必选	类型	描述
front	是	string	正视图图片。
back	否	string	后视图图片。
left	否	string	左视图图片。
right	否	string	右视图图片。

九、input