Hunyuan 3D v3 Prompt Engineering Guide

Configuring Hunyuan 3D v3 for Production Assets

Hunyuan 3D v3 compresses the 3D modeling timeline to minutes through a two-stage architecture: Hunyuan3D-DiT generates geometry via flow-based diffusion, while Hunyuan3D-Paint synthesizes high-resolution textures with physically-based rendering properties¹. The separation of shape and texture generation allows each stage to optimize independently, producing polygon-efficient meshes suitable for real-time applications.

Understanding how to communicate with this system determines whether you receive a usable production asset or an unusable artifact. The model exposes three distinct input modalities on fal: text-to-3D, image-to-3D, and sketch-to-3D. Each pathway requires different prompt strategies and parameter configurations to achieve optimal results.

Text-to-3D Prompt Architecture

The text-to-3D endpoint generates complete 3D models from natural language descriptions. Effective prompts follow a consistent structure that provides the model with sufficient geometric and material context.

Construct prompts with these elements in sequence:

Object identification stating precisely what you are creating
Material specification naming materials explicitly (walnut, brushed aluminum, velvet)
Surface characteristics including colors, textures, and finish qualities
Structural details describing form, proportions, and distinctive features

Consider the difference between "a chair" and "mid-century modern armchair with walnut frame, navy velvet upholstery, tapered legs, and brass feet." The latter provides material context, stylistic reference, and structural specificity that guides generation toward a predictable outcome.

API Usage

A text-to-3D request with error handling:

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

try {
  const result = await fal.subscribe("fal-ai/hunyuan3d-v3/text-to-3d", {
    input: {
      prompt:
        "Mid-century modern armchair with walnut frame and navy velvet upholstery",
      generate_type: "Normal",
      enable_pbr: true,
    },
  });

  console.log(result.model_glb.url); // GLB download URL
  console.log(result.model_urls.obj.url); // OBJ download URL
  console.log(result.thumbnail.url); // Preview image
} catch (error) {
  if (error.status === 422) {
    console.error("Invalid input parameters:", error.body);
  } else if (error.status === 401) {
    console.error("Authentication failed. Check FAL_KEY.");
  } else {
    console.error("Generation failed:", error.message);
  }
}

Parameter Configuration

The API exposes parameters that control output characteristics:

Parameter	Options	Pricing Impact
generate_type	Normal, LowPoly, Geometry	Normal: $0.375, LowPoly: $0.45, Geometry: $0.225
enable_pbr	true/false	Adds $0.15 when enabled
face_count	Custom polygon count	Adds $0.15 for non-default values

For real-time applications, configure generate_type: "LowPoly" with reduced face count. For visualization or 3D printing, use generate_type: "Normal" with enable_pbr: true.

fal^{MODEL APIs}

The fastest, cheapest and most reliable way to run genAI models. 1 API, 100s of models

Build

fal^SERVERLESS

Scale custom models and apps to thousands of GPUs instantly

Deploy

fal^COMPUTE

A fully controlled GPU cloud for enterprise AI training + research

Train

Image-to-3D Input Selection

Image-to-3D converts photographs into textured meshes. Input image quality directly constrains output fidelity.

Optimal input images share these characteristics:

Clear subject isolation against simple or removed backgrounds
Even lighting that reveals form without harsh shadows
Resolution between 512x512 and 2048x2048 pixels
Viewing angles that expose structural information

Multi-View Input

The model supports optional multi-view input using back, left, and right images alongside the primary front view. This adds $0.15 to the generation cost but reduces reconstruction ambiguity for complex geometry. Single-view input works adequately for geometrically simple objects.

Sketch-to-3D Workflows

The sketch-to-3D mode combines line drawings with text prompts, creating an intuitive pathway from concept to dimensional asset.

Prepare sketches with these considerations:

Clean, continuous boundary lines defining object silhouettes
Structural outlines without shading or texture rendering
Consistent perspective throughout the drawing
Resolution between 512x512 and 1024x1024 pixels

The sketch establishes geometric structure. The accompanying text prompt specifies attributes not visible in the drawing: materials, surface finishes, and color. Avoid restating structural information already present in the sketch. Instead, focus the prompt on material qualities like "leather upholstery, chrome metal frame, glossy finish."

Generation Type Selection

The generate_type parameter controls output style and cost:

Normal ($0.375): Fully textured models with color and surface detail. Use for visualization, e-commerce, and assets where appearance matters.

LowPoly ($0.45): Reduced polygon count while preserving textures. Optimized for real-time rendering in game engines. Despite higher cost, the polygon efficiency saves downstream processing.

Geometry ($0.225): Untextured white meshes for downstream processing. Use when applying custom materials in external software or when only shape matters.

PBR Material Generation

Enabling PBR adds metalness, roughness, and normal maps to the output for $0.15 additional cost. These maps are essential for photorealistic rendering in modern pipelines like Unreal Engine and Unity HDRP. Skip PBR when targeting stylized aesthetics or when custom shaders will replace generated materials.

Production Configurations

Different applications require distinct optimization strategies:

Game development: Set generate_type: "LowPoly" for real-time rendering compatibility. Disable PBR if implementing custom shader systems. Total cost: $0.45.

E-commerce visualization: Use generate_type: "Normal" with enable_pbr: true. Provide multiple product photographs when using image-to-3D for best reconstruction. Total cost: $0.375 + $0.15 = $0.525.

3D printing: Configure generate_type: "Normal" or "Geometry". PBR is unnecessary since physical materials replace textures. Export OBJ for compatibility with mesh repair utilities. Total cost: $0.225 to $0.375.

Architectural visualization: Leverage sketch-to-3D for rapid concept iteration. Enable PBR for realistic material representation. Total cost: $0.375 + $0.15 = $0.525.

Troubleshooting Common Issues

Geometry artifacts: Holes and extrusions typically indicate insufficient polygon budget. Request higher face count (adds $0.15) for complex organic shapes.

Blurry textures: Generic material descriptions produce generic textures. Specify materials precisely: "brushed aluminum" rather than "metal," "rough oak wood" rather than "wood."

Structural misinterpretation: When text prompts fail to communicate complex geometry, switch to sketch-to-3D mode. A simple outline often conveys structure more reliably than elaborate verbal description.

Multiple objects in output: The model performs best on single isolated subjects. Generate complex scenes by creating individual assets and compositing in 3D software.

Inconsistent results: The model incorporates stochastic elements. Generate multiple variations and select the optimal result rather than expecting perfection from any single generation.

Output Format

The API returns both GLB and OBJ formats. GLB packages geometry, textures, and materials into a single file suitable for web viewers and game engines. OBJ separates geometry from its accompanying MTL material definition, offering better compatibility with traditional 3D editing software. The response also includes a thumbnail preview image.

Both formats import directly into Unity, Unreal Engine, Blender, and Maya. PBR materials integrate with modern rendering pipelines without conversion.