> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenfall.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# llms.py

> Use llms.py with Lumenfall

[llms.py](https://github.com/ServiceStack/llms) is a lightweight CLI and web UI to access hundreds of AI models across many providers. Its out of the box support for image models is limited.

With the Lumenfall extension, you can access all of our image models inside llms.py.

## How it works

The Lumenfall extension registers as an image generation provider inside llms.py. Once installed, you can generate images from any terminal with a single command:

```bash theme={null}
llms --out image "A capybara relaxing in a hot spring" -m gemini-3-pro-image
```

The extension:

1. **Registers as a provider** once added to `~/.llms/llms.json` and `LUMENFALL_API_KEY` is set
2. **Routes all image requests** through Lumenfall's unified API
3. **Caches generated images** to disk and displays local file paths

## Prerequisites

* [llms.py](https://github.com/ServiceStack/llms) installed
* A Lumenfall API key ([get one here](https://lumenfall.ai/app/api_keys))

## Installation

```bash theme={null}
llms --add lumenfall
```

## Configuration

### 1. Set your API key

The API key is configured via the `LUMENFALL_API_KEY` environment variable. To make it available in every shell session, add it to your shell profile:

```bash theme={null}
# Bash (~/.bashrc or ~/.bash_profile)
echo 'export LUMENFALL_API_KEY="lmnfl_your_api_key"' >> ~/.bashrc
source ~/.bashrc

# Zsh (~/.zshrc)
echo 'export LUMENFALL_API_KEY="lmnfl_your_api_key"' >> ~/.zshrc
source ~/.zshrc
```

### 2. Register the provider (Optional)

If you want to be able to turn the provider on and off in the web interface, add it to the `providers` section of `~/.llms/llms.json`:

```json theme={null}
{
  "providers": {
    "lumenfall": { "enabled": true, "npm": "llmspy_lumenfall" }
  }
}
```

## Usage

### List available models

```bash theme={null}
llms --check lumenfall
```

### Generate images

#### Basic generation

```bash theme={null}
llms --out image "A capybara relaxing in a hot spring" -m gemini-3-pro-image
```

Output:

```
Saved files:
/home/user/.llms/cache/ab/abc123def456.png
http://localhost:8000/~cache/ab/abc123def456.png
```

#### Using different models

```bash theme={null}
# GPT Image 1.5
llms --out image "A capybara wearing a tiny sombrero" -m gpt-image-1.5

# FLUX 2 Max
llms --out image "A capybara in a neon-lit Tokyo alley" -m flux.2-max

# Seedream 4.5
llms --out image "A capybara painting a self-portrait" -m seedream-4.5
```

### Edit images

Image editing is also supported through Lumenfall.

```bash theme={null}
llms "Add a tiny sombrero to the capybara" -m gpt-image-1 --image photo.png
```

<Info>
  Even image editing models that usually can't be used in a conversational interface, like Seedream-4.5, can be used with turn based editing.
</Info>

## Web UI

llms.py includes a built-in web UI where all Lumenfall functionality - image generation and editing - works the same as on the CLI. Start it with:

```bash theme={null}
llms --server 8000
```

Then open `http://localhost:8000` in your browser.

## Available models

Lumenfall strives to offer every image model that exists, backend by multiple providers.
You can find our current selection in the [model catalog](https://lumenfall.ai/models).

For models that are available on other providers in llmspy, the first match is used. See "Routing" below to control this.

## Routing with other providers

llms.py uses the first matching provider for a given model. To ensure all image requests go through Lumenfall, list it **first** in your `providers` config - before any other providers that may also serve image models (e.g. Google, OpenAI, or OpenRouter):

```json theme={null}
{
  "providers": {
    "lumenfall": { "enabled": true, "npm": "llmspy_lumenfall" },
    "google": { ... },
    "openai": { ... },
    ...
  }
}
```

## Known limitations

* **Provider forcing not supported.** [Lumenfall providers](/providers) cannot be forced by prepending the provider in the model (e.g. `replicate/gemini-3-pro-image`) as usual.

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full API documentation.
  </Card>

  <Card title="Available models" icon="cube" href="/api-reference/models/list">
    See all available image generation models.
  </Card>
</CardGroup>