# TRELLIS.2 Trainer

> Train LoRA adapters for TRELLIS.2 model


## Overview

- **Endpoint**: `https://fal.run/fal-ai/trellis-2-lora-trainer`
- **Model ID**: `fal-ai/trellis-2-lora-trainer`
- **Category**: image-to-3d
- **Kind**: training
**Description**: It trains a single TRELLIS.2 LoRA adapter from a dataset of 3D assets. The trained adapter can be used with `fal-ai/trellis-2-lora` to customize image-to-3D generation.



## Pricing

Each request is billed a one-time dataset-preparation charge of **$0.10023** per input object (*10-object minimum*, waived when you reuse a prepared dataset) plus a per-denoiser training charge of **$8.34** / **$3.25** / **$3.38** per *1,000 steps* for *sparse_structure* / *geometry* / *texture*, scaled by your rank (×0.5 / ×1 / ×2 for 16 / 32 / 64) and resolution (×1 / ×2 for 512 / 1024).

For more details, see [fal.ai pricing](https://fal.ai/pricing).

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:


- **`data_url`** (`string`, _required_):
  URL to a .zip archive containing raw 3D assets or a TRELLIS.2 preprocessed dataset zip returned by the data_preprocessing endpoint.

- **`denoisers`** (`list<Enum>`, _optional_):
  TRELLIS.2 denoisers to fine-tune. One LoRA adapter is trained per entry, and all selected denoisers are trained in parallel from the same preprocessed dataset. Provide 1-3 unique values out of sparse_structure, geometry, and texture.
  - Array of Enum

- **`resolution`** (`ResolutionEnum`, _optional_):
  Training resolution. Must match the resolution the dataset is preprocessed at. Sparse-structure training uses the same config at both resolutions; geometry and texture have dedicated 512/1024 configs. Default value: `"512"`
  - Default: `512`
  - Options: `512`, `1024`

- **`rank`** (`RankEnum`, _optional_):
  LoRA rank. Higher values increase adapter capacity. Default value: `"32"`
  - Default: `32`
  - Options: `16`, `32`, `64`

- **`learning_rate`** (`float`, _optional_):
  Learning rate for LoRA optimization. Default value: `0.0001`
  - Default: `0.0001`
  - Range: `0.000001` to `0.01`

- **`training_steps`** (`integer`, _optional_):
  Number of training steps. Default value: `1000`
  - Default: `1000`
  - Range: `100` to `10000`



**Required Parameters Example**:

```json
{
  "data_url": ""
}
```

**Full Example**:

```json
{
  "data_url": "",
  "resolution": 512,
  "rank": 32,
  "learning_rate": 0.0001,
  "training_steps": 1000
}
```


### Output Schema

The API returns the following output format:

- **`adapters`** (`list<LoraAdapterResult>`, _required_):
  Trained LoRA adapters, one per denoiser that completed successfully. Use each adapter's file in the matching trellis-2-lora inference field.
  - Array of LoraAdapterResult

- **`failed`** (`list<LoraTrainingFailure>`, _optional_):
  Denoisers whose training did not complete. Empty when every requested denoiser succeeded.
  - Array of LoraTrainingFailure

- **`preprocessed_data_file`** (`File`, _required_):
  Reusable TRELLIS.2 preprocessed dataset zip used for training.



**Example Response**:

```json
{
  "adapters": [
    {
      "denoiser": "sparse_structure",
      "resolution": 512,
      "lora_file": {
        "url": "",
        "content_type": "image/png",
        "file_name": "z9RV14K95DvU.png",
        "file_size": 4404019
      },
      "rank": 16
    }
  ],
  "failed": [
    {
      "denoiser": "sparse_structure",
      "error": ""
    }
  ],
  "preprocessed_data_file": {
    "url": "",
    "content_type": "image/png",
    "file_name": "z9RV14K95DvU.png",
    "file_size": 4404019
  }
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/fal-ai/trellis-2-lora-trainer \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
     "data_url": ""
   }'
```

### Python

Ensure you have the Python client installed:

```bash
pip install fal-client
```

Then use the API client to make requests:

```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/trellis-2-lora-trainer",
    arguments={
        "data_url": ""
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

### JavaScript

Ensure you have the JavaScript client installed:

```bash
npm install --save @fal-ai/client
```

Then use the API client to make requests:

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

const result = await fal.subscribe("fal-ai/trellis-2-lora-trainer", {
  input: {
    data_url: ""
  },
  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);
```


## Additional Resources

### Documentation

- [Model Playground](https://fal.ai/models/fal-ai/trellis-2-lora-trainer)
- [API Documentation](https://fal.ai/models/fal-ai/trellis-2-lora-trainer/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/trellis-2-lora-trainer)

### fal.ai Platform

- [Platform Documentation](https://docs.fal.ai)
- [Python Client](https://docs.fal.ai/clients/python)
- [JavaScript Client](https://docs.fal.ai/clients/javascript)