Data Types

Image Processing API

Image processing REST API for resizing, cropping, compressing, and manipulating images.

Usage

Replace raw with image in your image URLs:

https://upcdn.io
Account
/W142hJk/
API
image
File Path
/example.jpg
Parameters
?w=800&h=600

Finally, add the query string parameters documented on this page to process and optimize your images.

Supported Image Formats

The Image Processing API supports the following input formats:

  • AVIF

  • BMP

  • GIF

  • HEIC

  • HEIF

  • JFIF

  • JP2

  • JPEG

  • JPF

  • PDF

  • PNG

  • RAW

  • SVG

  • TIFF

  • WebP

The Image Processing API supports image conversion to the following output formats:

  • AVIF

  • GIF

  • JPEG

  • PNG

  • WebP

The f parameter can be used to explicitly set the output format. If f is unset, the input format will be used as the output format, with JPEG as a fallback if the format is not supported.

Supported Input Sources

Upload supports the following input sources:

  • Built-in Cloud Storage

  • External Amazon S3 Bucket

  • External HTTP(S) Origin

To configure an input source, select a folder in the Upload Dashboard and click "Edit Storage Type".

Image Compression API

Use the Image Compression API to optimize your images for the web.

For best results:

  • Photos:

    • Use: f=webp&q=70

    • You will notice lower file sizes compared to using f=jpeg.

  • Graphics:

    • Use: f=png&q=70

    • You will notice less noise with f=png compared to other image formats.

Format  f

f=avif

Converts the image to AVIF.

f=gif

Converts the image to GIF.

f=jpeg

Converts the image to JPEG.

f=jpg

Converts the image to JPEG. (Alias for f=jpeg.)

f=png

Converts the image to PNG.

f=webp

Converts the image to WebP.

Quality  q

q=<int>

Sets the quality of the image, allowing you to optimize your images for the web.

1 = highest image compression and smallest file size.

100 = lowest image compression and largest file size.

Image Resizing API

Use the Image Resizing API to automatically resize and crop images.

Width  w

w=<int>

Width to resize the image to.

Height  h

h=<int>

Height to resize the image to.

Fit  fit

fit=crop

Resizes the image to the given dimensions (see: w and h).

The resulting image may be cropped in one dimension to preserve the aspect ratio of the original image.

The cropped edges are determined by the crop parameter.

Resulting image size: = w x h

Aspect ratio preserved: yes

Cropping: yes

Requires: h, w

fit=enlarge

Enlarges the image to the given dimensions (see: w and h) but won't shrink images that already exceed the dimensions.

If enlargement occurs, the image will be enlarged until at least one dimension is equal to the given dimensions, while the other dimension will be ≤ the given dimensions.

Resulting image size: ≥ w | ≥ h

Aspect ratio preserved: yes

Cropping: no

Requires: h, w

fit=enlarge-cover

Enlarges the image to the given dimensions (see: w and h) but won't shrink images that already exceed the dimensions.

If enlargement occurs, the resulting image's dimensions will be ≥ the given dimensions.

Resulting image size: ≥ w & ≥ h

Aspect ratio preserved: yes

Cropping: no

Requires: h, w

fit=height

Resizes the image to the given height (see: h).

Width will be automatically set to preserve the aspect ratio of the original image.

Resulting image size: = h

Aspect ratio preserved: yes

Cropping: no

Requires: h

fit=max

Resizes the image to the given dimensions (see: w and h).

The resulting image may be smaller in one dimension, while the other will match the given dimensions exactly.

Resulting image size: (≤ w & = h) | (= w & ≤ h)

Aspect ratio preserved: yes

Cropping: no

Requires: h, w

fit=min

Resizes the image to the given dimensions (see: w and h).

The resulting image may be larger in one dimension, while the other will match the given dimensions exactly.

Resulting image size: (≥ w & = h) | (= w & ≥ h)

Aspect ratio preserved: yes

Cropping: no

Requires: h, w

fit=shrink

Shrinks the image to the given dimensions (see: w and h) but won't enlarge images that are already below the dimensions.

If shrinking occurs, the resulting image's dimensions will be ≤ the given dimensions.

