Hunyuan 3d V3.1 Rapid API

API reference for Hunyuan 3d V3.1 Rapid. Rapidly generate 3D models from images using Hunyuan 3D.

Image To 3d

Endpoint: POST https://fal.run/fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d Endpoint ID: fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d

Try it in the Playground

Run this model interactively with your own prompts.

Quick Start

Python

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/rapid/image-to-3d",
    arguments={
        "input_image_url": "https://v3b.fal.media/files/b/0a865ab1/omYcawLUo4RZbO8J6ZgZR.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/rapid/image-to-3d", {
  input: {
      input_image_url: "https://v3b.fal.media/files/b/0a865ab1/omYcawLUo4RZbO8J6ZgZR.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/rapid/image-to-3d \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "input_image_url": "https://v3b.fal.media/files/b/0a865ab1/omYcawLUo4RZbO8J6ZgZR.png"
}'

Input Schema

input_image_url · string · required

Front view image URL. Resolution: 128-5000px, max 8MB (recommended ≤6MB for base64 encoding), formats: JPG/PNG/WEBP. Tips: simple background, single object, object >50% of frame.

enable_pbr · boolean · default: "false"

Enable PBR material generation (metallic, roughness, normal textures). Does not take effect when enable_geometry is True.

enable_geometry · boolean · default: "false"

Generate geometry-only white model without textures. When enabled, enable_pbr is ignored and OBJ is not supported (default output is GLB).

Output Schema

model_glb · File

Generated 3D model file. Contains GLB if available, otherwise OBJ.

material_mtl · File

MTL material file for the OBJ model.

texture · File

Texture image for the 3D model.

thumbnail · File

Preview thumbnail of the generated model

model_urls · ModelUrls · required

URLs for different 3D model formats.

Input Example

{
  "input_image_url": "https://v3b.fal.media/files/b/0a865ab1/omYcawLUo4RZbO8J6ZgZR.png",
  "enable_pbr": false,
  "enable_geometry": false
}

Output Example

{
  "model_glb": {
    "content_type": "model/obj",
    "file_name": "8b1dbea208d194b9089a950abc2df426.obj",
    "file_size": 3172659,
    "url": "https://v3b.fal.media/files/b/0a8c4439/vj933H8B4W3wbd3e2RNby_8b1dbea208d194b9089a950abc2df426.obj"
  },
  "material_mtl": {
    "content_type": "text/plain",
    "file_name": "material.mtl",
    "file_size": 88,
    "url": "https://v3b.fal.media/files/b/0a8c4439/_RhytNH4xZ5EFHr34YzJt_material.mtl"
  },
  "texture": {
    "content_type": "image/png",
    "file_name": "texture_20250901.png",
    "file_size": 11728567,
    "url": "https://v3b.fal.media/files/b/0a8c4439/_4NXiSoGcZ-GYwmgUTfHZ_texture_20250901.png"
  },
  "thumbnail": {
    "content_type": "image/png",
    "file_name": "preview.png",
    "file_size": 82521,
    "url": "https://v3b.fal.media/files/b/0a8c4439/70Sm1pZ16SQP-mEbaKICC_preview.png"
  },
  "model_urls": {
    "mtl": {
      "content_type": "text/plain",
      "file_name": "material.mtl",
      "file_size": 88,
      "url": "https://v3b.fal.media/files/b/0a8c4439/_RhytNH4xZ5EFHr34YzJt_material.mtl"
    },
    "obj": {
      "content_type": "model/obj",
      "file_name": "8b1dbea208d194b9089a950abc2df426.obj",
      "file_size": 3172659,
      "url": "https://v3b.fal.media/files/b/0a8c4439/vj933H8B4W3wbd3e2RNby_8b1dbea208d194b9089a950abc2df426.obj"
    },
    "texture": {
      "content_type": "image/png",
      "file_name": "texture_20250901.png",
      "file_size": 11728567,
      "url": "https://v3b.fal.media/files/b/0a8c4439/_4NXiSoGcZ-GYwmgUTfHZ_texture_20250901.png"
    }
  }
}

Text To 3d

Endpoint: POST https://fal.run/fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d Endpoint ID: fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d

Try it in the Playground

Run this model interactively with your own prompts.

Quick Start

Python

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/rapid/text-to-3d",
    arguments={
        "prompt": "A rustic wooden treasure chest with metal bands and ornate lock"
    },
    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/rapid/text-to-3d", {
  input: {
      prompt: "A rustic wooden treasure chest with metal bands and ornate lock"
    },
  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/rapid/text-to-3d \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "prompt": "A rustic wooden treasure chest with metal bands and ornate lock"
}'

Input Schema

prompt · string · required

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

enable_pbr · boolean · default: "false"

Enable PBR material generation (metallic, roughness, normal textures). Does not take effect when enable_geometry is True.

enable_geometry · boolean · default: "false"

Generate geometry-only white model without textures. When enabled, enable_pbr is ignored and OBJ is not supported (default output is GLB).

Output Schema

model_obj · File

Generated 3D model in OBJ format.

material_mtl · File

MTL material file for the OBJ model.

texture · File

Texture image for the 3D model.

thumbnail · File

Preview thumbnail of the generated model

model_urls · ModelUrls · required

URLs for different 3D model formats.

Input Example

{
  "prompt": "A rustic wooden treasure chest with metal bands and ornate lock",
  "enable_pbr": false,
  "enable_geometry": false
}

Output Example

{
  "model_obj": {
    "content_type": "model/obj",
    "file_name": "0f7f7a1ac578c80d4397a7f2b69b40ff.obj",
    "file_size": 5306476,
    "url": "https://v3b.fal.media/files/b/0a8c44d5/2W2KRP1DM_-4qI8F_n05b_0f7f7a1ac578c80d4397a7f2b69b40ff.obj"
  },
  "material_mtl": {
    "content_type": "text/plain",
    "file_name": "material.mtl",
    "file_size": 157,
    "url": "https://v3b.fal.media/files/b/0a8c44d5/EHzTxJtHpdIliaMNnEke-_material.mtl"
  },
  "texture": {
    "content_type": "image/png",
    "file_name": "material.png",
    "file_size": 5915609,
    "url": "https://v3b.fal.media/files/b/0a8c44d5/T0q-P0aqXVG_y7jff-XTa_material.png"
  },
  "thumbnail": {
    "content_type": "image/png",
    "file_name": "preview.png",
    "file_size": 281374,
    "url": "https://v3b.fal.media/files/b/0a8c44d6/D9_IYgpugP0deXvSwBC2J_preview.png"
  },
  "model_urls": {
    "mtl": {
      "content_type": "text/plain",
      "file_name": "material.mtl",
      "file_size": 157,
      "url": "https://v3b.fal.media/files/b/0a8c44d5/EHzTxJtHpdIliaMNnEke-_material.mtl"
    },
    "obj": {
      "content_type": "model/obj",
      "file_name": "0f7f7a1ac578c80d4397a7f2b69b40ff.obj",
      "file_size": 5306476,
      "url": "https://v3b.fal.media/files/b/0a8c44d5/2W2KRP1DM_-4qI8F_n05b_0f7f7a1ac578c80d4397a7f2b69b40ff.obj"
    },
    "texture": {
      "content_type": "image/png",
      "file_name": "material.png",
      "file_size": 5915609,
      "url": "https://v3b.fal.media/files/b/0a8c44d5/T0q-P0aqXVG_y7jff-XTa_material.png"
    }
  }
}

Related

• Hunyuan 3D Pro Image to 3D — 3D
• Hunyuan 3D Pro Text to 3D — 3D
• Hunyuan 3d — 3D
• Hunyuan 3D Smart Topology — 3D
• Hunyuan 3D Part Splitter — 3D
• Hunyuan 3D Rapid Image to 3D — 3D