Hunyuan 3D Pro

tencent-hunyuan-3d-pro

Tencent Hunyuan 3D Pro supports generating textured models, low-poly models, white geometry models, and sketch-mode 3D assets from text or images, with PBR materials, face-count control, custom export formats, and multi-view image guidance.

Endpoints

POST /v1/queue/tencent-hunyuan-3d-pro # Create task

GET /v1/queue/tencent-hunyuan-3d-pro/requests/{request_id}/status # Check status

GET /v1/queue/tencent-hunyuan-3d-pro/requests/{request_id}/response # Get result

PUT /v1/queue/tencent-hunyuan-3d-pro/requests/{request_id}/cancel # Cancel task

Request parameters

curl --location "https://odirouter.ai/model/v1/queue/tencent-hunyuan-3d-pro" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "image_url": "https://example.com/reference-image.webp",
    "face_count": 3000,
    "enable_pbr": false
  }'

prompt string

Text-to-3D prompt. In Normal, LowPoly, and Geometry modes, exactly one of prompt, image_url, and image_base64 can be provided. 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, exactly one of prompt, image_url, and image_base64 can be provided. In Sketch mode, image_base64 or image_url must be provided together with prompt.

Supported formats: jpg, png, jpeg, webp

Image size: the wrapper layer recommends up to 8MB

Resolution: each side must be between 128 and 5000 pixels

image_url string

Publicly accessible input image URL. In Normal, LowPoly, and Geometry modes, exactly one of prompt, image_url, and image_base64 can be provided. 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 int

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

Range: 3000 - 1500000

Default: 500000

generate_type string

Generation task type used to control model style and output behavior. Normal generates textured geometry; LowPoly generates a retopologized low-poly asset and ignores face_count; Geometry generates an untextured white model and ignores enable_pbr; Sketch accepts sketch or line-art input and requires both prompt and image_url or image_base64.

Options: Normal, LowPoly, Geometry, Sketch

Default: Normal

polygon_type string

Polygon topology mode. Only effective when generate_type is LowPoly. triangle outputs triangle faces only; quadrilateral outputs a mix of quad and triangle faces.

Options: triangle, quadrilateral

Default: triangle

enable_pbr bool

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

Options: true, false

Default: false

result_format string

Optional export format for limiting the generated model to a single format. When omitted, Pro responses can return OBJ and GLB model outputs with previews.

Options: STL, USDZ, FBX

multi_view_images array

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

Supported views: left, right, back

Views supported only by upstream 3.1: top, bottom, left_front, right_front

For URL input, keep the total image size within 8MB. For Base64 input, keep original images around 6MB total.

Single image resolution: each side must be between 128 and 5000 pixels

Supported formats: jpg, png

ViewType string required

View identifier for the reference image.

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

ViewImageUrl string

Publicly accessible URL for the image of this view.

ViewImageBase64 string

Base64 encoded image content for this view.

Response parameters

Final 3D asset URLs may use a .bin file name. Use the output metadata, such as metadata.format, to identify the actual model format.

{
  "request_id": "mmsu_01hxyz...",
  "response_url": "https://odirouter.ai/model/v1/queue/tencent-hunyuan-3d-pro/requests/mmsu_01hxyz.../response",
  "status_url": "https://odirouter.ai/model/v1/queue/tencent-hunyuan-3d-pro/requests/mmsu_01hxyz.../status",
  "cancel_url": "https://odirouter.ai/model/v1/queue/tencent-hunyuan-3d-pro/requests/mmsu_01hxyz.../cancel",
  "queue_position": 0
}

Field	Type	Description
`request_id`	string	Task ID used for all follow-up operations.
`response_url`	string	URL to fetch the final result.
`status_url`	string	URL to query task status.
`cancel_url`	string	URL to cancel the task.
`queue_position`	int	Current queue position.

Follow-up operations

Check status

Get result

Cancel task

Error handling