Resulting image size: ≤ w & ≤ h

Aspect ratio preserved: yes

Cropping: no

Requires: h, w

fit=shrink-cover

Shrinks the image to the given dimensions (see: w and h) but won't enlarge images that are already below the dimensions.

If shrinking occurs, the image will be shrunk until at least one dimension is equal to the given dimensions, while the other dimension will be ≥ the given dimensions.

Resulting image size: ≤ w | ≤ h

Aspect ratio preserved: yes

Cropping: no

Requires: h, w

fit=stretch

Resizes the image to the given dimensions, stretching to fit if required (see: w and h).

Resulting image size: = w x h

Aspect ratio preserved: no

Cropping: no

Requires: h, w

fit=width

Resizes the image to the given width (see: w).

Height will be automatically set to preserve the aspect ratio of the original image.

Resulting image size: = w

Aspect ratio preserved: yes

Cropping: no

Requires: w

Crop  crop

crop=bottom

Automatically crops to the bottom of the image.

The crop is performed by removing pixels evenly from the left and right of the image, or from the top of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=bottom-left

Automatically crops to the bottom-left corner of the image.

The crop is performed by removing pixels from the top or right of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=bottom-right

Automatically crops to the bottom-right corner of the image.

The crop is performed by removing pixels from the top or left of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=center

Automatically crops to the center of the image.

The crop is performed by removing pixels evenly from both sides of one axis, while leaving the other axis uncropped.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=left

Automatically crops to the left of the image.

The crop is performed by removing pixels evenly from the top and bottom of the image, or from the right of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=right

Automatically crops to the right of the image.

The crop is performed by removing pixels evenly from the top and bottom of the image, or from the left of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=smart

Automatically crops to the area of the image with the highest luminance frequency, color saturation, and presence of skin tones.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=smart-entropy

Automatically crops to the area of the image with the highest entropy.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=top

Automatically crops to the top of the image.

The crop is performed by removing pixels evenly from the left and right of the image, or from the bottom of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=top-left

Automatically crops to the top-left corner of the image.

The crop is performed by removing pixels from the bottom or right of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

crop=top-right

Automatically crops to the top-right corner of the image.

The crop is performed by removing pixels from the bottom or left of the image, but never both.

To use this parameter, you must set fit=crop or leave fit unspecified.

For manual cropping: use crop-x, crop-y, crop-w and crop-h instead of crop.

Requires: h, w

Image Cropping API

Use the Image Cropping API to manually crop images to a specific region.

Crop X  crop-x

crop-x=<int>

The X position within the image to crop from.

Requires: crop-y, crop-h, crop-w

Crop Y  crop-y

crop-y=<int>

The Y position within the image to crop from.

Requires: crop-x, crop-h, crop-w

Crop Width  crop-w

crop-w=<int>

The width of the crop area.

Requires: crop-h, crop-x, crop-y

Crop Height  crop-h

crop-h=<int>

The height of the crop area.

Requires: crop-w, crop-x, crop-y

Image Manipulation API

Use the Image Manipulation API to apply adjustments and filters to the underling image.

Blur  blur

blur=fast

Blurs the image by an automatic amount (fastest).

blur=<int>

Blurs the image by the given amount.

Sharpen  sharpen

sharpen=fast

Sharpens the image by an automatic amount (fastest).

sharpen=<int>

Sharpens the image by the given amount.

Brightness  brightness

brightness=<int>

Adjusts the brightness of the image.

Note: brightness is multiplicative whereas lightness is additive.

Lightness  lightness

lightness=<int>

Adjusts the lightness of the image.

Note: brightness is multiplicative whereas lightness is additive.

Hue  hue

hue=<int>

Adjusts the hue of the image.

Saturation  saturation

saturation=<int>

Adjusts the saturation of the image.

Grayscale  grayscale

grayscale=true

Converts the image to grayscale (removes color from the image).

Negate  negate

negate=true

Negates the RGB channels, producing a "negative" of the original image.

Negate Alpha Channel  negate-alpha

negate-alpha=<bool>

Negates the alpha channel in addition to the RGB channels.

Tint  tint

tint=<string>

