> ## 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.

# LiteLLM

> Use LiteLLM with Lumenfall

[LiteLLM](https://github.com/BerriAI/litellm) is a popular Python library that provides a unified interface to 100+ LLM providers. You can use LiteLLM with Lumenfall to access many more media models out of the box than LiteLLM supports through other providers.

LiteLLM can be used in two ways:

* **Python SDK:** Your code connects directly to the Lumenfall API. Recommended if you just want to use media models, as Lumenfall unifies all models and providers to correctly work with the LiteLLM SDK.
* **Proxy server:** You can use any OpenAI-compatible SDK to connect to the LiteLLM proxy. The proxy then calls the Lumenfall API. This mode makes sense if you are already using the proxy or want to use other providers alongside Lumenfall, especially for text models.

Both modes are covered below.

## Connecting Lumenfall to LiteLLM

LiteLLM uses a **provider prefix** on the model name (e.g., `openai/gpt-image-1.5`, `vertex_ai/gemini-2.5-flash-image`) to determine which backend to route a request to. Lumenfall is not a built-in LiteLLM provider, so we need to add a prefix to make sure requests are routed to Lumenfall.

There are three integration approaches:

| Approach                     | Model format                     | Status                                                                                        |
| ---------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- |
| `openai/` prefix             | `openai/gemini-3-pro-image`      | **Recommended** - works for generation and editing ([minor limitations](#openai-recommended)) |
| `hosted_vllm/` prefix        | `hosted_vllm/gemini-3-pro-image` | Generation only - no `image_edit` support                                                     |
| Custom `lumenfall/` provider | `lumenfall/gemini-3-pro-image`   | Not yet working - [upstream bugs](#custom-lumenfall-provider)                                 |

<Note>
  The LiteLLM provider prefix (e.g., `openai/`, `hosted_vllm/`) is not the same as a [Lumenfall provider](/providers) prefix (e.g., `fal/`, `replicate/`). The LiteLLM prefix tells LiteLLM which *client* to use for the request. The Lumenfall provider prefix tells Lumenfall which *backend provider* to route to. They are independent - for example, `openai/fal/flux.2-max` uses the LiteLLM `openai/` client to send a request to Lumenfall, which then routes to fal.ai.
</Note>

This guide uses the `openai/` prefix throughout. See [Provider prefix options](#provider-prefix-options) at the end for details on the alternatives.

## Installation

```bash theme={null}
pip install litellm
```

## Configuration

Set your Lumenfall credentials once so you don't need to pass them on every call:

```python theme={null}
import litellm

litellm.api_base = "https://api.lumenfall.ai/openai/v1"
litellm.api_key = "lmnfl_your_api_key"
```

Alternatively, set environment variables before running your script:

```bash theme={null}
export OPENAI_API_BASE="https://api.lumenfall.ai/openai/v1"
export OPENAI_API_KEY="lmnfl_your_api_key"
```

<Tip>
  If using the `hosted_vllm/` prefix, set `HOSTED_VLLM_API_BASE` and `HOSTED_VLLM_API_KEY` instead.
</Tip>

## Python SDK

### Generate images

Use `litellm.image_generation()` to create images:

```python theme={null}
import litellm

response = litellm.image_generation(
    model="openai/gemini-3-pro-image",
    prompt="A capybara lounging in a hot spring at sunset",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(image_url)
```

<Info>
  Lumenfall handles parameter transformation on the backend. When you request `size="1024x1024"` for a model that uses different dimensions or even only supports different parameters such as aspect ratio, Lumenfall automatically maps it to the closest supported size.
</Info>

#### Generation options

Use `extra_body` to pass additional parameters that aren't part of LiteLLM's function signature directly to the Lumenfall API.

```python theme={null}
response = litellm.image_generation(
    model="openai/gpt-image-1.5",
    prompt="A capybara wearing a tiny top hat in a garden",
    n=1,
    size="1792x1024",  # landscape orientation
    extra_body={"response_format": "b64_json"}  # use extra_body for response_format
)
```

With the `openai/` prefix, `response_format` and `style` must go through `extra_body` because LiteLLM validates parameters against its built-in OpenAI model configs, which don't include these for non-OpenAI models. Standard parameters like `n` and `size` can be passed directly.

### Edit images

Use `litellm.image_edit()` to edit existing images:

```python theme={null}
import litellm

response = litellm.image_edit(
    model="openai/gpt-image-1.5",
    image=open("original.png", "rb"),
    prompt="Add a capybara sitting in the foreground",
    n=1,
    size="1024x1024"
)

edited_url = response.data[0].url
print(edited_url)
```

### Async support

Use `aimage_generation()` and `aimage_edit()` for async operations:

```python theme={null}
import asyncio
import litellm

async def generate_and_edit():
    # Generate an image
    gen_response = await litellm.aimage_generation(
        model="openai/gemini-3-pro-image",
        prompt="A capybara astronaut floating in space"
    )

    # Edit an existing image
    with open("original.png", "rb") as img:
        edit_response = await litellm.aimage_edit(
            model="openai/gpt-image-1.5",
            image=img,
            prompt="Make it look like a watercolor painting"
        )

    return gen_response.data[0].url, edit_response.data[0].url

gen_url, edit_url = asyncio.run(generate_and_edit())
```

### Forcing a Lumenfall provider

Lumenfall routes requests to underlying providers like OpenAI, Vertex AI, Replicate, and fal.ai. By default, Lumenfall selects the best provider automatically. You can force a specific provider by prefixing the model name with the provider slug:

```python theme={null}
response = litellm.image_generation(
    model="openai/fal/flux.2-max",  # force fal.ai provider
    prompt="A capybara swimming in a jungle river"
)
```

See [Providers](/providers) for the full list of provider slugs and how routing works.

### Per-call configuration

You can pass `api_key` and `api_base` on individual calls instead of using environment variables:

```python theme={null}
response = litellm.image_generation(
    model="openai/gemini-3-pro-image",
    prompt="A capybara in a field of sunflowers",
    api_key="lmnfl_your_api_key",
    api_base="https://api.lumenfall.ai/openai/v1"
)
```

This is useful when you need different credentials for different calls, or when you want explicit configuration without environment variables.

## Proxy server

The LiteLLM Proxy is a server that exposes an OpenAI-compatible API. You configure Lumenfall models once in a YAML file, then any OpenAI client can use them without knowing about provider prefixes or base URLs.

Add this to your `litellm_config.yaml`:

```yaml theme={null}
model_list:
  - model_name: lumenfall-gemini-image
    litellm_params:
      model: openai/gemini-3-pro-image
      api_key: os.environ/LUMENFALL_API_KEY
      api_base: https://api.lumenfall.ai/openai/v1

  - model_name: lumenfall-gpt-image
    litellm_params:
      model: openai/gpt-image-1.5
      api_key: os.environ/LUMENFALL_API_KEY
      api_base: https://api.lumenfall.ai/openai/v1

  - model_name: lumenfall-flux
    litellm_params:
      model: openai/flux.2-max
      api_key: os.environ/LUMENFALL_API_KEY
      api_base: https://api.lumenfall.ai/openai/v1
```

<Info>
  The `os.environ/LUMENFALL_API_KEY` syntax tells the proxy to read the API key from an environment variable at runtime, so you don't hardcode secrets in the config file.
</Info>

Start the proxy:

```bash theme={null}
litellm --config litellm_config.yaml
```

Then make requests through it using any OpenAI-compatible SDK. Here's an example using the OpenAI Python SDK:

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="any"  # This is your key to authenticate against the LiteLLM proxy. NOT your Lumenfall API Key.
)

response = client.images.generate(
    model="lumenfall-gemini-image",
    prompt="A capybara napping by a lake at dawn"
)
```

This works with any language or SDK that supports the OpenAI API - the proxy handles the Lumenfall routing internally.

## Provider prefix options

This section provides more detail on the trade-offs of each approach.

### openai/ (recommended)

The `openai/` prefix works for both image generation and editing. LiteLLM validates parameters against its OpenAI image configs, which blocks `response_format` and `style` for models that aren't `dall-e-2`, `dall-e-3`, or `gpt-image-*`. You can work around this by passing blocked parameters via `extra_body`:

```python theme={null}
response = litellm.image_generation(
    model="openai/gpt-image-1.5",
    prompt="A capybara reading a book under a tree",
    extra_body={"response_format": "b64_json"}  # bypass param validation
)
```

This workaround is not needed for `image_edit`, where `response_format` is supported directly.

### hosted\_vllm/ (generation only)

The `hosted_vllm/` prefix provides full parameter passthrough with no validation - useful if you need `response_format` or `style` without the `extra_body` workaround.

```python theme={null}
import os

os.environ["HOSTED_VLLM_API_BASE"] = "https://api.lumenfall.ai/openai/v1"
os.environ["HOSTED_VLLM_API_KEY"] = "lmnfl_your_api_key"

response = litellm.image_generation(
    model="hosted_vllm/gemini-3-pro-image",
    prompt="A capybara riding a bicycle through a park",
    response_format="b64_json"  # works directly, no extra_body needed
)
```

**Limitation:** LiteLLM's `hosted_vllm` provider does not support the `image_edit` endpoint. If you need image editing, use `openai/` instead.

### Custom lumenfall/ provider

LiteLLM supports [registering custom providers via a JSON file](https://docs.litellm.ai/docs/providers/openai_compatible#quick-start---add-a-json), which would allow a cleaner `lumenfall/model-name` syntax without `api_base` on every call. This would be the ideal approach, but it currently has upstream bugs for image endpoints:

* **Image generation** returns empty results (`data=[]`) despite the request succeeding upstream ([related: #18961](https://github.com/BerriAI/litellm/issues/18961), [#6513](https://github.com/BerriAI/litellm/issues/6513))
* **Image editing** fails with a provider validation error ([related: #7575](https://github.com/BerriAI/litellm/issues/7575))

These stem from [PR #18291](https://github.com/BerriAI/litellm/pull/18291) only wiring up JSON provider routing for chat completions, not image endpoints. Once resolved upstream, this would be the preferred approach. We will update this guide when that happens.

## 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>