Unified Model Behavior

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

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`, `gif`, `webp`, `avif`
`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.

response_format

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 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_format and output_compression

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.

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A mountain landscape",
    output_format="webp",
    output_compression=85  # 1-100
)

Size, aspect ratio, and resolution

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.

Parameters

Parameter	Format	Example	What it controls
`size`	`"WxH"` pixels	`"1920x1080"`	Shape and scale (most specific)
`aspect_ratio`	`"W:H"` ratio	`"16:9"`, `"8:1"`	Shape only
`resolution`	Scale tier	`"1K"`, `"4K"`	Scale only

All three are optional. When omitted, the model uses its defaults.

How parameters interact

When you provide multiple parameters, more specific inputs take priority:

size is the most specific — it determines both shape and scale. If you also pass aspect_ratio or resolution, they are ignored.
aspect_ratio + resolution — resolved independently. Shape is matched against the model’s supported ratios; scale is matched against supported tiers.
aspect_ratio alone — determines shape. Scale is left to the model’s default.
resolution alone — determines scale without changing shape (useful for upscaling).

# Shape from aspect ratio, scale from resolution (independent)
response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A mountain landscape",
    aspect_ratio="16:9",
    resolution="4K"
)

# Explicit pixel dimensions (overrides both aspect_ratio and resolution)
response = client.images.generate(
    model="flux-2-pro",
    prompt="A mountain landscape",
    size="1920x1080"
)

Shape matching

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.

Scale matching

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:

Format	Values	Used by
K tiers	`"0.5K"`, `"1K"`, `"2K"`, `"4K"`	Gemini, Vertex
Megapixel tiers	`"0.25"`, `"1"`	FLUX on Replicate

Dimension clamping

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 2048x2048
response = client.images.generate(
    model="flux-2-pro",
    prompt="A mountain landscape",
    size="4096x4096"
)

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

Getting started

Core concepts

Replay

Dashboard

Client libraries

Integrations

Unified Model Behavior

Parameter support

Universal features

response_format

output_format and output_compression

Size, aspect ratio, and resolution

Parameters

How parameters interact

Shape matching

Scale matching

Dimension clamping

Error normalization

Why this matters

Next steps

Available Models

Routing

​Parameter support

​Universal features

​response_format

​output_format and output_compression

​Size, aspect ratio, and resolution

​Parameters

​How parameters interact

​Shape matching

​Scale matching

​Dimension clamping

​Error normalization

​Why this matters

​Next steps

Available Models

Routing

Parameter support

Universal features

response_format

output_format and output_compression

Size, aspect ratio, and resolution

Parameters

How parameters interact

Shape matching

Scale matching

Dimension clamping

Error normalization

Why this matters

Next steps