Docs

CDN API Reference

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, where M and N are the mandatory output dimensions in pixels of type integer.
  • :offsets — string, format: M,N or center, where M and N 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/
-/scale_crop/:dimensions/:type/:offsets/

Value type:

  • :dimensions — string, format: MxN, where M and N are the mandatory output dimensions in pixels of type integer.
  • :type — string, an optional keyword which enables smart image analysis. Each smart analysis mode combines various methods for detecting areas of interest in an image. The methods you include are applied sequentially. The algorithm switches to the next method only if no regions were found by the previous one. If no regions of interest were found, the offsets :offsets setting is used to crop an image. When no :offsets are specified, images get center-cropped.

Possible :type values:

  • smart — default image analysis mode, face detection, object detection and corner points detection
  • smart_faces_objects_points — same as smart, face detection, object detection and corner points detection
  • smart_faces_objects — face detection, followed by object detection
  • smart_faces_points — face detection, followed by corner points detection
  • smart_objects_faces_points — object detection, followed by face detection, followed by corner points detection
  • smart_objects_faces — object detection, followed by face detection
  • smart_objects_points — object detection, followed by corner points detection
  • smart_points — corner points detection or manual region specified by offset parameter
  • smart_objects — object detection or manual region specified by offset parameter
  • smart_faces — face detection or manual region specified by offset parameter
  • :offsets — string, format: M%,N%, where M and N 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.

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 to normal.
  • lighter — ≈80% file size.
  • normal — ≈100% file size.
  • better — ≈125% file size.
  • best — ≈170% file size.
  • smart — Automatically set optimal image compression and format settings to preserve visual quality while minimizing the file size, content-aware.

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/