Assets API Reference

Image Proxy

The image proxy provides on-the-fly image resizing, cropping, and format conversion. It fetches an external image, processes it according to the specified options, and returns the result with appropriate cache headers.

Base URL

https://assets.api.easelive.tv

Endpoint

GET /api/v2/imgproxy/:accountId/:options?url=<imageUrl>

Path parameters:

• accountId — Your Ease Live account name (lowercase alphanumeric and hyphens)
• options — Comma-separated processing options in key=value format

Query parameters:

• url (required) — The source image URL (must be http or https)

Options

Option	Type	Values	Default	Description
w	number	50, 100–2000 (multiples of 100)	—	Output width in pixels
h	number	50, 100–2000 (multiples of 100)	—	Output height in pixels
fit	string	scaledown, scale, fill, fit, crop, face, face-and-shoulders	scaledown	Resize mode (see below)
fillPosition	string	top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right	—	Anchor point for fill and fit modes
q	number	10–100 (multiples of 10)	85	Output quality (JPEG/WebP)
f	string	jpg, jpeg, png, gif, webp	source format	Output format
padding	number	1–5 (max 1 decimal place)	1.8 (face) / 2.8 (face-and-shoulders)	Zoom multiplier for face crop region. Only applies to face and face-and-shoulders modes

TIP

The fillPosition is specified inline with fit using a colon separator: fit=fill:center

Fit modes

Mode	Description
scaledown	Fit within the given dimensions without enlarging. This is the default.
scale	Fit within the given dimensions, may enlarge.
fill	Cover the given dimensions, cropping excess. Use fillPosition to control the anchor.
fit	Fit within the given dimensions, padding if necessary. Use fillPosition to control alignment.
crop	Center crop to the given dimensions without resizing.
face	Detect a face and crop tightly around it (1.8× face height by default). Falls back to attention-based crop if no face is detected.
face-and-shoulders	Detect a face and crop to include shoulders (2.8× face height by default). Falls back to face sizing if the region extends past the image, or to attention-based crop if no face is detected.

Face-aware cropping

The face and face-and-shoulders fit modes use face detection to intelligently crop images around a person's face. This is useful for generating profile thumbnails or portrait crops from arbitrary photos.

How it works:

1. The image is analyzed to detect faces using a landmark model (68-point).
2. If multiple faces are found, the one closest to the image center is chosen.
3. A crop region is calculated relative to the detected face height — 1.8× for face and 2.8× for face-and-shoulders.
4. The region is centered on the nose landmark, then adjusted to fit the target aspect ratio.
5. If no face is detected (or the image is animated), it falls back to an attention-based smart crop.

The padding option:

Use the padding option to override the default crop multiplier. A value of 1 crops very tightly around the face, while 5 includes much more of the surrounding area. Accepts one decimal place (e.g., 1.5, 2.3).

WARNING

Face detection is skipped for animated images (GIFs, animated WebPs). These will fall back to attention-based cropping.

Response

Headers:

Header	Description
Content-Type	Output image MIME type (image/webp, image/png, etc.)
Cache-Control	public, max-age=5184000, s-maxage=86400 on success; public, max-age=300 on error
X-Cache	HIT if served from cache, MISS if freshly processed

Status codes:

Code	Description
200	Success
403	Domain not allowed or private/internal IP detected
422	Validation error (invalid options or URL)
502	Failed to process the upstream image
504	Upstream image fetch timed out

Examples

Resize to 200px width, convert to WebP — Open example

GET /api/v2/imgproxy/my-account/w=200,f=webp?url=https://download.easelive.tv/examples/ease-live-logo.png

Resize to 700x200, fill from center, 70% quality — Open example

GET /api/v2/imgproxy/my-account/w=700,h=200,fit=fill:center,q=70?url=https://download.easelive.tv/examples/ease-live-logo.png

Small 50px thumbnail as PNG — Open example

GET /api/v2/imgproxy/my-account/w=50,f=png?url=https://download.easelive.tv/examples/ease-live-logo.png

Face crop to 400x400 — Open example

GET /api/v2/imgproxy/my-account/w=400,h=400,fit=face?url=https://download.easelive.tv/docs/assets/player.png

Face and shoulders crop to 400x500 — Open example

GET /api/v2/imgproxy/my-account/w=400,h=500,fit=face-and-shoulders?url=https://download.easelive.tv/docs/assets/player.png

Face crop with custom padding (tighter crop) — Open example

GET /api/v2/imgproxy/my-account/w=300,h=300,fit=face,padding=1.2?url=https://download.easelive.tv/docs/assets/player.png