Tints the image using the provided chroma color.

Image luminance is preserved.

Alpha channels (i.e. transparent parts of the image) will be unaffected by the tint.

Flip  flip

flip=x

Flips the image horizontally.

flip=y

Flips the image vertically.

Image Rotation API

Use the Image Rotation API to rotate images by a fixed number of degrees, or to remove EXIF rotation metadata from images.

Rotation  rotate

rotate=auto

Converts an EXIF-rotated image to a pixel-rotated image, and then removes the EXIF rotation metadata.

The resulting image will appear identical to the original image — in the sense that no additional rotation has been applied — but the EXIF rotation metadata will have been removed.

This step is performed automatically if no other rotation parameters are provided.

rotate=<int>

Rotates the image by the given degrees.

Rotation Background  rotate-bg

rotate-bg=<string>

The background color to use when the rotate parameter does not evenly divide into 90.

Requires: rotate

Image Layer API

Use the Image Layer API to add image overlays and image watermarks.

When using the Image Layer API to add image watermarks, we recommend using the repeat, blend, layer-opacity, layer-rotate and layer-w parameters to repeat the image across the canvas.

Image  image

image=<string>

Renders another image or SVG over the image.

To use: specify the "file path" attribute of another image uploaded to your Upload account as the query parameter's value.

Text Layer API

Use the Text Layer API to add text overlays and image watermarks.

When using the Text Layer API to add image watermarks, we recommend using the repeat, blend, layer-opacity, layer-rotate and layer-w parameters to repeat the text across the image.

Text  text

text=<string>

Adds text to the image. The overlayed text can be further manipulated using the Image Processing API's text and layer parameters.

Text Color  color

color=<string>

Sets the text color.

Requires: text

Text Font  font

font=<string>

Sets the font to use for the text.

To use: specify the "file path" attribute of a TTF file uploaded to your Upload account as the query parameter's value.

Requires: text

Text Font Size  font-size

font-size=auto

Automatically sets the font size, causing text to fill its bounding box.

If layer-width or layer-height are not provided, then the image's dimensions are used as the bounding box.

Requires: text

font-size=<int>

Sets the font size to a specific DPI (dots per inch).

Tip: this number may need to be large (typically 200+) for the text to be legible.

Requires: text

Text Font Style  font-style

font-style=italic

Sets the font style for the text.

Requires: text

font-style=normal

Sets the font style for the text.

Requires: text

font-style=oblique

Sets the font style for the text.

Requires: text

Text Font Weight  font-weight

font-weight=<int>

Sets the font weight for the text.

Font weights are typically between 100 and 900, in increments of 100.

Requires: text

Text Justification  justify

justify=<bool>

Expands the spacing between the words in multiline text to align the first and last word of each line, except for the last line, which uses the font's default spacing.

Requires: text

Text Letter Spacing  letter-spacing

letter-spacing=<int>

Adjusts the spacing between each letter.

Supports positive and negative values.

Tip: this number may need to be large (e.g. +/- 20000) to make a visible difference.

Requires: text

Text Line Height  line-height

line-height=<int>

Increases the line height from the font's default.

Decreasing the line height is not currently supported: to decrease the line height, please use a custom font with a reduced line height.

Requires: text

Text Underline  underline

underline=double

Underlines the text with a double line.

Requires: text

underline=error

Underlines the text with a single wiggly line, similar to the "spelling error" underline used by most word processing applications.

Requires: text

underline=low

Underlines the text with a single line (closer to the text than single).

Requires: text

underline=single

Underlines the text with a single line.

Requires: text

Text Underline Color  underline-color

underline-color=<string>

Sets the color to use for the underline parameter.

Requires: text

Layer API

The Layer API is the base API for the Image Layer API and Text Layer API.

Each parameter listed here can be combined with the parameters from the Image Layer API and Text Layer API to control general layer behaviour.

Layer Width  layer-w

layer-w=<int>

Sets the external width dimension for the image or text.

The resulting image or text overlay may be smaller than this dimension: if this occurs, align will be used to align the content within the internal width dimension (the internal width dimension is the external width dimension minus any horizontal padding).

Requires: image or text

