Hunyuan 3d V3.1 Pro API

Image To 3d
Text To 3d

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)

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/hunyuan-3d/v3.1/pro/image-to-3d", {
  input: {
      input_image_url: "https://v3b.fal.media/files/b/0a8c3155/BTXNRrzOFsO6OvdSxdXmv_6ZcaGmrY.png"
    },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);

curl --request POST \
  --url https://fal.run/fal-ai/hunyuan-3d/v3.1/pro/image-to-3d \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "input_image_url": "https://v3b.fal.media/files/b/0a8c3155/BTXNRrzOFsO6OvdSxdXmv_6ZcaGmrY.png"
}'

Input Schema

string

required

Front view image URL. Resolution: 128-5000px, max 8MB, formats: JPG/PNG/WEBP. Tips: simple background, single object, object >50% of frame.

string

Optional back/rear view image URL (JPG/PNG recommended).

string

Optional left side view image URL (JPG/PNG recommended).

string

Optional right side view image URL (JPG/PNG recommended).

string

Optional top view image URL (v3.1 exclusive, JPG/PNG recommended).

string

Optional bottom view image URL (v3.1 exclusive, JPG/PNG recommended).

string

Optional left-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).

string

Optional right-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).

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

boolean

default:"false"

Enable PBR material generation (metallic, roughness, normal textures). Ignored when generate_type is Geometry.

integer

default:"500000"

Target polygon face count. Range: 40,000-1,500,000. Default: 500,000. Default value: 500000Range: 40000 to 1500000

Output Schema

File

required

Generated 3D object in GLB format.

File

Preview thumbnail of the generated model

ModelUrls

required

URLs for different 3D model formats

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

Endpoint: POST https://fal.run/fal-ai/hunyuan-3d/v3.1/pro/text-to-3d Endpoint ID: fal-ai/hunyuan-3d/v3.1/pro/text-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/text-to-3d",
    arguments={
        "prompt": "A super cool space ship with details"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/hunyuan-3d/v3.1/pro/text-to-3d", {
  input: {
      prompt: "A super cool space ship with details"
    },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);

curl --request POST \
  --url https://fal.run/fal-ai/hunyuan-3d/v3.1/pro/text-to-3d \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "prompt": "A super cool space ship with details"
}'

Input Schema

string

required

Text description of the 3D content to generate. Max 1024 UTF-8 characters.

GenerateTypeEnum

default:"Normal"

boolean

default:"false"

Enable PBR material generation (metallic, roughness, normal textures). Ignored when generate_type is Geometry.

integer

default:"500000"

Target polygon face count. Range: 40,000-1,500,000. Default: 500,000. Default value: 500000Range: 40000 to 1500000

Output Schema

File

required

Generated 3D object in GLB format.

File

Preview thumbnail of the generated model

ModelUrls

required

URLs for different 3D model formats

integer

The seed used for generation

Input Example

{
  "prompt": "A super cool space ship with details",
  "generate_type": "Normal",
  "enable_pbr": false,
  "face_count": 500000
}

Output Example

{
  "model_glb": {
    "content_type": "model/gltf-binary",
    "file_name": "model.glb",
    "file_size": 35833072,
    "url": "https://v3b.fal.media/files/b/0a8c5483/z6sbpr5wBRjqgnQlJM2Ot_model.glb"
  },
  "thumbnail": {
    "content_type": "image/png",
    "file_name": "preview.png",
    "file_size": 68927,
    "url": "https://v3b.fal.media/files/b/0a8c5483/EE97ZV7cM-3UVG4peyWTQ_preview.png"
  },
  "model_urls": {
    "glb": {
      "content_type": "model/gltf-binary",
      "file_name": "model.glb",
      "file_size": 35833072,
      "url": "https://v3b.fal.media/files/b/0a8c5483/z6sbpr5wBRjqgnQlJM2Ot_model.glb"
    },
    "mtl": {
      "content_type": "text/plain",
      "file_name": "material.mtl",
      "file_size": 88,
      "url": "https://v3b.fal.media/files/b/0a8c5482/ZxJepsEkhM67VSugmZ7QT_material.mtl"
    },
    "obj": {
      "content_type": "model/obj",
      "file_name": "6168030a8817075aaa55c94cc5145000.obj",
      "file_size": 34755929,
      "url": "https://v3b.fal.media/files/b/0a8c5482/ZzC1xlOftyGQxhDkbZzVW_6168030a8817075aaa55c94cc5145000.obj"
    },
    "texture": {
      "content_type": "image/png",
      "file_name": "texture_20250901.png",
      "file_size": 19996580,
      "url": "https://v3b.fal.media/files/b/0a8c5482/jOL2nBpcOGspwxQf0_U-z_texture_20250901.png"
    }
  }
}

Limitations

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

Video Generation

Image Generation

Audio

Vision

3D

Hunyuan 3d V3.1 Pro API

Try it in the Playground

Quick Start

Input Schema

Output Schema

Input Example

Output Example

Try it in the Playground

Quick Start

Input Schema

Output Schema

Input Example

Output Example

Limitations

Try it in the Playground

​Quick Start

​Input Schema

​Output Schema

​Input Example

​Output Example

Try it in the Playground

​Quick Start

​Input Schema

​Output Schema

​Input Example

​Output Example

​Related

​Limitations

Quick Start

Input Schema

Output Schema

Input Example

Output Example

Quick Start

Input Schema

Output Schema

Input Example

Output Example

Related

Limitations