Image processing REST API to resize, crop, compress, optimize, and manipulate images in real-time.
Replace raw with image in your file URLs:
To get a file URL: upload a file or create an external file source.
The response body will be the processed image or a JSON error response.
Images take ~600ms to process (to a resize a 10MB JPEG from 4000×3000 to 800×600).
Documents take ~300ms to process (to generate a thumbnail from a 5MB A4 PDF with edge-to-edge graphics).
Videos take ~5 seconds to process (to generate a thumbnail from a 1.5GB MP4 video at 1920×1080).
Caching benefits users with < 100ms latency for subsequent requests. See: edge caching and permanent caching.
Input files can be pulled from the following sources:
To create a file source: create a folder in the Upload Dashboard and edit its storage settings.
The Image Processing API can generate images from images, videos, and documents:
The Image Processing API can generate images from the following image inputs:
AVIF
BMP
GIF (for animated GIFs: use page to extract a specific frame, else the first frame will be extracted.)
HEIC
HEIF
JFIF
JP2
JPEG
JPF
PNG
RAW
SVG
TIFF (for multi-page TIFFs: use page to extract a specific page, else the first page will be extracted.)
WebP (for animated WebPs: use page to extract a specific frame, else the first frame will be extracted.)
Use f to specify the output format. Default value is the input image's format if supported as an output format, else JPEG.
The Image Processing API can generate video thumbnails from the following video inputs:
| File Extension(s) | Video Container | Video Codecs |
|---|---|---|
.m2v, .mpeg, .mpg | No Container | AVC (H.264), DV/DVCPRO, HEVC (H.265), MPEG-1, MPEG-2 |
.3g2 | 3G2 | AVC (H.264), H.263, MPEG-4 part 2 |
.3gp | 3GP | AVC (H.264), H.263, MPEG-4 part 2 |
.wmv | Advanced Systems Format (ASF) | VC-1 |
.flv | Adobe Flash | AVC (H.264), Flash 9 File, H.263 |
.avi | Audio Video Interleave (AVI) | Uncompressed, Canopus HQ, DivX/Xvid, DV/DVCPRO, MJPEG |
.m3u8 | HLS (MPEG-2 TS segments) | AVC (H.264), HEVC (H.265), MPEG-2 |
.mxf | Interoperable Master Format (IMF) | Apple ProRes, JPEG 2000 (J2K) |
.mxf | Material Exchange Format (MXF) | Uncompressed, AVC (H.264), AVC Intra 50/100, Apple ProRes (4444, 4444 XQ, 422, 422 HQ, LT, Proxy), DV/DVCPRO, DV25, DV50, DVCPro HD, JPEG 2000 (J2K), MPEG-2, Panasonic P2, SonyXDCam, SonyXDCam MPEG-4 Proxy, VC-3 |
.mkv | Matroska | AVC (H.264), MPEG-2, MPEG-4 part 2, PCM, VC-1 |
.mpg, .mpeg, .m2p, .ps | MPEG Program Streams (MPEG-PS) | MPEG-2 |
.m2t, .ts, .tsv | MPEG Transport Streams (MPEG-TS) | AVC (H.264), HEVC (H.265), MPEG-2, VC-1 |
.dat, .m1v, .mpeg, .mpg, .mpv | MPEG-1 System Streams | MPEG-1, MPEG-2 |
.mp4, .mpeg4 | MPEG-4 | Uncompressed, DivX/Xvid, H.261, H.262, H.263, AVC (H.264), AVC Intra 50/100, HEVC (H.265), JPEG 2000, MPEG-2, MPEG-4 part 2, VC-1 |
.mov, .qt | QuickTime | Uncompressed, Apple ProRes (4444, 4444 XQ, 422, 422 HQ, LT, Proxy), DV/DVCPRO, DivX/Xvid, H.261, H.262, H.263, AVC (H.264), AVC Intra 50/100, HEVC (H.265), JPEG 2000 (J2K), MJPEG, MPEG-2, MPEG-4 part 2, QuickTime Animation (RLE) |
.webm | WebM | VP8, VP9 |
Use t to specify the time to extract the video thumbnail from (in seconds). Default value is t=auto.
The Image Processing API can generate thumbnails from PDF documents.
Use page and page-count to specify the page to extract. Default values are page=1 and page-count=1.
Use the Image Optimization API to reduce the file size of your images.
To reduce your image's file size:
Set w and h as low as possible.
Use: fit=shrink or fit=shrink-cover to prevent image enlargement.
Use: c=100 for high image compression.
Use: q=70
Use: f=webp
You should notice lower file sizes compared to using f=jpg.
Use f2=jpg or f2=png to fallback onto JPG or PNG for images larger than 16383×16383.
To reduce processing time:
Set w and h as low as possible (processing time increases linearly with the image's output dimensions).
Use: fit=shrink or fit=shrink-cover to prevent image enlargement.
Use: c=1 for fast image compression if using f=avif, f=gif, f=png or f=webp.
Use: q=70
Use: f=jpg
JPGs are faster to generate than WEBPs, even when using f=webp&c=1.
Avoid using: f=png
PNGs require ~1.5x as much processing time as f=webp and f=jpg.
PNGs should therefore have f=webp set if transparency is required, else you may use f=jpg.
PNGs that don't have a f parameter set will be rendered as PNGs, thus may take longer to process.
To measure the processing time of each HTTP request:
The x-cpu-on-cache-miss HTTP response header tells you how many CPU milliseconds you were billed when the image was processed.
If either of these HTTP response headers are present, then no image processing occurred:
x-cache: Hit
x-cache-perma: Hit
To boost image download performance even further:
Ensure your permanent cache is enabled: this will eliminate re-processing delays for subsequent requests to the same URL.
Consider using Upload's Extended Coverage CDN for lower-latency downloads from the Asia Pacific & Africa.
Converts the image to AVIF when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).
Converts the image to GIF when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).
Converts the image to JPEG when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).
Converts the image to PNG when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).
Sets the quality of the image, allowing you to optimize your images for the web.
•1 = lowest image quality (smaller file size).
•100 = highest image quality (larger file size).
Sets the compression effort for the resulting image. Does not affect quality.
•1 = lowest compression, shortest processing time, but largest file size.
•100 = highest compression, longest processing time, and smallest file size.
Only applies to: f=avif, f=gif, f=png and f=webp.
Use the Video Thumbnail API to generate video thumbnails (aka video poster images) from a supported video file type.
Gets a thumbnail from 5 seconds into the video, or the last frame of the video: whichever comes first.
When batch=true then t=auto will be interpreted as t=0.
Default: t=auto
Gets a thumbnail from a specific time in the video (in seconds).
If t exceeds the length of the video, then a JSON error will be returned with a 400 status code.
Supports numbers between 0 - 86400 with up to two decimal places, for example: t=30.75
Important: thumbnails take considerably longer to generate further into the video compared to at the start, for some video formats.
Default: t=auto
Generates a single video thumbnail.
The HTTP response body will be the generated video thumbnail image.
Pricing for video thumbnail requests (non-batch mode):
Your CPU quota will have the maximum of the following values deducted from it:
•The time the request takes to process (see the x-cpu-on-cache-miss HTTP response header)
•8 seconds
Default: batch=false
Generates up to 10 video thumbnails.
The HTTP response body will be a JSON document containing artifact paths to the thumbnails.
Thumbnails can be accessed via the artifact parameter, e.g. ?batch=true&artifact=/01
Pricing for video thumbnail requests (batch mode):
Your CPU quota will have the maximum of the following values deducted from it:
•The time the request takes to process (see the x-cpu-on-cache-miss HTTP response header)
•The seconds of video covered by the generated thumbnails (see the duration parameter)
•8 seconds
Default: batch=false
Specifies the duration the thumbnails should cover in seconds. (Only applicable when batch=true.)
Supports numbers between 1 - 86400 with up to two decimal places, for example: duration=15.50
If t + duration exceeds the length of the video while t is less than the length of the video, then thumbnails will be generated for the section of video that exists, and the duration of that section will be used in the billing calculations as opposed to the duration parameter.
Default: duration=5
Specifies the number of thumbnails to generate per second of the duration parameter. (Only applicable when batch=true.)
Supports numbers between 0.0001 - 120 with up to four decimal places, for example: fps=0.5 creates a thumbnail every 2 seconds.
Default: fps=1
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Use the Image Canvas API to extend the image's canvas beyond the input image's size:
Use the Image Manipulation API to apply adjustments and filters to the underlying image:
Adjusts the brightness of the image.
Note: brightness is multiplicative whereas lightness is additive.
Adjusts the lightness of the image.
Note: brightness is multiplicative whereas lightness is additive.
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.
Use the Image Rotation API to rotate images by a fixed number of degrees, or to remove EXIF rotation metadata from images:
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.
The background color to use when the rotate parameter does not evenly divide into 90.
Requires: rotate
Use the Image Layer API to add image overlays and 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.
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.
Use the Text Layer API to add text overlays and 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.
Adds text to the image. The overlayed text can be further manipulated using the Image Processing API's text and layer parameters.
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
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
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
Sets the font weight for the text.
Font weights are typically between 100 and 900, in increments of 100.
Requires: text
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
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
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
Underlines the text with a single wiggly line, similar to the "spelling error" underline used by most word processing applications.
Requires: text
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.
Sets the external width for the layer (i.e. the image or text).
The layer's "internal dimensions" are the bounding box for the layer's contents: the layer's contents will be resized to fit inside the layer's internal dimensions while preserving the content's aspect ratio. If the contents becomes thinner than the layer's internal width, then the contents will be x-aligned within the layer's internal width per the align parameter.
•Internal width = the layer's external width minus horizontal padding (if any).
•External width = the layer-w parameter (if set) else the image's width minus layer-x (if set).
Requires: image or text
Sets the external height for the layer (i.e. the image or text).
The layer's "internal dimensions" are the bounding box for the layer's contents: the layer's contents will be resized to fit inside the layer's internal dimensions while preserving the content's aspect ratio. If the contents becomes shorter than the layer's internal height, then the contents will be y-aligned within the layer's internal height per the valign parameter.
•Internal height = the layer's external height minus vertical padding (if any).
•External height = the layer-h parameter (if set) else the image's height minus layer-y (if set).
Requires: image or text
Automatically positions the layer to the bottom-center of the image.
Requires: image or text
Automatically positions the layer to the bottom-left corner of the image.
Requires: image or text
Automatically positions the layer to the bottom-right corner of the image.
Requires: image or text
Automatically positions the layer to the left-center of the image.
Requires: image or text
Automatically positions the layer to the right-center of the image.
Requires: image or text
Automatically positions the layer to the top-left corner of the image.
Requires: image or text
Automatically positions the layer to the top-right corner of the image.
Requires: image or text
Sets the opacity for the image or text.
Tip: this parameter is useful for adding text and/or image watermarks.
Requires: image or text
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
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
Horizontal alignment of the image or text within the layer's internal width dimension.
•External width dimension = the layer-w parameter (if set) else the image's width minus layer-x (if set).
•Internal width dimension = the layer's external width dimension (above) minus horizontal padding (if any).
Requires: image or text
Horizontal alignment of the image or text within the layer's internal width dimension.
•External width dimension = the layer-w parameter (if set) else the image's width minus layer-x (if set).
•Internal width dimension = the layer's external width dimension (above) minus horizontal padding (if any).
Requires: image or text
Horizontal alignment of the image or text within the layer's internal width dimension.
•External width dimension = the layer-w parameter (if set) else the image's width minus layer-x (if set).
•Internal width dimension = the layer's external width dimension (above) minus horizontal padding (if any).
Requires: image or text
Vertical alignment of the image or text within the layer's internal height dimension.
•External height dimension = the layer-h parameter (if set) else the image's height minus layer-y (if set).
•Internal height dimension = the layer's external height dimension (above) minus vertical padding (if any).
Requires: image or text
Vertical alignment of the image or text within the layer's internal height dimension.
•External height dimension = the layer-h parameter (if set) else the image's height minus layer-y (if set).
•Internal height dimension = the layer's external height dimension (above) minus vertical padding (if any).
Requires: image or text
Vertical alignment of the image or text within the layer's internal height dimension.
•External height dimension = the layer-h parameter (if set) else the image's height minus layer-y (if set).
•Internal height dimension = the layer's external height dimension (above) minus vertical padding (if any).
Requires: image or text
Sets the horizontal (left and right) padding for the image or text.
Requires: image or text
Sets the vertical (top and bottom) padding for the image or text.
Requires: image or text
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
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
Renders the layer over the base image.
Intersecting pixels are mixed using the darkest color component from each layer.
Requires: image or text
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
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
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
Renders the base image over the layer.
Opposite of source-over.
Requires: image or text
Renders the difference of the two images (with a lower contrast than the difference blend mode).
Requires: image or text
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
Renders the layer over the base image.
Intersecting pixels are mixed using the lightest color component from each layer.
Requires: image or text
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
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
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
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
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
Renders the layer over the base image.
Uses the base image's alpha channel for the layer's alpha channel.
Requires: image or text
Renders the layer only.
The base image's alpha channel is used as a mask for the layer.
Requires: image or text
Renders the layer only.
The base image's alpha channel is used as an inverse mask for the layer.
Requires: image or text
Set to true to disable pre-multiplication of the base image.
Requires: image or text
The Page Extraction API allows you to specify which page(s) from a multi-page input to extract.
Supports: PDF, GIF, and TIFF.
The number of pages to extract from the multi-page input file (PDF, GIF, TIFF).
You may specify -1 to extract all pages.
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°).
This website uses cookies. By continuing you are consenting to the use of cookies per our cookie policy.
This website requires a modern web browser -- the latest versions of these browsers are supported: