Small Pics URL API: A Practical Guide

The Small Pics URL API lets you resize, crop, format, and optimize images by adding query parameters to any image URL. No SDK required, no build step, 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 does the Small Pics URL API work?

Every Small Pics URL follows the same pattern:

https://your-domain.smallpics.io/image.jpg?w=800&h=600&fit=cover&fm=webp

The 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.

How do you resize an image? (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.

What fit modes does Small Pics support? (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%" />

How do you change the output 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

How do you control compression 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.

How do you crop a specific region? (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.

How do you rotate and flip images? (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" />

What image adjustments are available? (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	-

How do you set a 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).

How do you add 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).

How do you add 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

How do you enable 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.

How do you secure image 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.

How do you combine multiple transforms?

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.