# Image CDN

All image URLs returned by the API are served through our CDN with automatic optimization. Images are compressed and converted to modern formats (WebP/AVIF) based on browser support.

## Default Behavior

Images are returned at **original dimensions** (capped at 2048px max) with automatic format conversion. Use presets to request specific sizes.

## Presets

Append a preset query parameter to any image URL for consistent sizing:

| Preset | Dimensions | Use Case |
|  --- | --- | --- |
| `thumb` | 150×150 | Thumbnails, small icons |
| `medium` | 600×600 | Listings, card images |
| `large` | 1200×1200 | Detail views, galleries |
| `hero` | 1920×800 | Hero banners, headers |
| `avatar` | 200×200 | User avatars, profile pictures |
| `card` | 400×300 | Product cards, previews |


### Example


```
# Original (max 2048px, auto format)
https://cdn.example.com/images/photo.png

# Thumbnail
https://cdn.example.com/images/photo.png?preset=thumb

# Medium for listings
https://cdn.example.com/images/photo.png?preset=medium

# High quality large
https://cdn.example.com/images/photo.png?preset=large&q=95
```

## Query Parameters

| Parameter | Type | Default | Description |
|  --- | --- | --- | --- |
| `preset` | string | - | Resize preset (see table above) |
| `q` | number | 80 | Quality (1-100) |
| `f` | string | `auto` | Output format |
| `fit` | string | `inside` | Resize fit mode |


### Format Options (`f`)

| Value | Description |
|  --- | --- |
| `auto` | Best format based on browser support (recommended) |
| `jpeg` | Force JPEG |
| `webp` | Force WebP |
| `png` | Force PNG (preserves transparency) |
| `avif` | Force AVIF (best compression) |


### Fit Options (`fit`)

| Value | Description |
|  --- | --- |
| `inside` | Fit within dimensions, maintain aspect ratio (default) |
| `cover` | Cover dimensions, crop overflow |
| `contain` | Fit within dimensions with padding |
| `fill` | Stretch to exact dimensions |


## Supported Formats

**Input:** JPEG, PNG, WebP, GIF (animations preserved), AVIF

**Output:** Auto-selected based on browser support (WebP, AVIF, JPEG, PNG)

## Error Codes

| HTTP Code | Description |
|  --- | --- |
| 200 | Success |
| 404 | Image not found |
| 5xx | Processing error (falls back to original) |


> **Note:** Invalid parameters are clamped to valid ranges automatically.