Tencent Hunyuan 3D Pro | Vtrix API Docs

API Notes

tencent_hunyuan_3d_pro uses upstream Hunyuan 3D Pro Model 3.1 automatically; do not pass a model parameter inside params

tencent_hunyuan_3d_pro requires exactly one primary input among prompt, image_url, and image_base64 when generate_type is Normal, LowPoly, or Geometry

tencent_hunyuan_3d_pro requires prompt together with image_url or image_base64 when generate_type is Sketch

tencent_hunyuan_3d_pro does not support multi_view_images when generate_type is Sketch

tencent_hunyuan_3d_pro expects each multi_view_images item to use ViewType with either ViewImageUrl or ViewImageBase64

tencent_hunyuan_3d_pro 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_pro

prompt `string`

Text prompt for text-to-3D generation. In Normal, LowPoly, and Geometry modes, provide exactly one of prompt, image_url, or image_base64. In Sketch mode, prompt must be provided together with image_url or image_base64

Maximum length: 1024 UTF-8 characters

image_base64 `string`

Base64-encoded input image. In Normal, LowPoly, and Geometry modes, provide exactly one of prompt, image_url, or image_base64. In Sketch mode, image_base64 or image_url must be provided together with prompt

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

image_url `string`

Publicly accessible input image URL. In Normal, LowPoly, and Geometry modes, provide exactly one of prompt, image_url, or image_base64. In Sketch mode, image_url or image_base64 must be provided together with prompt

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

face_count `integer`

Target face count for the generated 3D model. This parameter is ignored when generate_type is LowPoly

Default: 500000

Range: 3000 - 1500000

generate_type `string`

Generation mode that controls the model style and output behavior

Normal generates textured geometry
LowPoly generates topology-optimized assets and ignores face_count
Geometry generates geometry-only assets and ignores enable_pbr
Sketch accepts sketch or line-art style input and requires prompt plus image_url or image_base64

Default: Normal

Options: Normal, LowPoly, Geometry, Sketch

polygon_type `string`

Polygon topology mode. This parameter only takes effect when generate_type is LowPoly

triangle outputs triangle faces only
quadrilateral mixes quadrilateral and triangle faces

Default: triangle

Options: triangle, quadrilateral

enable_pbr `boolean`

Whether to enable PBR material generation. This parameter is ignored when generate_type is Geometry

Default: false

Options: true, false

multi_view_images `array`

Multi-view reference images used to improve geometry consistency. This parameter is supported for non-Sketch requests only. Each item must include ViewType and either ViewImageUrl or ViewImageBase64. Only one image is allowed for each view

Supported views: left, right, back
3.1-only views upstream: top, bottom, left_front, right_front
Total payload limit: combined image payload should stay within 8MB for URL input or about 6MB before Base64 expansion
Per-image resolution: each side must be between 128 and 5000 pixels
Supported formats: jpg, png

item object

A single multi-view image object

ViewType string required

View identifier for the reference image

Options: back, left, right, top, bottom, left_front, right_front

ViewImageUrl string

Publicly accessible image URL for the specified view

ViewImageBase64 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

extra_info object

Additional upstream billing details when provided

ResultCreditConsumed integer

Upstream credits consumed for the generated result

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
13001095	Upstream internal generation error
13001096	Result parsing exception
13001097	Upstream HTTP response error
13001098	Task status polling exception
13001099	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_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 } }

API Notes

Authentication

authorization string required

Parameters

model string required

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 required

ViewImageUrl string

ViewImageBase64 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

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

Error Codes

authorization `string` required

model `string` required

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

ViewImageUrl `string`

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

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`