fal-ai/trellis-2-lora

TRELLIS.2 LoRA

Overview

trellis-2-lora converts a single input image into a textured 3D GLB using TRELLIS.2 plus one or more stage-specific LoRA adapters. The adapters are trained with trellis-2-lora-trainer and are applied to the matching stage of the 3D generation pipeline.

Key features:

• Image-to-3D generation with custom TRELLIS.2 LoRA adapters.
• Supports sparse-structure, geometry, and texture LoRAs independently or together.
• Returns a ready-to-download .glb file.
• Lets you control mesh density and texture resolution at export time.

You must provide at least one LoRA URL. Any stage without a LoRA uses the base TRELLIS.2 model.

Input Parameters Reference

Image

image_url (required)

Type: string

URL of the input image to convert to a 3D model. Use a clear image with one main object, strong foreground/background separation, and visible shape cues.

The image is validated up to 4096x4096 pixels, then resized to fit within 1024x1024 pixels before generation.

LoRA Adapters

sparse_structure_lora_url

Type: string or null Default: null

Optional .safetensors LoRA trained with denoiser: "sparse_structure".

This adapter affects the earliest 3D structure stage: the coarse occupancy, silhouette, and broad proportions of the generated object.

geometry_lora_url

Type: string or null Default: null

Optional .safetensors LoRA trained with denoiser: "geometry".

This adapter affects the detailed shape stage: object-specific geometry, surface form, and structural details after the sparse structure has been created.

texture_lora_url

Type: string or null Default: null

Optional .safetensors LoRA trained with denoiser: "texture".

This adapter affects the texture/material stage: colors, surface appearance, PBR-style material cues, and visual finish.

LoRA field	Train with	Best for
sparse_structure_lora_url	denoiser: "sparse_structure"	Coarse shape, silhouette, object category proportions
geometry_lora_url	denoiser: "geometry"	Detailed geometry, surface form, structural traits
texture_lora_url	denoiser: "texture"	Materials, colors, texture style, surface appearance

Each LoRA checkpoint must be a valid .safetensors adapter. Checkpoint downloads are limited to 2048 MB.

Generation Settings

resolution

Type: integer Default: 512 Allowed values: 512, 1024

Generation resolution. 1024 runs the cascade pipeline for more detail and must match the resolution the provided LoRA adapters were trained at (see trellis-2-lora-trainer). Pairing a 1024-trained adapter with resolution: 512 (or vice versa) fails.

Per-stage sampler controls

Each of the three TRELLIS.2 stages exposes the same six classifier-free-guidance and sampling controls, mirroring the base trellis-2 endpoint. Prefix the control with the stage:

• ss_ — sparse structure (rough shape/occupancy)
• shape_slat_ — shape (detailed geometry)
• tex_slat_ — texture (color/material)

Control (per stage)	Type	Default (ss / shape / tex)	Description
{stage}_guidance_strength	number (0–10)	7.5 / 7.5 / 1.0	Guidance strength; higher follows the image more closely.
{stage}_guidance_rescale	number (0–1)	0.7 / 0.5 / 0.0	Dampens high-guidance artifacts.
{stage}_guidance_interval_start	number (0–1)	0.6 / 0.6 / 0.6	Denoising fraction where guidance starts.
{stage}_guidance_interval_end	number (0–1)	1.0 / 1.0 / 0.9	Denoising fraction where guidance ends (must be ≥ start).
{stage}_sampling_steps	integer (1–50)	12 / 12 / 12	Denoising steps; more = slower, potentially higher quality.
{stage}_rescale_t	number (1–6)	5.0 / 3.0 / 3.0	Noise-schedule sharpness.

For example, ss_sampling_steps, shape_slat_guidance_strength, and tex_slat_guidance_interval_end control the three stages respectively. The defaults reproduce the base trellis-2 behavior.

Export Settings

seed

Type: integer or null Default: null

Random seed for reproducible generation. Reuse the same seed, image, adapter URLs, and export settings to reproduce a result as closely as possible.

decimation_target

Type: integer Default: 500000 Range: 5000 to 2000000

Target vertex count for the exported GLB.

Value	Use Case
20000-50000	Lightweight web/mobile previews
500000	Balanced default for most usage
1000000+	Higher-detail meshes with larger files

texture_size

