Tencent Hunyuan 3D Pro | Vtrix API Docs

接口提示

tencent_hunyuan_3d_pro 服务端自动使用上游 Hunyuan 3D Pro Model=3.1; 不需要也不支持在 params 中传入 model

tencent_hunyuan_3d_pro 在 Normal、LowPoly 和 Geometry 模式下, prompt、image_url、image_base64 三者只能三选一

tencent_hunyuan_3d_pro 在 generate_type 为 Sketch 时, 必须同时传 prompt 和 image_url 或 image_base64

tencent_hunyuan_3d_pro 在 generate_type 为 Sketch 时不支持 multi_view_images

tencent_hunyuan_3d_pro 的 multi_view_images 子项应使用 ViewType 搭配 ViewImageUrl 或 ViewImageBase64

tencent_hunyuan_3d_pro 的 output[].content[] 请优先使用 format 而不是 type 判断实际资源格式, 当 format 为 obj 时 url 通常返回 .zip 压缩包

认证

authorization `string` 必填

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

访问 API Key 管理页面获取 API Key

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

model `string` 必填

请求使用的模型 ID

值: tencent_hunyuan_3d_pro

prompt `string`

文生 3D 提示词. 在 Normal、LowPoly 和 Geometry 模式下, prompt、image_url、image_base64 三者只能三选一. 在 Sketch 模式下, prompt 必须与 image_url 或 image_base64 一起传入

最大长度: 1024 个 UTF-8 字符

image_base64 `string`

Base64 编码的输入图片. 在 Normal、LowPoly 和 Geometry 模式下, prompt、image_url、image_base64 三者只能三选一. 在 Sketch 模式下, image_base64 或 image_url 必须与 prompt 一起传入

支持格式: jpg, png, jpeg, webp
图片大小: 封装层建议不超过 8MB
分辨率: 单边需在 128 到 5000 像素之间

image_url `string`

公开可访问的输入图片 URL. 在 Normal、LowPoly 和 Geometry 模式下, prompt、image_url、image_base64 三者只能三选一. 在 Sketch 模式下, image_url 或 image_base64 必须与 prompt 一起传入

支持格式: jpg, png, jpeg, webp
图片大小: 不超过 8MB
分辨率: 单边需在 128 到 5000 像素之间

face_count `integer`

生成 3D 模型的目标面数. 当 generate_type 为 LowPoly 时, 此参数不生效

默认值: 500000

范围: 3000 - 1500000

generate_type `string`

生成任务类型, 用于控制模型风格和输出行为

Normal 生成带纹理的几何模型
LowPoly 生成智能拓扑后的低模资产, 忽略 face_count
Geometry 生成不带纹理的白模, 忽略 enable_pbr
Sketch 接收草图或线稿风格输入, 且必须同时提供 prompt 和 image_url 或 image_base64

默认值: Normal

可选值: Normal, LowPoly, Geometry, Sketch

polygon_type `string`

多边形拓扑模式. 仅在 generate_type 为 LowPoly 时生效

triangle 仅输出三角面
quadrilateral 混合输出四边形面和三角面

默认值: triangle

可选值: triangle, quadrilateral

enable_pbr `boolean`

是否开启 PBR 材质生成. 当 generate_type 为 Geometry 时, 此参数不生效

默认值: false

可选值: true, false

multi_view_images `array`

用于增强几何一致性的多视角参考图片. 该参数仅支持非 Sketch 请求. 每个子项都必须包含 ViewType 以及 ViewImageUrl 或 ViewImageBase64 其中之一. 每个视角只允许一张图片

支持视角: left, right, back
上游 3.1 才支持的视角: top, bottom, left_front, right_front
总大小限制: URL 输入时建议所有图片总量控制在 8MB 以内, Base64 输入时原始图片总量建议控制在约 6MB 以内
单张分辨率: 单边需在 128 到 5000 像素之间
支持格式: jpg, png

item object

ViewType string 必填

该参考图对应的视角标识

可选值: back, left, right, top, bottom, left_front, right_front

ViewImageUrl string

当前视角图片的公开可访问 URL

ViewImageBase64 string

当前视角图片的 Base64 编码内容

轮询

由于结果生成需要时间，您需要在创建任务后轮询任务状态

初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取

轮询请求与响应示例见右侧

响应格式

id `string` 必填

任务 ID

created_at `integer` 必填

任务创建时间戳（毫秒）

status `string` 必填

任务状态

可选值: in_progress, completed, failed

model `string` 必填

模型 ID

progress `number`

任务进度, 仅在 status 为 in_progress 时存在

error `object`

错误信息, 仅在 status 为 failed 时存在

code string

错误码

message string

详细错误信息

output `array`

生成结果, 仅在 status 为 completed 时存在

content array

当前任务可下载的模型资源列表

type string

