Skip to main content
Lumenfall automatically routes your requests to the best available AI provider based on the model you specify and provider availability. Routing is managed by Lumenfall to ensure optimal reliability, performance, and cost.

​
How routing works

When you make a request to Lumenfall:
  1. Model matching - Lumenfall resolves your model to available providers
  2. Provider selection - A provider is selected from the healthy provider pool
  3. Execution - Your request is sent to the selected provider
  4. Fallback - If the provider fails, the request is retried with another provider
Request → Model Matching → Provider Selection → Execute → Response
                                    ↓
                              (on failure)
                                    ↓
                            Next Provider → Execute → Response

​
Model aliases

Some models can be requested using alternative names. For example, a model might have both a versioned name and a shorter alias that always points to the latest version. You can find available aliases on each model’s page in the model catalog.

​
Load balancing

Many models are available from multiple providers. For each model, Lumenfall distributes traffic across providers that offer competitive pricing, good performance, and reliable availability. Which provider serves your request may change on every request. This is intentional - it allows Lumenfall to optimize for cost and reliability across your usage. If you need a specific provider, see Forcing a specific provider.

​
Fallback

When a provider fails, Lumenfall automatically retries your request with another provider. This happens transparently - you receive a successful response if any available provider succeeds. Lumenfall monitors provider health in real-time. If a provider experiences issues, it is automatically removed from the default provider pool. Requests are then distributed only among healthy providers. Unhealthy providers are not abandoned entirely. If all healthy providers fail for a request, Lumenfall will attempt the unhealthy providers as a last resort before returning an error.

​
Forcing a specific provider

While routing is managed by Lumenfall, you can bypass it and force a specific provider by prefixing the model name with a provider slug: 
gemini-3-pro-image → vertex/gemini-3-pro-image

curl https://api.lumenfall.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vertex/gemini-3-pro-image",
    "prompt": "A mountain landscape"
  }'

​
Viewing routing decisions

Each response includes headers showing which provider handled the request: 
X-Lumenfall-Provider: vertex
X-Lumenfall-Model: gemini-3-pro-image
X-Lumenfall-Provider-Model: gemini-3-pro-image-preview
X-Request-Id: req_abc123
HeaderDescription
X-Lumenfall-ProviderProvider slug that served the request
X-Lumenfall-ModelLumenfall model slug you requested
X-Lumenfall-Provider-ModelActual model ID sent to the provider
X-Request-IdUnique request identifier
For detailed routing information including fallback attempts, latency breakdown, and cost - see the Requests page in your dashboard.