Tencent Hunyuan 3D | Vtrix API Docs

API Notes

tencent_hunyuan_3d requires exactly one primary input among prompt, image_url, and image_base64

tencent_hunyuan_3d supports multi-view guidance through multi_view_images with View and either ImageUrl or ImageBase64

tencent_hunyuan_3d only accepts left, right, and back as View values in multi_view_images

tencent_hunyuan_3d uses format instead of type to identify the actual asset format in output[].content[], and url typically returns a .zip package when format is obj

Authentication

authorization `string` required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

model `string` required

Model ID to use for the request

Value: tencent_hunyuan_3d

prompt `string`

Text prompt for text-to-3D generation. Provide exactly one of prompt, image_url, or image_base64

Maximum length: 1024 UTF-8 characters

image_base64 `string`

Base64-encoded input image. Provide exactly one of prompt, image_url, or image_base64

Supported formats: jpg, png, jpeg, webp
Image size: up to 8MB
Resolution: each side must be between 128 and 5000 pixels

image_url `string`

Publicly accessible input image URL. Provide exactly one of prompt, image_url, or image_base64

Supported formats: jpg, png, jpeg, webp
Image size: up to 8MB
Resolution: each side must be between 128 and 5000 pixels

result_format `string`

Desired export format for the generated 3D asset. Use output[].content[].format as the authoritative returned format. When format is obj, the downloadable url usually points to a .zip package

Options: OBJ, GLB, STL, USDZ, FBX, MP4

enable_pbr `boolean`

Whether to enable PBR material generation for the output asset

Options: true, false

multi_view_images `array`

Optional multi-view reference images used to improve geometry consistency. Each item must include View and either ImageUrl or ImageBase64

Supported views: left, right, back

item object

A single multi-view image object

View string required

View identifier for the reference image

Options: left, right, back

ImageUrl string

Publicly accessible image URL for the specified view

ImageBase64 string

Base64-encoded image content for the specified view

Polling

Since result generation takes time, you need to poll the task status after creating the task.

The initial response only returns information such as the task ID and initial status. The final result must be obtained by polling the task status endpoint using the task ID.

See the examples on the right for polling requests and responses.

Response Format

id `string` required

Task ID

created_at `integer` required

Task creation timestamp in milliseconds

status `string` required

Task status

Options: in_progress, completed, failed

model `string` required

Model ID

progress `number`

Task progress, only present when status is in_progress

error `object`

Error information, only present when status is failed

code string

Error code

message string

Detailed error message

output `array`

Generated results, only present when status is completed

content array

Downloadable model resources for the completed task

type string

Wrapper resource type. In current 3D responses this field may still return glb even when format is obj, so use format to determine the actual asset format

format string

Actual export format for the returned asset, such as obj or glb

url string

Download URL for the model asset. When format is obj, this URL usually points to a .zip package

preview_url string

Preview image URL for the current asset

jobId string

Upstream job ID. Multiple assets in the same task can share the same jobId

usage `object`

Billing and usage information, only present when status is completed

cost string

Total cost in USD. This field can be an empty string when billing data is not returned

input_tokens number

Input token count. Current 3D tasks usually return null

output_tokens number

Output token count. Current 3D tasks usually return null

quantity integer

Billable quantity for the task

total_tokens number

Total token count. Current 3D tasks usually return null

unit_price string

Unit price in USD. This field can be an empty string when billing data is not returned

user_discount number

User discount value returned by the wrapper

metadata `object`

Timing metadata returned by the wrapper

completed_at number

Time to completion in seconds

in_queue_at number

Time spent in queue in seconds

upload_at number

Upload and preprocessing time in seconds

Error Codes

Error Code	Description
13002095	Upstream internal generation error
13002096	Result parsing exception
13002097	Upstream HTTP response error
13002098	Task status polling exception
13002099	Upstream task creation exception

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 } }

API Notes

Authentication

authorization string required

Parameters

model string required

prompt string

image_base64 string

image_url string

result_format string

enable_pbr boolean

multi_view_images array

item object

View string required

ImageUrl string

ImageBase64 string

Polling

Response Format

id string required

created_at integer required

status string required

model string required

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

Error Codes

authorization `string` required

model `string` required

prompt `string`

image_base64 `string`

image_url `string`

result_format `string`

enable_pbr `boolean`

multi_view_images `array`

item `object`

View `string` required

ImageUrl `string`

ImageBase64 `string`

id `string` required

created_at `integer` required

status `string` required

model `string` required

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`