Layer Height  layer-h

layer-h=<int>

Sets the external height dimension for the image or text.

The resulting image or text overlay may be smaller than this dimension: if this occurs, valign will be used to align the content within the internal height dimension (the internal height dimension is the external height dimension minus any vertical padding).

Requires: image or text

Layer X & Y (Auto)  gravity

gravity=bottom

Automatically positions the layer to the bottom-center of the image.

Requires: image or text

gravity=bottom-left

Automatically positions the layer to the bottom-left corner of the image.

Requires: image or text

gravity=bottom-right

Automatically positions the layer to the bottom-right corner of the image.

Requires: image or text

gravity=center

Automatically positions the layer to the center of the image.

Requires: image or text

gravity=left

Automatically positions the layer to the left-center of the image.

Requires: image or text

gravity=right

Automatically positions the layer to the right-center of the image.

Requires: image or text

gravity=top

Automatically positions the layer to the top-center of the image.

Requires: image or text

gravity=top-left

Automatically positions the layer to the top-left corner of the image.

Requires: image or text

gravity=top-right

Automatically positions the layer to the top-right corner of the image.

Requires: image or text

Layer X  layer-x

layer-x=<int>

Sets the X position for the image or text.

Requires: image or text

Layer Y  layer-y

layer-y=<int>

Sets the Y position for the image or text.

Requires: image or text

Layer Opacity  layer-opacity

layer-opacity=<int>

Sets the opacity for the image or text.

Tip: this parameter is useful for adding text and/or image watermarks.

Requires: image or text

Layer Repeat  repeat

repeat=<bool>

Repeats the layer infinitely on both axis.

No spacing is added between repetitions.

To add spacing: use the padding parameter to add internal spacing to the layer.

Tip: this parameter is useful for adding text and/or image watermarks.

Requires: image or text

Layer Rotation  layer-rotate

layer-rotate=<int>

Rotates the image or text by the given degrees.

Tip: this parameter is useful for adding text and/or image watermarks.

Requires: image or text

Layer Horizontal Alignment  align

align=center

Horizontal alignment of the image or text within the layer's internal width dimension.

Internal width dimension = the layer's external width dimension minus any horizontal padding.

External width dimension = the layer-w parameter (if set) else the image's width minus the layer-x parameter.

Requires: image or text

align=left

Horizontal alignment of the image or text within the layer's internal width dimension.

Internal width dimension = the layer's external width dimension minus any horizontal padding.

External width dimension = the layer-w parameter (if set) else the image's width minus the layer-x parameter.

Requires: image or text

align=right

Horizontal alignment of the image or text within the layer's internal width dimension.

Internal width dimension = the layer's external width dimension minus any horizontal padding.

External width dimension = the layer-w parameter (if set) else the image's width minus the layer-x parameter.

Requires: image or text

Layer Vertical Alignment  valign

valign=bottom

Vertical alignment of the image or text within the layer's internal height dimension.

Internal height dimension = the layer's external height dimension minus any vertical padding.

External height dimension = the layer-h parameter (if set) else the image's height minus the layer-y parameter.

Requires: image or text

valign=center

Vertical alignment of the image or text within the layer's internal height dimension.

Internal height dimension = the layer's external height dimension minus any vertical padding.

External height dimension = the layer-h parameter (if set) else the image's height minus the layer-y parameter.

Requires: image or text

valign=top

Vertical alignment of the image or text within the layer's internal height dimension.

Internal height dimension = the layer's external height dimension minus any vertical padding.

External height dimension = the layer-h parameter (if set) else the image's height minus the layer-y parameter.

Requires: image or text

Layer Padding  padding

padding=<int>

Sets the padding for the image or text.

Requires: image or text

Layer Padding X  padding-x

padding-x=<int>

Sets the horizontal (left and right) padding for the image or text.

Requires: image or text

Layer Padding Y  padding-y

padding-y=<int>

Sets the vertical (top and bottom) padding for the image or text.

Requires: image or text

Layer Padding Top  padding-top

padding-top=<int>

Sets the top padding for the image or text.

Requires: image or text

Layer Padding Bottom  padding-bottom

