How Lumenfall ensures consistent behavior across all models and providers
Each AI provider has its own API format, parameter names, and supported features. Lumenfall abstracts these differences for you, so you can write code once and have it work consistently across all models and providers.
When you make a request, Lumenfall handles parameters in four ways, from weakest to strongest support:
Mode
What Happens
Example
Passthrough
Passed as-is to upstream; provider may ignore if unsupported
style, quality, guidance_scale
Renamed
Field name mapped to provider’s expected name for this model
prompt
Converted
Value transformed to provider’s format for this model
size
Emulated
Behavior emulated even if model doesn’t support it
n, response_format, output_format, output_compression
Provider-specific parameters: Any parameters not recognized by Lumenfall are passed through to the upstream provider. This lets you use provider-specific features without waiting for explicit Lumenfall support. See Passing additional parameters for examples.
Request images as URLs or base64-encoded data.When you request url but the provider returns base64, we temporarily store the image on our servers and return a URL valid for 60 minutes. The image is deleted after expiry with no copies retained. This applies regardless of your data retention settings.Supported values: url, b64_json
# Get base64 data even if provider returns URLsresponse = client.images.generate( model="gemini-3-pro-image", prompt="A mountain landscape", response_format="b64_json")image_data = response.data[0].b64_json
Specify the image format you want. If the provider generates a different format, Lumenfall converts the image for you. Use output_compression to control quality for lossy formats.Supported formats: png, jpeg, gif, webp, avif
Lumenfall supports more output formats than OpenAI’s API. In addition to png, jpeg, and webp, we also support gif and avif. Note that AVIF conversion is limited to images up to 1,600 pixels; larger images will fall back to the original format.
Control the shape and scale of generated images using three parameters. Lumenfall translates these into whatever format each provider expects — pixel dimensions, aspect ratio strings, resolution tiers, or preset sizes.
Always use size, aspect_ratio, and resolution instead of provider-specific parameters like image_size, width/height, or imageSize. Since Lumenfall may route your request to different providers, these three universal parameters ensure consistent behavior regardless of which provider handles it.
When the exact aspect ratio you request isn’t supported by the model, Lumenfall finds the closest match by comparing the numeric ratio values. For example, requesting "7:1" on a model that supports ["4:1", "8:1"] will match to "8:1".If you request an exact ratio the model supports, it’s used as-is with no transformation.
Resolution tiers are matched against the model’s supported values. If you request a tier the model doesn’t support, Lumenfall picks the closest available tier rather than silently dropping your preference. For example, requesting "8K" on a model that supports ["1K", "4K"] will match to "4K".Two tier formats exist across providers — Lumenfall handles both transparently:
When a model accepts pixel dimensions with constraints (min/max width, height, or megapixels), Lumenfall clamps your dimensions to fit within the model’s bounds while preserving the aspect ratio when possible.
# If the model's max is 2048x2048, this is clamped to 2048x2048response = client.images.generate( model="flux-2-pro", prompt="A mountain landscape", size="4096x4096")
Each provider returns errors in different formats. Lumenfall transforms all provider errors into the standard OpenAI error format, so you can handle errors consistently.
