Tencent Hunyuan 3D Rapid | Vtrix API Docs

接口提示

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

tencent_hunyuan_3d_rapid 提供 enable_pbr、result_format 和 enable_geometry 作为可选生成控制参数

tencent_hunyuan_3d_rapid 在 params 中不提供 face_count、generate_type、polygon_type 或上游 model 选择; multi_view_images 会兼容接收但不会转发给上游

tencent_hunyuan_3d_rapid 的 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_rapid

prompt `string`

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

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

image_base64 `string`

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

支持格式: jpg, png, jpeg, webp
分辨率: 单边需在 128 到 5000 像素之间

image_url `string`

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

支持格式: jpg, png, jpeg, webp
分辨率: 单边需在 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

enable_geometry `boolean`

是否请求上游 Rapid 接口在支持时生成白模输出

可选值: true, false

轮询

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

初始响应只返回任务 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

上传和预处理耗时（秒）

错误码

错误码	描述
13003095	上游内部生成错误
13003096	结果解析异常
13003097	上游 HTTP 响应错误
13003098	任务状态查询异常
13003099	上游任务创建异常

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_rapid", "input": [ { "params": { "prompt": "A cute sci-fi robot dog" } } ] }'

{ "id": "d7gpmlde8786gjrf4emg", "created_at": 1776393046432, "status": "completed", "model": "tencent_hunyuan_3d_rapid", "output": [ { "content": [ { "format": "obj", "jobId": "1436543442318000128", "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": 73.88364958763123, "in_queue_at": 0.9293951988220215, "upload_at": 8.858556985855103 } }

接口提示

认证

authorization string 必填

参数

model string 必填

prompt string

image_base64 string

image_url string

result_format string

enable_pbr boolean

enable_geometry boolean

轮询

响应格式

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`

enable_geometry `boolean`

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`