Variants
A variant is a transformed version of an asset's image content, such as a resized thumbnail, cropped avatar, or WebP conversion.
A variant is composed of:
- Attributes: Properties of the output, such as its
height,width, andformat. - Transformation: The operations applied to the original variant, such as
rotate: 90orblur: 2.
Original Variant
The original variant is the image Konifer stores during the Store Assets request. Konifer creates every other variant from this image.
Preprocessing can resize or convert the supplied content before Konifer stores it as the original variant. Without preprocessing, the original variant contains the supplied image unchanged.
For example, one stored cow photo can supply a small avatar without replacing its original. Both images belong to the same asset; the thumbnail is a generated variant.


See Image Transformation for the resizing behavior behind this thumbnail.
Variant Types
Konifer generates variants in two ways:
- Eager variant generation
- On-demand variant generation
Eager Variant Generation
Use eager generation when you know which variants an application will need before an upload arrives. Konifer queues these variants during upload and returns the Store Asset response without waiting for them to finish.
Eager variants can only be defined using variant profiles.
Best-effort
Eager generation is asynchronous and best-effort. Konifer does not reschedule a failed or interrupted eager task. If a client later requests the missing variant, Konifer generates it on demand.
Configuration
Eager variants are defined in your path configuration. The following configuration generates two different variants.
variant-profiles {
small {
height = 50
width = 50
fit = fill
format = png
}
medium {
height = 100
width = 100
fit = fill
format = png
}
}
paths {
"/users/**" {
transform {
eager-variants = [
small,
medium
]
}
}
}
On-demand Variant Generation
A Fetch Asset request with transformation parameters such as width, height, or gravity generates a variant
from the original
variant. Konifer caches the result in the configured object store. See Variant Caching for details.
On-demand Variant Generation Modes
By default, clients can request any supported on-demand transformation. Set
transform.on-demand-variant.mode in path configuration to restrict this behavior.
enabled(default): Clients can supply a profile or individual transformation parameters.profile_only: Clients must name a variant profile for transformed content. Explicit parameters must resolve to that profile's transformation. Profiles that omitformatallow format negotiation.disabled: Clients cannot request arbitrary on-demand variants. A request for a configured eager variant can still generate that variant when its eager task has not completed.
Transformation Limits
Transformation limits protect Konifer from generating unexpectedly large images. They apply per path to preprocessing, eager variants, and on-demand variants.
paths {
"/**" {
transform {
limits {
max-width = 8192
max-height = 8192
max-pixels = 20MP
}
}
}
}
max-widthlimits the final output width.max-heightlimits the final output height.max-pixelslimits the final output width multiplied by its height.
Pixel counts can be written as exact integers or with the decimal units P, KP, MP, and GP. For example, 20MP
means 20,000,000 pixels and 8.2944MP means 8,294,400 pixels.
The final dimensions include padding and reflect rotation. An original variant stored without preprocessing is not subject to transformation limits because no transformation is being generated.
Konifer rejects configured preprocessing and eager variants during configuration loading when the known dimensions
already exceed a limit. Transformations with a missing dimension or automatic rotation can depend on the source image,
so Konifer completes validation after normalization at runtime. An invalid on-demand or preprocessing transformation
returns 400 Bad Request; eager generation remains best-effort and does not create the invalid variant.
The clamp-width and clamp-height properties inside transform.preprocessing are resize instructions. The
properties inside transform.limits are safeguards that reject transformed output exceeding the configured limits.
Supplied images have a separate path-level limits block, which is checked before preprocessing. See
Supplied content limits.
See the configuration reference for the complete property list and defaults.
Deleting an Asset
Deleting an asset also deletes each of its variants.