Images

To transform an image, you need to make a request with parameters. The service will create a new file, return it in response to the request, and save it to your storage.

For subsequent requests with the same parameters, the already created file will be returned.

Example:

// create a new image with a width of 100px while maintaining the aspect ratio
https://api.defaultuploader.com/v1/image/upload/token/sample.jpg?w=100

width

alias: w

Creates an image with the specified width while maintaining the correct aspect ratio.

min 0, max 5000

height

alias: h

Creates an image with the specified height while maintaining the correct aspect ratio.

min 0, max 5000

format

alias: f

Changes the image format.

Supported formats
JPEG, PNG, WebP, AVIF, TIFF, GIF, SVG, HEIC

auto Coming soon

Automatic detection of modern image format support by the browser.

quality

alias: q

min 0, max 100, default value = 75

Change the image quality.

dpr

1, 2 — default 1

Supports high-resolution screens, doubling the image size.

animated

alias: a

animated=0

Disable animation for GIF or WebP.

fit

How the image should be resized/cropped to fit the target size(s).

cover, contain, fill, inside, outside

bg

Sets the background color when using fit=contain. The empty space around the image is filled with the specified color instead of black.

Format: 6-character hex color without #
Example: bg=ffffff, bg=1a1a2e

pad

Adds padding around the image as a percentage of the canvas size. Works only with fit=contain.

min 0, max 50 (percentage)

func

Smart crop. face and auto use AI to find a face or the “interesting” part of the image and center it in the crop. manual skips detection and crops around a focal point you choose with pos_x/pos_y — that point is placed at the center of the crop, with the framing controlled by zoom, the target aspect from w/h, and edge handling via pos_edge.

face, auto, manual

crop

Cut out an explicit rectangle of the source image, in percentages — no detection involved. Format: x,y,w,h, where x/y are the offset of the top-left corner and w/h the size of the region, each from 0 to 100.

x,y,w,h — each 0–100 (percent); x+w ≤ 100, y+h ≤ 100

Combine with w/h to resize the cropped region afterwards. crop needs no detection and takes an exact region, so it always takes precedence over func.

zoom

alias: z

Optional parameter for “smart” cropping (func). Adjusts how tightly the crop frames the subject.

min 0.1, max 10, step 0.1 — default 1

Values greater than 1 zoom in (a tighter crop around the face). Values less than 1 zoom out, keeping more context around the face — handy for banners and wide layouts. When zooming out past the image edges, the empty area is handled by pos_edge.

pos_x

alias: px

Horizontal position of the detected face within the output frame, as a percentage. Requires func=face. With func=manual it instead sets the horizontal focal point in the source image (see func).

min 0, max 100 — default 50 (centered)

pos_x=0 aligns the face to the left edge, pos_x=100 to the right edge.

pos_y

alias: py

Vertical position of the detected face within the output frame, as a percentage. Requires func=face. With func=manual it instead sets the vertical focal point in the source image (see func).

min 0, max 100 — default 38 (golden ratio)

When omitted, the face sits at about 38% from the top (golden ratio), shifting toward the center for group photos.

pos_edge

Strategy for the area that falls outside the source image when the crop extends past its edges (for example with zoom < 1, or an extreme pos_x/pos_y). Requires func=face or func=manual.

fill, clamp, outpaint — default fill

fill — keep the requested framing and fill the overflow with the bg color, or transparency (white for formats without an alpha channel, such as JPEG).
clamp — shift the crop to stay inside the image so there are no margins (the face position may move slightly).
outpaint — generate the missing background with AI. heavy slower, processed on a separate queue.

blur

Creates a blurred image

min 0.3, max 1000

negate

Creates a “negative” image

?negate

normalize_lower

Enhances the contrast of the output image by stretching its brightness to cover the full dynamic range

min 1, max 99

normalize_upper

Enhances the contrast of the output image by stretching its brightness to cover the full dynamic range

min 1, max 99

saturation

Sets the image saturation

min 0.1

brightness

Sets the image brightness

min 0.1

hue

Sets the image hue

min 1

lightness

Sets the image lightness

min 0.1

greyscale

Converts the image to black and white

?greyscale

radius

Rounds the corners of the image

min 0 max 100

To create a circular image, set equal dimensions.

remove_background

alias: rm_bg

Removes the background from the image

?rm_bg

super_resolution coming soon

Uses AI to upscale the image resolution.

download

Forces the browser to download the file instead of opening it inline, by setting the Content-Disposition: attachment response header. Works with any media type and combines with all transformation parameters. It does not affect the cached file — the ETag stays the same with and without download.

?download              — download with the original file name
?download=report.pdf   — download with a custom file name

nostore

Processes the requested transformation and returns the result without saving the variation to storage. The processed image is served from a temporary worker cache and is still cached by the CDN (the Cache-Control header is unchanged), so repeat requests stay fast — but no new object is written to your bucket. Useful for one-off or preview transforms you don’t want to persist.

Applies to images only and combines with any transformation parameters. CPU and traffic are billed as usual; the transformation limit is not counted against the request. If the requested variation already exists in storage (for example, from an earlier normal request), it is returned as-is.

?width=300&nostore=1   — resize, return the result, do NOT store the variation
?width=300&nostore     — same (the parameter's presence enables it)