Tencent Hunyuan 3D Pro

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

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

error `object`

Error information, only present when status is failed

code string

Error code

message string

Detailed error message

output `array`

Generation results, only present when status is completed

content array

List of generated resource content

type string

Resource type

Value: image｜video

url string

Processed resource URL

jobId string

Remote task ID

usage `object`

Usage statistics, only present when status is completed

cost string

Total cost in USD

discount number

Discount amount

metadata `object`

Metadata information

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": "task_id", "created_at": 1769757744021, "status": "completed", "model": "tencent_hunyuan_3d_pro", "output": [ { "content": [ { "type": "glb", "format": "glb", "url": "https://example.com/generated-model.glb", "preview_url": "https://example.com/generated-preview.webp", "jobId": "1436190229014241280" } ] } ], "usage": { "cost": "0.000500", "discount": 0, "quantity": 1, "unit_price": "0.000500" } }

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

error `object`

code `string`

message `string`

output `array`

content `array`

type `string`

url `string`

jobId `string`

usage `object`

cost `string`

discount `number`

metadata `object`

Error Codes

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

error object

code string

message string

output array

content array

type string

url string

jobId string

usage object

cost string

discount number

metadata object

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`

error `object`

code `string`

message `string`

output `array`

content `array`

type `string`

url `string`

jobId `string`

usage `object`

cost `string`

discount `number`

metadata `object`