Variants

Variants allow automatic transformations of property values when accessed via the API. Create variants on string or blob properties to generate transformed versions on-demand.

How Variants Work

1. Create a variant on a property (string or blob)
2. Define one or more transformation steps
3. Access the transformed value using $variantName syntax
4. Results are cached for performance

Available Transformers

Each transformer has a unique ID, an input type, and an output type. Type 1 means string (text) and type 10 means blob (binary). When chaining transformers, the output type of one step must match the input type of the next.

Transformer	ID	Input → Output	Property Type	Description
Translate	2a0dfa7f-1eac-483e-81c7-970e613e2320	string → string	string	AI translation of text between languages (from, to)
Image Resize	1b26c21a-7397-4492-9cdd-386fa2f929c0	blob → blob	blob	Resize image (toMimeFormat, maxWidth, maxHeight, resizeMode)
Vision AI Image Description	04efe645-c715-42cc-b2ab-f6c00d959360	blob → string	blob	AI-generated text description of an image
Image Grayscale	3cb5e811-f891-4587-8d4b-1d5e2d2bf962	blob → blob	blob	Convert image to grayscale (toMimeFormat)
EXIF Location Extraction	33fb8b2e-ab90-4b52-8ba3-a44d71910150	blob → string	blob	Extract GPS location from image EXIF metadata as text

For LLMs and API automation

The transformer ID is the stable identifier used when configuring variants programmatically. Names and descriptions may change, but IDs do not.

Creating Variants

In the Developer Portal

1. Navigate to your collection
2. Select a string or blob property
3. Click Add Variant
4. Name your variant (e.g., "thumbnail", "spanish")
5. Add transformation steps
6. Save

Chaining Transformers

Each variant can have multiple transformation steps applied in sequence:

Original Image → Resize (200x200) → Grayscale → Output

This allows complex transformations like "resize then convert to grayscale" in a single variant.

Accessing Variants

Blob Properties (Images/Files)

Append the variant name to the blob field URL:

GET /api/products/{item-id}/image$thumbnail

Examples:

/api/products/abc-123/image$thumbnail      # Resized thumbnail
/api/products/abc-123/photo$grayscale      # Grayscale version
/api/products/abc-123/image$small          # Custom "small" variant

String Properties (Text)

Use the select parameter with the variant name:

GET /api/articles/{item-id}?select=description$spanish

Examples:

?select=content$spanish                # Translated to Spanish
?select=description$summary            # Summarized version
?select=title,content$translated       # Multiple fields with variant

Multiple Variants

Request multiple variants in a single call:

GET /api/articles/abc-123?select=title,content$summary,content$spanish

Returns the title plus both a summarized and translated version of content.

Use Cases

Image Transformations

Use Case	Example Variant
Thumbnails	Resize to 150x150
Responsive images	Multiple size variants (small, medium, large)
Optimized formats	Convert to WebP
Grayscale previews	Remove color

Text Transformations

Use Case	Example Variant
Multilingual content	Translate to Spanish, French, German
Content previews	Summarize long articles
Accessibility	Generate image descriptions

Benefits

Benefit	Description
No code required	Configure in the portal, no functions needed
Cached results	Transformed content is cached automatically
On-demand	Only generated when first requested
Scalable	Runs on serverless infrastructure

Example: Product Images

Create variants for different image sizes:

Variant Name	Transformation
thumbnail	Resize to 100x100
card	Resize to 300x200
detail	Resize to 800x600
hero	Resize to 1920x1080

Access them:

/api/products/abc-123/image              # Original
/api/products/abc-123/image$thumbnail    # 100x100
/api/products/abc-123/image$card         # 300x200
/api/products/abc-123/image$detail       # 800x600

Example: Multilingual Content

Create translation variants for an article's description:

Variant Name	Transformation
spanish	Translate to Spanish
french	Translate to French
german	Translate to German

Access them:

?select=description                  # Original language
?select=description$spanish          # Spanish translation
?select=description$french           # French translation