padding-bottom=<int>

Sets the bottom padding for the image or text.

Requires: image or text

Layer Padding Left  padding-left

padding-left=<int>

Sets the left padding for the image or text.

Requires: image or text

Layer Padding Right  padding-right

padding-right=<int>

Sets the right padding for the image or text.

Requires: image or text

Layer Blend Mode  blend

blend=add

Renders the sum of each pixel.

Requires: image or text

blend=color-burn

Renders the layer over the base image.

Darkens the layer's color by a factor depending on the base layer's color.

Requires: image or text

blend=color-dodge

Renders the layer over the base image.

Brightens the layer's color by a factor depending on the base layer's color.

Requires: image or text

blend=darken

Renders the layer over the base image.

Intersecting pixels are mixed using the darkest color component from each layer.

Requires: image or text

blend=dest-atop

Renders the base image over the layer.

Uses the layer's alpha channel for the base image's alpha channel.

Opposite of source-atop.

Requires: image or text

blend=dest-in

Renders the base image only.

The layer's alpha channel is used as a mask for the base image.

Opposite of source-in.

Requires: image or text

blend=dest-out

Renders the base image only.

The layer's alpha channel is used as an inverse mask for the base image.

Opposite of source-out.

Requires: image or text

blend=dest-over

Renders the base image over the layer.

Opposite of source-over.

Requires: image or text

blend=difference

Renders the difference of the two images.

Requires: image or text

blend=exclusion

Renders the difference of the two images (with a lower contrast than the difference blend mode).

Requires: image or text

blend=hard-light

Renders the layer over the base image.

Intersecting pixels are blended with multiply or screen, depending on the lightness of the base image's colors.

Requires: image or text

blend=lighten

Renders the layer over the base image.

Intersecting pixels are mixed using the lightest color component from each layer.

Requires: image or text

blend=multiply

Renders the layer over the base image.

Intersecting pixels will be as dark as, or darker than, the original pixels from each.

Requires: image or text

blend=overlay

Renders the layer over the base image.

Intersecting pixels are blended with multiply or screen, depending on the lightness of the layer's colors.

Requires: image or text

blend=saturate

Renders the base image over the layer.

Darkens the layer per the layer's alpha channel (0% alpha = 100% darkness applied, 100% alpha = 0% darkness applied).

Requires: image or text

blend=screen

Renders the layer over the base image.

Intersecting pixels will be as light as, or lighter than, the original pixels from each.

Requires: image or text

blend=soft-light

Renders the layer over the base image.

Intersecting pixels are blended with darken or lighten, depending on the lightness of the base image's colors.

Requires: image or text

blend=source-atop

Renders the layer over the base image.

Uses the base image's alpha channel for the layer's alpha channel.

Requires: image or text

blend=source-in

Renders the layer only.

The base image's alpha channel is used as a mask for the layer.

Requires: image or text

blend=source-out

Renders the layer only.

The base image's alpha channel is used as an inverse mask for the layer.

Requires: image or text

blend=source-over

Renders the layer over the base image.

Default blend mode.

Requires: image or text

blend=xor

Performs a XOR of the alpha channels between both layers.

Requires: image or text

Layer Premultiply Base  premultiply

premultiply=<bool>

Set to true to disable pre-multiplication of the base image.

Requires: image or text

Miscellaneous Parameters

Flush  flush

flush=true

Forces a render of the image before applying subsequent parameters.

Explanation:

The Image Processing API will attempt to combine as many parameters into a single pixel processing pipeline as possible. This is an optimization it performs to reduce the number of pixel iterations required to process the image.

In certain situations — and depending on your requirements — this may yield undesirable visual effects.

The flush=true parameter allows you to control this behaviour.

Example:

The Image Processing API merges the rotate and blur steps by default. This means that rotated images will have visibly blurry edges if a non-right-angle rotation is used (e.g. 45°). If this is undesirable, you can perform blur=10&flush=true&rotate=45 to force a render between the blur and the rotation, resulting in a blurred image with sharp edges rotated at 45° (rather than a blurred image with blurry edges rotated at 45°).

Was this section helpful? Yes No

Image Processing API

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: