Skip to main content
Endpoint: POST https://fal.run/fal-ai/hunyuan-3d/v3.1/pro/image-to-3d Endpoint ID: fal-ai/hunyuan-3d/v3.1/pro/image-to-3d

Try it in the Playground

Run this model interactively with your own prompts.

​
Quick Start

import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/hunyuan-3d/v3.1/pro/image-to-3d",
    arguments={
        "input_image_url": "https://v3b.fal.media/files/b/0a8c3155/BTXNRrzOFsO6OvdSxdXmv_6ZcaGmrY.png"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)

​
Input Schema

​
input_image_url
string
required
Front view image URL. Resolution: 128-5000px, max 8MB, formats: JPG/PNG/WEBP. Tips: simple background, single object, object >50% of frame.
​
back_image_url
string
Optional back/rear view image URL (JPG/PNG recommended).
​
left_image_url
string
Optional left side view image URL (JPG/PNG recommended).
​
right_image_url
string
Optional right side view image URL (JPG/PNG recommended).
​
top_image_url
string
Optional top view image URL (v3.1 exclusive, JPG/PNG recommended).
​
bottom_image_url
string
Optional bottom view image URL (v3.1 exclusive, JPG/PNG recommended).
​
left_front_image_url
string
Optional left-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).
​
right_front_image_url
string
Optional right-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).
​
generate_type
GenerateTypeEnum
default:"Normal"
Generation task type. Normal: textured model. Geometry: geometry-only white model (no textures). LowPoly/Sketch are not available in v3.1. Default value: "Normal"Possible values: Normal, Geometry
​
enable_pbr
boolean
default:"false"
Enable PBR material generation (metallic, roughness, normal textures). Ignored when generate_type is Geometry.
​
face_count
integer
default:"500000"
Target polygon face count. Range: 40,000-1,500,000. Default: 500,000. Default value: 500000Range: 40000 to 1500000

​
Output Schema

​
model_glb
File
required
Generated 3D object in GLB format.
​
thumbnail
File
Preview thumbnail of the generated model
​
model_urls
ModelUrls
required
URLs for different 3D model formats
​
seed
integer
The seed used for generation

​
Input Example

{
  "input_image_url": "https://v3b.fal.media/files/b/0a8c3155/BTXNRrzOFsO6OvdSxdXmv_6ZcaGmrY.png",
  "generate_type": "Normal",
  "enable_pbr": false,
  "face_count": 500000
}

​
Output Example

{
  "model_glb": {
    "content_type": "model/gltf-binary",
    "file_name": "model.glb",
    "file_size": 38554640,
    "url": "https://v3b.fal.media/files/b/0a8c3187/jOeZmtBuhdQMkDu65AkdT_model.glb"
  },
  "thumbnail": {
    "content_type": "image/png",
    "file_name": "preview.png",
    "file_size": 194908,
    "url": "https://v3b.fal.media/files/b/0a8c3187/gxidaODj4OvPXruCfrZ-__preview.png"
  },
  "model_urls": {
    "glb": {
      "content_type": "model/gltf-binary",
      "file_name": "model.glb",
      "file_size": 38554640,
      "url": "https://v3b.fal.media/files/b/0a8c3187/jOeZmtBuhdQMkDu65AkdT_model.glb"
    },
    "obj": {
      "content_type": "model/obj",
      "file_name": "model.obj",
      "file_size": 31447160,
      "url": "https://v3b.fal.media/files/b/0a8c3186/no-aBFEDnOuthILfv-wzs_model.obj"
    }
  }
}

​
Limitations

  • generate_type restricted to: Normal, Geometry
  • face_count range: 40000 to 1500000