Small Pics URL API: A Practical Guide
Small Pics is a URL-first image service. That means there’s no SDK to install, no build step, and no config file. You construct a URL, and Small Pics returns an optimized image. This post walks through the API from the basics to more advanced features.
How it works
Every Small Pics URL follows the same pattern:
https://your-domain.smallpics.io/image.jpg?w=800&h=600&fit=cover&fm=webpThe path is your origin image. The query parameters are your transforms. Small Pics processes the image on the first request, caches it at the edge, and serves it from cache on subsequent requests.
Resizing: w and h
The most common operation. Set the width, height, or both.
<!-- Width only (height scales proportionally) -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800" />
<!-- Both dimensions -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&h=600" />For retina displays, use dpr to multiply the dimensions automatically:
<!-- Renders at 1600x1200 for 2x screens -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&h=600&dpr=2" />dpr accepts values from 1 to 8.
Fit modes: fit
When you specify both w and h, fit controls how the image fills those dimensions.
| Value | Behavior |
|---|---|
contain | Fits inside the box, preserving aspect ratio (default) |
max | Like contain, but never upscales |
cover | Fills the box, cropping the overflow |
crop | Same as cover |
fill | Stretches to fit, may upscale |
fill-max | Like fill, but never upscales |
stretch | Ignores aspect ratio, stretches to exact dimensions |
You can also use crop-x%-y% to control the crop focal point:
<!-- Crop with focus on the top-right -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&h=600&fit=crop-100%-0%" />Format: fm
Small Pics supports AVIF, WebP, JPEG, Progressive JPEG, PNG, GIF, and JPEG XL.
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&fm=avif" />| Value | Format |
|---|---|
avif | AVIF (default) |
webp | WebP |
jpg | JPEG |
pjpg | Progressive JPEG |
png | PNG |
gif | GIF |
jxl | JPEG XL |
Quality: q
Controls compression quality on a 0-100 scale. Default is 90.
<!-- Lower quality, smaller file -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&fm=webp&q=75" />For most photos, 70-80 is a good balance between quality and file size. Go lower for thumbnails, higher for hero images.
Cropping: crop
For precise control, use crop to extract a region before resizing. The format is width,height,x,y:
<!-- Extract a 500x500 region starting at coordinates 100,200 -->
<img src="https://your-domain.smallpics.io/photo.jpg?crop=500,500,100,200&w=400" />This crops first, then applies any w/h resize.
Rotation and flipping: or and flip
Rotate in 90-degree increments, or set auto to respect EXIF orientation (the default):
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&or=90" />Flip horizontally, vertically, or both:
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&flip=h" />Image adjustments: bri, con, gam, sharp
Fine-tune the output with brightness, contrast, gamma, and sharpness.
<!-- Slightly brighter and sharper -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&bri=10&sharp=30" />| Parameter | Range | Default |
|---|---|---|
bri | -100 to 100 | 0 |
con | -100 to 100 | 0 |
gam | 0.1 to 9.99 | - |
sharp | 0 to 100 | - |
Background color: bg
When using contain or fill fit modes, the background is visible. Set it with bg:
<!-- White background behind a contained image -->
<img src="https://your-domain.smallpics.io/logo.png?w=400&h=400&fit=contain&bg=white" />
<!-- Hex color -->
<img src="https://your-domain.smallpics.io/logo.png?w=400&h=400&fit=contain&bg=ff6600" />Supports CSS color names and hex values (3, 4, 6, or 8 digits).
Borders: border
Add a border around the image. The format is width,color,method:
<!-- 10px red border -->
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&border=10,red,overlay" />The method can be overlay (draws on top of the image), shrink (shrinks the image to make room), or expand (increases the canvas).
Watermarks
Overlay a watermark from your configured watermarks directory:
<img
src="https://your-domain.smallpics.io/photo.jpg?w=1200&mark=logo.png&markpos=bottom-right&markalpha=50"
/>| Parameter | Description |
|---|---|
mark | Watermark filename |
markpos | Position (e.g. center, top-left, bottom-right) |
markalpha | Opacity, 0-100 |
markw / markh | Watermark dimensions |
markpad | Padding around the watermark |
markx / marky | Offset from edges |
markfit | How the watermark scales |
markorigin | Image origin for the watermark |
Progressive loading: interlace
Enable progressive encoding for JPEG and PNG:
<img src="https://your-domain.smallpics.io/photo.jpg?w=1200&fm=jpg&interlace=1" />This makes images render progressively in the browser, appearing blurry first and sharpening as data loads. Useful for large above-the-fold images.
Signed URLs: s
If you have URL signing enabled on your image source, append the signature:
<img src="https://your-domain.smallpics.io/photo.jpg?w=800&s=abc123..." />Signed URLs prevent anyone from modifying your transform parameters. See our docs for details on generating signatures.
Putting it all together
Here’s a real-world example for a responsive hero image:
<picture>
<source
srcset="https://your-domain.smallpics.io/hero.jpg?w=1200&h=630&fit=cover&fm=avif&q=80"
type="image/avif"
/>
<source
srcset="https://your-domain.smallpics.io/hero.jpg?w=1200&h=630&fit=cover&fm=webp&q=80"
type="image/webp"
/>
<img
src="https://your-domain.smallpics.io/hero.jpg?w=1200&h=630&fit=cover&fm=jpg&q=80"
alt="Hero image"
width="1200"
height="630"
loading="eager"
/>
</picture>And a responsive srcset for different screen widths:
<img
srcset="
https://your-domain.smallpics.io/photo.jpg?w=400&fm=webp 400w,
https://your-domain.smallpics.io/photo.jpg?w=800&fm=webp 800w,
https://your-domain.smallpics.io/photo.jpg?w=1200&fm=webp 1200w
"
sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
src="https://your-domain.smallpics.io/photo.jpg?w=800&fm=webp"
alt="Responsive image"
loading="lazy"
/>That covers everything the URL API can do. If you want the full parameter reference, it’s all in the docs. And if you want to try it on your own images, you can start a free trial, no credit card needed.