封装层资源类型. 当前 3D 响应里即使 format 为 obj, 该字段也可能返回 glb, 判断实际资源格式请以 format 为准

format string

实际导出格式, 如 obj、glb

url string

模型资源下载地址. 当 format 为 obj 时, 该地址通常指向 .zip 压缩包

preview_url string

当前模型资源对应的预览图 URL

jobId string

上游任务 ID. 同一任务返回多个资源时通常会复用同一个 jobId

usage `object`

计费和用量信息, 仅在 status 为 completed 时存在

cost string

总费用（美元）. 未返回计费信息时可能为空字符串

extra_info object

额外的上游计费信息, 仅在返回时存在

ResultCreditConsumed integer

上游返回的结果消耗 credits

input_tokens number

输入 token 数. 当前 3D 任务通常返回 null

output_tokens number

输出 token 数. 当前 3D 任务通常返回 null

quantity integer

本次任务的计费数量

total_tokens number

总 token 数. 当前 3D 任务通常返回 null

unit_price string

单价（美元）. 未返回计费信息时可能为空字符串

user_discount number

封装层返回的用户折扣值

metadata `object`

封装层返回的耗时元信息

completed_at number

任务完成耗时（秒）

in_queue_at number

队列等待耗时（秒）

upload_at number

上传和预处理耗时（秒）

错误码

错误码	描述
13001095	上游内部生成错误
13001096	结果解析异常
13001097	上游 HTTP 响应错误
13001098	任务状态查询异常
13001099	上游任务创建异常

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "tencent_hunyuan_3d_pro", "input": [ { "params": { "prompt": "A futuristic ceramic cat figurine", "generate_type": "Normal" } } ] }'

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "tencent_hunyuan_3d_pro", "input": [ { "params": { "image_url": "https://example.com/front.png", "generate_type": "Normal", "multi_view_images": [ { "ViewType": "left", "ViewImageUrl": "https://example.com/left.png" }, { "ViewType": "back", "ViewImageUrl": "https://example.com/back.png" }, { "ViewType": "right", "ViewImageUrl": "https://example.com/right.png" } ] } } ] }'

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "tencent_hunyuan_3d_pro", "input": [ { "params": { "prompt": "A hand-drawn mech cat sketch", "image_url": "https://example.com/sketch-input.png", "generate_type": "Sketch", "enable_pbr": true } } ] }'

{ "id": "d7gp8a5e8787vbqk5ql0", "created_at": 1776391209655, "status": "completed", "model": "tencent_hunyuan_3d_pro", "output": [ { "content": [ { "format": "obj", "jobId": "1436535738316922880", "preview_url": "https://example.com/generated-model-obj-preview.webp", "type": "glb", "url": "https://example.com/generated-model-obj.zip" }, { "format": "glb", "jobId": "1436535738316922880", "preview_url": "https://example.com/generated-model-glb-preview.webp", "type": "glb", "url": "https://example.com/generated-model.glb" } ] } ], "usage": { "cost": "", "extra_info": { "ResultCreditConsumed": 30 }, "input_tokens": null, "output_tokens": null, "quantity": 1, "total_tokens": null, "unit_price": "", "user_discount": 0 }, "metadata": { "completed_at": 252.79277920722961, "in_queue_at": 1.9341065883636475, "upload_at": 19.68806028366089 } }

接口提示

认证

authorization string 必填

参数

model string 必填

prompt string

image_base64 string

image_url string

face_count integer

generate_type string

polygon_type string

enable_pbr boolean

multi_view_images array

item object

ViewType string 必填

ViewImageUrl string

ViewImageBase64 string

轮询

响应格式

id string 必填

created_at integer 必填

status string 必填

model string 必填

progress number

error object

code string

message string

output array

content array

type string

format string

url string

preview_url string

jobId string

usage object

cost string

extra_info object

ResultCreditConsumed integer

input_tokens number

output_tokens number

quantity integer

total_tokens number

unit_price string

user_discount number

metadata object

completed_at number

in_queue_at number

upload_at number

错误码

authorization `string` 必填

model `string` 必填

prompt `string`

image_base64 `string`

image_url `string`

face_count `integer`

generate_type `string`

polygon_type `string`

enable_pbr `boolean`

multi_view_images `array`

item `object`

ViewType `string` 必填

ViewImageUrl `string`

ViewImageBase64 `string`

id `string` 必填

created_at `integer` 必填

status `string` 必填

model `string` 必填

progress `number`

error `object`

code `string`

message `string`

output `array`

content `array`

type `string`

format `string`

url `string`

preview_url `string`

jobId `string`

usage `object`

cost `string`

extra_info `object`

ResultCreditConsumed `integer`

input_tokens `number`

output_tokens `number`

quantity `integer`

total_tokens `number`

unit_price `string`

user_discount `number`

metadata `object`

completed_at `number`

in_queue_at `number`

upload_at `number`