URL Format & Parameters
Two URL Styles
PreviewProxy supports two request styles: path-style and query-style.
Path-style
Parameters are embedded directly in the URL path, before the image URL:
http://your-host/<params>/<image_url>
http://your-host/w=400,h=300,format=webp/https://example.com/image.jpg
Multiple parameters are separated by commas. The image URL follows after a /.
If no transforms are needed, the params segment can be omitted entirely:
http://your-host/https://example.com/image.jpg
Query-style
Parameters are passed as standard HTTP query string params to the /proxy endpoint:
http://your-host/proxy?url=<image_url>¶m=value&...
http://your-host/proxy?url=https://example.com/image.jpg&w=400&h=300&format=webp
Path Parameter Syntax
Path-style supports three equivalent syntaxes for each parameter. All can be freely mixed in the same request:
| Syntax | Example | Notes |
|---|---|---|
key=value | w=400,h=300 | Same keys as query-style |
key:value | w:400,h:300 | Alternative separator |
| Shorthand | 400x300, q80, r90 | Compact notation for common params |
Shorthand tokens
| Shorthand | Equivalent | Description |
|---|---|---|
WxH | w=W,h=H | Width and height together (e.g. 300x200) |
qN | q=N | Quality (e.g. q80) |
rN | rotate=N | Rotation (e.g. r90) |
contain | fit=contain | Fit mode |
cover | fit=cover | Fit mode |
crop | fit=crop | Fit mode |
webp | format=webp | Output format (works for all formats) |
fliph | flip=h | Horizontal flip |
flipv | flip=v | Vertical flip |
grayscale | grayscale=1 | Enable grayscale |
gif_anim | gif_anim=all | Enable animated GIF (all frames) |
gif_af | gif_af=1 | Apply transforms to frame range only |
Mixed syntax example
These three requests are equivalent:
/300x200,webp,q80/https://example.com/image.jpg
/w=300,h=200,format=webp,q=80/https://example.com/image.jpg
/w:300,h:200,format:webp,q:80/https://example.com/image.jpg
Supported Source URL Schemes
| Scheme | Example |
|---|---|
| HTTP/HTTPS | https://example.com/image.jpg |
| S3 | s3:/path/to/image.jpg |
| Local filesystem | local:/path/to/image.jpg |
| Alias | mycdn:/path/to/image.jpg |
Percent-encoding is supported in the image URL segment. For example, spaces and special characters in filenames can be encoded as %20, %2B, etc.
Parameters Reference
| Param | Type | Description |
|---|---|---|
w | integer | Output width in pixels (max 8192) |
h | integer | Output height in pixels (max 8192) |
fit | string | Resize mode: contain, cover, or crop (default: contain) |
format | string | Output format: webp, jpeg, png, avif, gif, bmp, tiff, ico, jxl |
q | integer | Quality 1-100 for JPEG and WebP (default: encoder default) |
rotate | integer | Clockwise rotation: 90, 180, or 270 |
flip | string | Flip axis: h (horizontal) or v (vertical) |
blur | float | Gaussian blur radius 0-100 |
grayscale | bool | Convert to grayscale: true or 1 |
bright | integer | Brightness adjustment -255 to 255 |
contrast | integer | Contrast adjustment -255 to 255 |
wm | string | Watermark image URL (supports http, https, s3:, local:) |
sig | string | HMAC-SHA256 signature (required when HMAC_KEY is set) |
gif_anim | string | GIF frame range: all, N, N-M, -N (last N frames) |
gif_af | bool | Apply transforms to gif_anim range only, return all frames |
seek | string | Video thumbnail seek: N (seconds), Nr (ratio 0-1), auto (middle) |
Examples
Resize to fixed dimensions (path-style)
/w=800,h=600/https://example.com/photo.jpg
Convert to WebP with quality (path-style shorthand)
/webp,q85/https://example.com/photo.jpg
Resize, convert format, and set quality (mixed shorthand)
/400x300,webp,q80/https://example.com/photo.jpg
Resize with cover fit (path-style)
/w=400,h=400,fit=cover/https://example.com/photo.jpg
Rotate and flip (path-style)
/rotate=90,flip=h/https://example.com/photo.jpg
Apply blur and grayscale (path-style)
/blur=3,grayscale=1/https://example.com/photo.jpg
Brightness and contrast adjustment (path-style)
/bright=30,contrast=20/https://example.com/photo.jpg
Overlay a watermark (path-style)
/wm=https://example.com/watermark.png/https://example.com/photo.jpg
Query-style equivalent
/proxy?url=https://example.com/photo.jpg&w=400&h=300&format=webp&q=80
S3 source image (path-style)
/w=400,format=webp/s3:/images/photo.jpg
All transforms combined (path-style shorthand)
/800x600,cover,webp,q85,blur:1,bright:10/https://example.com/photo.jpg
Parameters can be specified in any order. Only include the parameters you need - unspecified parameters use their defaults or are skipped entirely.
The sig parameter is required when HMAC_KEY is configured on the server. Requests without a valid signature will be rejected. See the security documentation for details on generating signatures.