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.
Parameter support
When you make a request, Lumenfall handles parameters in four ways, from weakest to strongest support:
| Mode | What Happens | Example |
|---|
| Passthrough | Passed as-is; provider may ignore if unsupported | style |
| 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 |
Universal features
These features are normalized across all models, giving you consistent behavior regardless of which provider handles your request:
| Feature | Description |
|---|
response_format | Choose url or b64_json for any model |
output_format | Choose output format: png, jpeg, webp |
output_compression | Control compression level for lossy formats |
n | Request multiple images regardless of provider limits |
When a model natively supports a feature, Lumenfall uses the native capability. Emulation only kicks in when needed.
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 URLs
response = client.images.generate(
model="gemini-3-pro-image",
prompt="A mountain landscape",
response_format="b64_json"
)
image_data = response.data[0].b64_json
output_compression to control quality for lossy formats.
Supported formats: png, jpeg, webp
response = client.images.generate(
model="gemini-3-pro-image",
prompt="A mountain landscape",
output_format="webp",
output_compression=85 # 0-100
)
Error normalization
Each provider returns errors in different formats. Lumenfall transforms all provider errors into the standard OpenAI error format, so you can handle errors consistently.
| Provider Error | Normalized To |
|---|
| Content policy violation | 400 content_policy_violation |
| Rate limit exceeded | 429 rate_limit_exceeded |
| Invalid image format | 400 invalid_request_error |
| Model not found | 404 model_not_found |
| Authentication failed | 401 invalid_api_key |
Why this matters
- Write once, switch freely - Change models without rewriting code
- No provider lock-in - Your integration works with any provider
- Predictable behavior - Same parameters, same results, regardless of which provider handles the request
Next steps
