CDN API Reference
- Accessing CDN API
- CDN API Limitations
- Resize and Crop Images
- Image Compression and Performance
- Image Rotation
- Image Filters
Accessing CDN API
To access the Uploadcare CDN API, you make requests to ucarecdn.com
via HTTP
or HTTPS. Make sure the file you are requesting is uploaded to
one of your Uploadcare projects.
A valid CDN URL to request a file from Uploadcare CDN looks like this:
https://ucarecdn.com/:uuid/
When using one of our paid plans, you can connect Uploadcare CDN to your domain or subdomain, Let’s Encrypt SSL certificate included.
CDN API operations are applied to files by including URL directives in their respective CDN URLs:
https://ucarecdn.com/:uuid/-/:operation/:params/:filename
Where:
:uuid
stands for the unique file identifier, UUID, assigned on upload./-/
is the mandatory delimiter for our parser to tell operations from one another and other path components.:operation/:params/
stands for a CDN API operation URL directive and related parameters.:filename
is an optional filename you can add after the trailing/
in a CDN URL.
Note, consider piping operations to experience the full CDN API potential:
-/:operation/:params/-/:operation/:params/
CDN API Limitations
This section describes the limits to consider when implementing Uploadcare Image Transformations.
Core Operations
When applying image transformations, add at least one of the following operations via their respective URL directives:
Output Image Dimensions
The dimensions you specify for the last operation should not exceed 3000x3000
pixels. You can increase that limit to 5000x5000 pixels by explicitly setting
your image format to JPEG, /format/jpeg/
.
File Size
We don’t provide on-the-fly image transformations for images greater than 75 Mpx in resolution: those can only be delivered via CDN as-is.
Simple Rotation
When the only image transformation you want is rotating, consider using the
preview
control without any arguments. When you use
any of the transformations, we automatically rotate images according to their
EXIF orientation.
Animated Images
Animated images are treated as static by the transformations engine, consider checking out our GIF to Video workflow optimized for animated images delivery.
Resize and Crop Images
preview
Resize an image to fit into specified dimensions, proportional.
-/preview/:dimensions/
Value type: string
, format: MxN
, where M
and N
are the output dimensions
in pixels of type integer
.
Default value: 2048x2048
.
resize
Resize an image to fit into specified dimensions.
-/resize/:dimensions/
Value type: string
, format: MxN
, where M
and N
are the mandatory output
dimensions in pixels of type integer
. Either M
and N
can be ommited
providing the proportional resizing behavior.
Default value: N/A.
Including the resize
URL directive without arguments raises an error:
Mandatory argument "OneOrTwoDimensions(dimensions)" not found while parsing {directive}
crop
Crop an image to fit into specified dimensions, implement optional offsets.
-/crop/:dimensions/:offsets/
Value type:
:dimensions
—string
, format:MxN
, whereM
andN
are the mandatory output dimensions in pixels of typeinteger
.:offsets
—string
, format:M,N
orcenter
, whereM
andN
are the optional offsets along one or both of the axes;center
is a keyword centering the crop focus.
Default value:
:dimensions
— N/A.:offsets
—0,0
, top-left image corner.
Including the crop
URL directive without :dimensions
raises an error:
Mandatory argument "RelativeDimensions(dimensions)" not found while parsing {directive}
scale_crop
Downscale an image along one of the axes (the one with smaller linear size) and crop the rest. The method can be implemented with manual, center-focused or “smart crop” behavior.
-/scale_crop/:dimensions/
-/scale_crop/:dimensions/:type/
-/scale_crop/:dimensions/:offsets/
Value type:
:dimensions
—string
, format:MxN
, whereM
andN
are the mandatory output dimensions in pixels of typeinteger
.:type
—string
, format:smart
, an optional keyword which enables smart image analysis.:offsets
—string
, format:M%,N%
, whereM
andN
are the optional offsets along one or both of the axes in percentages; other possible values include:center
, a keyword responsible for centering the crop focus.smart
, a keyword responsible for switching to the “smart crop” behavior.
Default value:
:dimensions
— N/A.
Including the scale_crop
URL directive without :dimensions
raises an error:
Mandatory argument "TwoDimensions(dimensions)" not found while parsing {directive}
stretch
Set the resize
operation behavior when provided
:dimensions
are greater than the source image dimensions. The directive should
come before resize
to give any effect.
-/stretch/:mode/
Value type: string
, format: keyword:
on
— stretch the source image.off
— forbid stretching the source image.fill
— forbid stretching the source image, render color-filled frame around.
Default value: on
.
Including the stretch
URL directive without any value raises an error:
Mandatory argument "Enum(value)" not found while parsing {directive}
setfill
Set the fill color when converting alpha channel enabled images to JPEG, with
crop
or stretch
.
-/setfill/:color/
Value type: hex
color.
Default value: ffffff
.
Including the setfill
URL directive without any value raises an error:
Mandatory argument "Color(fill_color)" not found while parsing "setfill"
Image Compression and Performance
format
Convert an image to one of the supported output formats.
-/format/:format/
Value type: string
, format: keyword, mandatory:
jpeg
— convert an image to JPEG.png
— convert an image to PNG.webp
— convert an image to WebP.auto
— try converting to WebP and fall back to JPEG when a user browser provides no WebP support.
Default value: N/A.
Including the format
URL directive without any value raises an error:
Mandatory argument "Enum(format_name)" not found while parsing {directive}
quality
Adjust image quality. Works with JPEG and WebP formats.
The main purpose of the quality
operation is to cut image sizes, thus the
quality levels can not be set higher than their original values.
-/quality/:value/
Value type: string
, format: keyword, mandatory:
lightest
— ≈50% file size compared tonormal
.lighter
— ≈80% file size.normal
— ≈100% file size.better
— ≈125% file size.best
— ≈170% file size.
Default value: normal
.
Including the quality
URL directive without any value raises an error:
Mandatory argument "Enum(quality_value)" not found while parsing {directive}
progressive
Convert JPEG to Progressive JPEG. Has no effect on non-JPEGs. Does not force
image formats to jpeg
.
-/progressive/:option/
Value type: string
, format: keyword, mandatory:
yes
— use multi-scan rendering.no
— do not use multi-scan rendering.
Default value: no
.
Including the quality
URL directive without any value raises an error:
Mandatory argument "Boolean(progressive)" not found while parsing {directive}
max_icc_size
Strip off an ICC profile from an image based on the profile size in kilobytes.
-/max_icc_size/:value/
Value type: integer
, format: size in kilobytes.
Default value: 10
(10240 bytes).
Including the max_icc_size
URL directive without any value raises an error:
Mandatory argument "PositiveInteger(size)" not found while parsing {directive}
Image Rotation
autorotate
Instruct Uploadcare CDN whether it should rotate an image according to the
EXIF orientation
tag or not.
Value type: string
, format: keyword, mandatory:
yes
— rotate an image.no
— do not rotate an image.
Default value: yes
.
-/autorotate/:value/
Including the autorotate
URL directive without any value raises an error:
Mandatory argument "Boolean(autorotate)" not found while parsing {directive}
rotate
Rotate an image counterclockwise.
Value type: integer
, format: angle in degrees, must be a multiple of 90,
mandatory:
Default value: no
.
-/rotate/:value/
Including the rotate
URL directive without any value raises an error:
Mandatory argument "AngleInDegrees(angle)" not found while parsing {directive}
flip
Flip an image (mirror-reverse an image across the horizontal axis).
Value is not required.
-/flip/
mirror
Mirror an image (mirror-reverse an image across the vertical axis).
Value is not required.
-/mirror/
Image Filters
enhance
Auto-enhance an image by performing the following operations: auto levels, auto contrast, and saturation sharpening.
-/enhance/
-/enhance/:value/
Value type: integer
, format: strength, must be in range from 0 to 100.
Default value: 50
.
sharp
Sharpen an image, might be especially useful with images that were subjected to downscaling.
-/sharp/
-/sharp/:value/
Value type: integer
, format: strength, must be in range from 0 to 20.
Default value: 5
.
blur
Blur images by the strength
factor. The filtering mode is Gaussian Blur,
where strength
parameter sets the blur radius — effect intensity.
Technically, strength
controls the Gaussian Blur standard deviation
multiplied by ten. Note, different strength
values do not affect the
operation performance.
-/blur/
-/blur/:value/
Value type: integer
, format: strength, must be in range from 0 to 5000.
Default value: 5
.
grayscale
Desaturate an image.
Value is not required.
-/grayscale/
invert
Invert the colors of an image.
Value is not required.
-/invert/