Skip to main content
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:
ApproachModel formatStatus
openai/ prefixopenai/gemini-3-pro-imageRecommended - works for generation and editing (minor limitations)
hosted_vllm/ prefixhosted_vllm/gemini-3-pro-imageGeneration only - no image_edit support
Custom lumenfall/ providerlumenfall/gemini-3-pro-imageNot yet working - upstream bugs
The LiteLLM provider prefix (e.g., openai/, hosted_vllm/) is not the same as a Lumenfall provider 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.
This guide uses the openai/ prefix throughout. See Provider prefix options at the end for details on the alternatives.

​
Installation

pip install litellm

​
Configuration

Set your Lumenfall credentials once so you don’t need to pass them on every call: 
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: 
export OPENAI_API_BASE="https://api.lumenfall.ai/openai/v1"
export OPENAI_API_KEY="lmnfl_your_api_key"
If using the hosted_vllm/ prefix, set HOSTED_VLLM_API_BASE and HOSTED_VLLM_API_KEY instead.

​
Python SDK

​
Generate images

Use litellm.image_generation() to create images: 
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)
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.

​
Generation options

Use extra_body to pass additional parameters that aren’t part of LiteLLM’s function signature directly to the Lumenfall API. 
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: 
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: 
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: 
response = litellm.image_generation(
    model="openai/fal/flux.2-max",  # force fal.ai provider
    prompt="A capybara swimming in a jungle river"
)
See 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: 
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: 
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
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.
Start the proxy: 
litellm --config litellm_config.yaml
Then make requests through it using any OpenAI-compatible SDK. Here’s an example using the OpenAI Python SDK: 
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. 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: 
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. 
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, 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, #6513)
  • Image editing fails with a provider validation error (related: #7575)
These stem from PR #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

API Reference

Explore the full API documentation.

Available Models

See all available image generation models.