⌘K

Tencent Hunyuan 3D Pro

tencent_hunyuan_3d_pro

Tencent Hunyuan 3D Pro 支持通过文本或图片生成带纹理模型、低模模型、白模和草图模式 3D 资产，并提供 PBR 材质、面数控制和多视角图像引导能力.

接口提示

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

认证

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 轮询任务状态接口获取

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

响应格式

error object

错误信息, 仅在状态为 failed 时存在

code string

错误码

message string

详细错误信息

output array

生成结果, 仅在状态为 completed 时存在

content array

生成的资源内容列表

type string

资源类型

值: image｜video

url string

处理后的资源 URL

jobId string

远端任务 ID

usage object

使用统计, 仅在状态为 completed 时存在

cost string

总费用（美元）

discount number

折扣金额

metadata object

元数据信息

错误码

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