gh-jezweb-claude-skills-skills-cloudflare-images/references/variants-guide.md

Variants Guide - Named vs Flexible

Complete guide to Cloudflare Images variants.

---

What Are Variants?

Variants define how images should be resized and transformed for different use cases.

Two Types:

1. Named Variants - Predefined transformations (up to 100)
2. Flexible Variants - Dynamic transformations (unlimited)

---

Named Variants

Overview

Pre-configured transformations that apply consistently across all images.

Limits: 100 variants per account Use with: Public and private images (signed URLs compatible)

Creating Named Variants

Via API:

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "thumbnail",
    "options": {
      "fit": "cover",
      "width": 300,
      "height": 300,
      "metadata": "none"
    },
    "neverRequireSignedURLs": false
  }'

Via Dashboard:

1. Dashboard → Images → Variants
2. Create variant
3. Set dimensions, fit mode, metadata handling

Using Named Variants

URL Format:

https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>

Example:

<img src="https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/abc123/thumbnail" />

Common Named Variants

const presets = {
  thumbnail: { width: 300, height: 300, fit: 'cover' },
  avatar: { width: 200, height: 200, fit: 'cover' },
  small: { width: 480, fit: 'scale-down' },
  medium: { width: 768, fit: 'scale-down' },
  large: { width: 1920, fit: 'scale-down' },
  hero: { width: 1920, height: 1080, fit: 'cover' },
  product: { width: 800, height: 800, fit: 'contain' }
};

When to Use Named Variants

✅ Use when:

• Consistent sizes needed across app
• Private images (signed URLs required)
• Predictable, simple URLs
• Team collaboration (shared definitions)

❌ Don't use when:

• Need dynamic sizing per request
• Rapid prototyping with many sizes
• Approaching 100-variant limit

---

Flexible Variants

Overview

Dynamic transformations using params directly in URL.

Limits: Unlimited transformations Use with: Public images only (signed URLs NOT compatible)

Enabling Flexible Variants

One-time setup per account:

curl --request PATCH \
  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{"flexible_variants": true}'

Using Flexible Variants

URL Format:

https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<TRANSFORMATION_PARAMS>

Examples:

<!-- Basic resize -->
<img src="https://imagedelivery.net/HASH/ID/w=400,h=300" />

<!-- With quality and format -->
<img src="https://imagedelivery.net/HASH/ID/w=800,q=85,f=auto" />

<!-- Sharpen and crop -->
<img src="https://imagedelivery.net/HASH/ID/w=600,h=600,fit=cover,sharpen=3" />

<!-- Blur effect -->
<img src="https://imagedelivery.net/HASH/ID/w=500,blur=20,q=50" />

Available Parameters

Same as transformation options:

• w, h - Width, height
• fit - Fit mode (scale-down, contain, cover, crop, pad)
• q - Quality (1-100)
• f - Format (auto, avif, webp, jpeg)
• gravity - Crop focal point (auto, face, left, right, top, bottom)
• blur, sharpen, brightness, contrast, gamma
• rotate, flip
• dpr - Device pixel ratio
• metadata - EXIF handling (none, copyright, keep)
• anim - Preserve animation (true/false)

When to Use Flexible Variants

✅ Use when:

• Dynamic sizing needs
• Public images only
• Rapid prototyping
• User-controlled transformations

❌ Don't use when:

• Need signed URLs (private images)
• Want consistent, predictable URLs
• Team needs shared definitions

---

Comparison Table

Feature	Named Variants	Flexible Variants
Limit	100 per account	Unlimited
Signed URLs	✅ Compatible	❌ Not compatible
URL Format	/thumbnail	/w=400,h=300,fit=cover
URL Length	Short, clean	Longer, dynamic
Setup	Create variants first	Enable once, use anywhere
Use Case	Consistent sizes	Dynamic sizing
Team Sharing	Shared definitions	Ad-hoc transformations
Private Images	✅ Supported	❌ Public only

---

Combining Both

You can use both types in the same account:

<!-- Named variant for avatar (private image, signed URL) -->
<img src="https://imagedelivery.net/HASH/PRIVATE_ID/avatar?exp=123&sig=abc" />

<!-- Flexible variant for public thumbnail -->
<img src="https://imagedelivery.net/HASH/PUBLIC_ID/w=300,h=300,fit=cover" />

---

Best Practices

For Named Variants

1. Create core sizes first: thumbnail, small, medium, large
2. Use descriptive names: product-square, hero-wide, avatar-round
3. Document variant usage: Share definitions with team
4. Set consistent quality: 85 for photos, 90+ for graphics
5. Use metadata: none: Unless specific need to preserve EXIF

For Flexible Variants

1. Always use f=auto: Optimal format for each browser
2. Limit dynamic range: Don't allow arbitrary sizes (performance)
3. Cache popular sizes: Create named variants for common sizes
4. URL-encode params: Especially if using special characters
5. Public images only: Remember signed URL incompatibility

---

Migration Strategies

From Flexible to Named

If approaching flexibility limits or need signed URLs:

// Analyze usage logs
const popularSizes = analyzeImageRequests();
// { w=300,h=300: 50000, w=800,h=600: 30000, ... }

// Create named variants for top sizes
for (const [params, count] of Object.entries(popularSizes)) {
  if (count > 10000) {
    await createVariant(getNameForParams(params), parseParams(params));
  }
}

// Update URLs from flexible to named
// Before: /w=300,h=300,fit=cover
// After: /thumbnail

From Named to Flexible

If need more than 100 variants:

1. Enable flexible variants
2. Gradually migrate to dynamic params
3. Keep popular sizes as named variants
4. Use flexible for long-tail sizes

---

Cost Considerations

Named Variants:

• Cached at edge (fast delivery)
• Predictable bandwidth
• Good for high traffic

Flexible Variants:

• Also cached at edge
• More cache keys (potentially)
• Good for diverse sizing needs

Both: First transformation billable, subsequent cached requests free

---

Official Documentation

• Create Variants: https://developers.cloudflare.com/images/manage-images/create-variants/
• Enable Flexible Variants: https://developers.cloudflare.com/images/manage-images/enable-flexible-variants/