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.