Type: integer Default: 2048 Allowed values: 1024, 2048, 4096

Texture resolution baked into the GLB.

Value	Use Case
1024	Smaller files and faster loading
2048	Balanced default
4096	More texture detail with larger output files

Outputs

model_glb

Type: file

Generated 3D GLB file.

seed

Type: integer

Seed used for generation. Store this if you want to reproduce or compare results.

resolution

Type: integer

Generation resolution used (512 or 1024).

sparse_structure_lora_url

Type: string | null

Sparse-structure LoRA checkpoint applied for this generation, echoed from the request (null if none was provided).

geometry_lora_url

Type: string | null

Geometry LoRA checkpoint applied for this generation, echoed from the request (null if none was provided).

texture_lora_url

Type: string | null

Texture LoRA checkpoint applied for this generation, echoed from the request (null if none was provided). Together, these three fields show exactly which adapters shaped the result.

decimation_target

Type: integer

Target vertex count used for the exported GLB.

texture_size

Type: integer

Texture resolution baked into the exported GLB.

How LoRA Inference Works

1. The endpoint validates the input image and prepares it for TRELLIS.2.
2. Each provided LoRA checkpoint is downloaded and checked as a .safetensors adapter.
3. The adapter is loaded into its matching TRELLIS.2 stage:
   • sparse structure
   • geometry
   • texture
4. TRELLIS.2 generates the 3D object from the image.
5. The generated mesh is exported as a GLB using decimation_target and texture_size.

Only the stages you provide are customized. For example, if you provide only texture_lora_url, the sparse-structure and geometry stages remain the base TRELLIS.2 model.

Using Adapters Independently or Together

Use one adapter

Use a single adapter when you only want to customize one part of the pipeline.

json
{
  "image_url": "https://example.com/product.png",
  "texture_lora_url": "https://example.com/texture_lora.safetensors",
  "seed": 1234,
  "decimation_target": 500000,
  "texture_size": 2048
}

Use two adapters

Use two adapters when you want to customize related stages, such as geometry and texture, while keeping the initial sparse structure from the base model.

json
{
  "image_url": "https://example.com/product.png",
  "geometry_lora_url": "https://example.com/geometry_lora.safetensors",
  "texture_lora_url": "https://example.com/texture_lora.safetensors"
}

Use all three adapters

Use all three adapters when you trained a full stage stack from the same dataset and want the output to reflect that dataset throughout the whole generation process.

json
{
  "image_url": "https://example.com/product.png",
  "sparse_structure_lora_url": "https://example.com/sparse_structure_lora.safetensors",
  "geometry_lora_url": "https://example.com/geometry_lora.safetensors",
  "texture_lora_url": "https://example.com/texture_lora.safetensors",
  "seed": 1234
}

There is no adapter scale or blending parameter on this endpoint. If a URL is provided, that adapter is used for its stage.

Training and Inference Mapping

Each trellis-2-lora-trainer request trains exactly one adapter. Use the returned lora_file in the matching inference field.

Trainer denoiser	Inference field
sparse_structure	sparse_structure_lora_url
geometry	geometry_lora_url
texture	texture_lora_url

Do not put a texture LoRA into the geometry field, or a geometry LoRA into the sparse-structure field. The endpoint validates the adapter against the stage it is loaded into.

Tips for Good Results

• Use input images with a single, centered object. Crowded scenes and unclear silhouettes are harder to convert into stable 3D structure.
• Match the adapter to the thing you want to control. Texture LoRAs help appearance, but they will not teach a new object silhouette by themselves.
• Train related adapters from the same preprocessed dataset when you plan to combine them.
• Keep track of which denoiser produced each .safetensors file. Rename downloaded adapters clearly if your workflow stores multiple files.
• Use a fixed seed when comparing different adapter combinations.
• Lower decimation_target for delivery to realtime viewers, and increase it when inspecting geometry detail.

Common Errors

• No LoRA URL provided: pass at least one of sparse_structure_lora_url, geometry_lora_url, or texture_lora_url.
• Invalid checkpoint: use a .safetensors TRELLIS.2 LoRA returned by the trainer.
• Wrong adapter stage: pass each trained LoRA to its matching field.
• Poor object detection from image: try an image with a clearer object, less background clutter, and better foreground/background contrast.

Billing

A successful inference request is billed as 6 billable units.