Tencent Hunyuan 3D | Vtrix API Docs

接口提示

tencent_hunyuan_3d 的 prompt、image_url 和 image_base64 三者只能三选一作为主输入

tencent_hunyuan_3d 支持通过 multi_view_images 提供多视角引导, 子项应使用 View 搭配 ImageUrl 或 ImageBase64

tencent_hunyuan_3d 的 multi_view_images 仅支持 left、right 和 back 三种 View 取值

tencent_hunyuan_3d 的 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

prompt `string`

文生 3D 提示词. prompt、image_url 和 image_base64 三者只能三选一

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

image_base64 `string`

Base64 编码的输入图片. prompt、image_url 和 image_base64 三者只能三选一

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

image_url `string`

公开可访问的输入图片 URL. prompt、image_url 和 image_base64 三者只能三选一

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

result_format `string`

生成 3D 资产的目标导出格式. 请以 output[].content[].format 判断实际返回格式. 当 format 为 obj 时, 可下载的 url 通常指向 .zip 压缩包

可选值: OBJ, GLB, STL, USDZ, FBX, MP4

enable_pbr `boolean`

是否为输出资产生成 PBR 材质

可选值: true, false

multi_view_images `array`

用于增强几何一致性的可选多视角参考图列表. 每个子项都必须包含 View 以及 ImageUrl 或 ImageBase64 其中之一

支持视角: left, right, back

item object

单个多视角参考图对象

View string 必填

当前参考图对应的视角标识

可选值: left, right, back

ImageUrl string

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

ImageBase64 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

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

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

上传和预处理耗时（秒）

错误码

错误码	描述
13002095	上游内部生成错误
13002096	结果解析异常
13002097	上游 HTTP 响应错误
13002098	任务状态查询异常
13002099	上游任务创建异常

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", "input": [ { "params": { "prompt": "A stylized ceramic fox figurine", "enable_pbr": true, "result_format": "GLB" } } ] }'

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", "input": [ { "params": { "image_url": "https://example.com/front.png", "multi_view_images": [ { "View": "left", "ImageUrl": "https://example.com/left.png" }, { "View": "back", "ImageUrl": "https://example.com/back.png" }, { "View": "right", "ImageUrl": "https://example.com/right.png" } ] } } ] }'

{ "id": "d7gp885e8787vbqk5qig", "created_at": 1776391200897, "status": "completed", "model": "tencent_hunyuan_3d", "output": [ { "content": [ { "format": "obj", "jobId": "1436535701570461696", "preview_url": "https://example.com/generated-model-obj-preview.webp", "type": "glb", "url": "https://example.com/generated-model-obj.zip" } ] } ], "usage": { "cost": "", "input_tokens": null, "output_tokens": null, "quantity": 1, "total_tokens": null, "unit_price": "", "user_discount": 0 }, "metadata": { "completed_at": 155.25190353393555, "in_queue_at": 0.991074800491333, "upload_at": 9.9931321144104 } }

接口提示

认证

authorization string 必填

参数

model string 必填

prompt string

image_base64 string

image_url string

result_format string

enable_pbr boolean

multi_view_images array

item object

View string 必填

ImageUrl string

ImageBase64 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

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`

result_format `string`

enable_pbr `boolean`

multi_view_images `array`

item `object`

View `string` 必填

ImageUrl `string`

ImageBase64 `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`

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`