Data Types

Image Processing API

Scalable image REST API to resize, crop, convert, edit, and optimize images in real-time.

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

1 Upload your input

Firstly, your image must be uploaded or accessible to Bytescale:

Icon

Use the Bytescale Dashboard to upload a file manually.

Icon

Use the Upload Widget, Bytescale SDKs or Bytescale API to upload a file programmatically.

Icon

Use our external storage options to process external images.

2 Build your image URL

Build an image processing URL:

2a

Get the raw URL for your file:

https://upcdn.io/W142hJk/raw/example.jpg

2b

Replace "raw" with "image":

https://upcdn.io/W142hJk/image/example.jpg

2c

Add querystring parameters to control the output:

https://upcdn.io/W142hJk/image/example.jpg?w=800&h=600

3 View your image

To view your processed image, simply navigate to the URL from step 2 or include it in a webpage:

<img src="https://upcdn.io/W142hJk/image/example.jpg?w=800&h=600" />

HTTP Response

The HTTP 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.

Supported File Sources

Input files can be pulled from the following sources:

To create an external file source: create a folder in the Bytescale Dashboard and edit its storage settings.

Supported File Types

The Image Processing API can generate images from images, videos, and documents:

Supported Input Images

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)

  • HEIC

  • HEIF

  • JFIF

  • JP2

  • JPEG

  • JPF

  • PNG

  • RAW

  • SVG

  • TIFF (for multi-page TIFFs: use page to extract a specific page)

  • WebP (for animated WebPs: use page to extract a specific frame)

Use f to specify the output format. Default value is the input image's format if supported as an output format, else JPEG.

Supported Input Videos

The Image Processing API can generate video thumbnails from the following video inputs:

File Extension(s)Video ContainerVideo Codecs

.gif

No Container

GIF 87a, GIF 89a

.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

Bytescale supports up to 16384x16384 inputs for most video codecs. AVC (H.264) inputs are limited to 16384x8192.

Some codec profiles are not supported by Bytescale. It is worth noting that AVC (H.264) High 4:4:4 Predictive is currently not supported. We aim to provide a full list of supported profiles in the near future.

Use t to specify the time to extract the video thumbnail from (in seconds). Default value is t=auto.

Supported Input Documents

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.

Image Optimization API

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

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 processing 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:

1

Ensure your permanent cache is enabled: this will eliminate re-processing delays for subsequent requests to the same URL.

2

Consider using Bytescale's Extended Coverage CDN for lower-latency downloads from the Asia Pacific & Africa.

f=avif

Converts the image to AVIF.

Recommendation: use f=webp instead of f=avif. WebP transformations are significantly faster and produce equivalent results to AVIF.

f=gif

Converts the image to GIF.

f=jpeg

Converts the image to JPEG.

f=jpg

Alias for f=jpeg.

f=png

Converts the image to PNG.

f=webp

Converts the image to WebP.

Recommendation: use f=webp for all image outputs (where possible). WebP supports transparency and animation, provides great compression for both photographic and graphical imagery, and is supported by all modern web browsers.

f=blurhash

Converts the image to a BlurHash.

BlurHashes are short strings (6-166 chars long) that can be rendered as blurred image placeholders.

BlurHashes are designed to be stored in your database.

To render an image from a BlurHash:

You must use a BlurHash decoder (to convert a BlurHash to an image data URI).

You can decode BlurHashes either client-side or server-side (using a BlurHash decoder library).

You should use client-side decoding if your client-side code will be running at the time your blurred image needs to be displayed. This is the fastest way to show blurred images to your users, and uses the least amount of network resources. If your client-side code will not be running at the time you need to display blurred images (e.g. on initial page load for an HTML/JS webpage) then you can decode an initial set of images server-side, and send their data URIs back to the client in the initial page response.

You should not store decoded BlurHashes in your database: decoded BlurHashes are simply images, so can be quite large (e.g. ~20KB) compared to a BlurHash (~20B). Doing so would largely undo the benefits of using BlurHashes (i.e. you could use the blur param instead, and save the result as a data URI to your database).

Setting BlurHash quality:

The q parameter sets the number of color points used in the BlurHash.

Color points define the number of points in the blurred image that color radiates from.

Color points set by the q parameter are apportioned on the X and Y axis relative to the input image's aspect ratio. For example, when setting q=12 for an input image of 800x600, the resulting BlurHash will contain 4x3 color points.

Default is q=12 (this typically gives great results).

Increasing the q parameter increases the size of the BlurHash.

Increasing the q parameter does not necessarily increase the aesthetic of the BlurHash.

BlurHashes are base-83 strings that are safe for use in JSON and HTML (without requiring escaping).

f=meta

Returns metadata for the input image as a JSON object.

Includes: dimensions, rotation, mirroring, color profile, keywords, GPS coordinates, etc.

See the Image Metadata API docs for more information.

f=meta-out

Returns metadata for the output image as a JSON object.

Includes: dimensions, rotation, mirroring, color profile, etc.

See the Image Metadata API docs for more information.

f2=avif

Converts the image to AVIF when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).

f2=gif

Converts the image to GIF when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).

f2=jpeg

Converts the image to JPEG when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).

f2=jpg

Alias for f2=jpeg.

f2=png

Converts the image to PNG when f cannot be used (e.g. due to the 16383×16383 output limit for WebP).

f2=webp

Converts the image to WebP when f cannot be used.

q=<int>

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).

c=<int>

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.

Default: 60

Image Metadata API

Use the Image Metadata API to extract the dimensions, rotation, mirroring, color profiles, keywords, GPS coordinates, and other EXIF information from an image.

Instructions:

  1. Replace raw with image in your image URL.

  2. Append ?f=meta to the URL to return the input image's metadata.

  3. The result will be a JSON object (see below).

You can use ?f=meta-out to return the output image's metadata.

This can be useful for observing changes to ICC profiles and color spaces made via the Color Management API.

Example image metadata JSON response:

{
"dimensions": {
"width": 1500,
"height": 1000
},
"rotation": {
"degrees": 0,
"mirrorX": false,
"mirrorY": false
},
"size": {
"exif": 9540,
"icc": 557168,
"iptc": 9998,
"raw": 187636,
"tiffTagPhotoshop": 0,
"total": 781291,
"xmp": 16949
},
"exif": {
"applicationRecordVersion": "\u0000\u0000",
"colorMode": 3,
"colorSpace": 1,
"colorSpaceData": "RGB",
"createDate": "2022-09-22T14:49:03+01:00",
"creatorTool": "Adobe Photoshop 23.2 (Macintosh)",
"documentID": "adobe:docid:photoshop:0a99566f-a60d-744d-9f74-f614130ba392",
"exifImageHeight": 1000,
"exifImageWidth": 1500,
"imageHeight": 3630,
"imageWidth": 5445,
"history": [
{
"action": "created",
"instanceID": "xmp.iid:c6cc9587-bde2-41ad-a103-2795a768652e",
"softwareAgent": "Adobe Photoshop 23.2 (Macintosh)",
"when": "2022-09-22T14:49:03+01:00"
},
{
"action": "saved",
"changed": "/",
"instanceID": "xmp.iid:4f02d905-a8ca-4eae-ad14-cabd90a71105",
"softwareAgent": "Adobe Photoshop 23.2 (Macintosh)",
"when": "2022-09-22T14:52:23+01:00"
}
],
"iccProfile": "Display",
"instanceID": "xmp.iid:417ea026-b3be-4355-9eb8-a3817710410c",
"keywords": [
"bjølsen",
"oslo",
"sommer",
"sushi rose bjølsen"
],
"metadataDate": "2022-09-22T14:52:23+01:00",
"modifyDate": "2022-09-22T14:52:23.000Z",
"orientation": 1,
"originalDocumentID": "xmp.did:c6cc9587-bde2-41ad-a103-2795a768652e",
"primaryPlatform": "Apple Computer",
"profileCMMType": "Apple Computer",
"profileClass": "Monitor",
"profileConnectionSpace": "XYZ",
"profileCopyright": "Copyright Apple Inc., 2022",
"profileCreator": "Apple Computer",
"profileDateTime": "2022-09-16T07:23:30.000Z",
"profileDescription": "Display",
"profileDescriptionML": [
{
"country": "US",
"lang": "en",
"text": "BenQ PD3220U"
}
],
"profileFileSignature": "acsp",
"profileVersion": "2.1.0",
"renderingIntent": "Relative Colorimetric",
"resolutionUnit": "inches",
"software": "Adobe Photoshop 23.2 (Macintosh)",
"xResolution": 144,
"yResolution": 144
}
}

The size field contains the image's size in bytes, broken down into its various components:

  • The size.total field shows the sum of the other fields, and represents the total file size of the image in bytes.

  • The size.raw field shows the size of the raw image data.

  • The remaining fields represent the size of the image's metadata components in bytes.

Image Resizing API

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

w=<int>

Width to resize the image to (in pixels).

wp=<int>

Width override parameter for portrait images.

If specified, allows you to use w for landscape images and wp for portrait images.

If not specified, then w will be used for all images.

h=<int>

Height to resize the image to (in pixels).

hp=<int>

Height override parameter for portrait images.

If specified, allows you to use h for landscape images and hp for portrait images.

If not specified, then h will be used for all images.

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

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

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

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

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Image Cropping API

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

crop-x=<int>

The X position within the image to crop from.

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

crop-y=<int>

The Y position within the image to crop from.

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

crop-w=<int>

The width of the crop area.

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

crop-h=<int>

The height of the crop area.

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

Color Management API

You can optionally use the Color Management API to control the color models and ICC profiles used in your output images.

By default, Bytescale converts all images to sRGB and strips ICC profiles to produce web-optimized images.

If you prefer, you can use the parameters below to retain ICC profiles, convert to alternative ICC profiles, and convert to alternative color models (such as RGB -> CMYK for printing).

cm=rgb

Returns the image using the RGB color model, performing a color model conversion on the input image if necessary.

Uses the sRGB color space.

Recommended for displaying images on web pages and in mobile applications.

This is the default setting.

cm=cmyk

Returns the image using the CMYK color model, performing a color model conversion on the input image if necessary.

Uses a generic CMYK color space.

Recommended for saving images to be printed.

cm=gray

Returns the image using the grayscale color model, performing a color model conversion on the input image if necessary.

Uses a generic grayscale color space.

cm=keep

Returns the image in the input image's color model (if supported by the output image format).

icc=strip

Removes the ICC profile from the output image.

Recommended for displaying images on web pages and in mobile applications. Modern browsers assume images use sRGB when no ICC profile is present, which allows images to be saved in sRGB without an embedded ICC profile to reduce file size.

This is the default setting.

icc=embed

Automatically adds an ICC profile to the output image.

The ICC profile is chosen based on the output image's color model:

RGB & Grayscale: a web-safe sRGB ICC profile will be embedded. Adds 6KB to the image's file size.

CMYK: the U.S. Web Coated (SWOP) v2 ICC profile will be embedded. Adds 557KB to the image's file size.

For web pages and mobile apps, we recommend using icc=strip and cm=rgb (both default values) as these result in smaller images.

icc=keep

Retains the ICC profile from the input image.

If the input image lacks an ICC profile, or if the input image's color model does not match the cm parameter, then icc=embed will be used.

icc=set

Adds the ICC profile specified by the iccPath parameter:

The iccPath parameter must point to a valid .icc file in your Bytescale account and must start with a / character.

The cm parameter must specify the color model of the ICC profile.

Requires: iccPath

iccPath=<string>

Adds the specified ICC profile to the image:

The iccPath parameter must point to a valid .icc file in your Bytescale account and must start with a / character.

The cm parameter must specify the color model of the ICC profile.

Image Canvas API

Use the Image Canvas API to extend the output image's dimensions.

Default behavior:

  • Resize parameters (e.g. w, h, fit, etc.) are applied to the input image first, and then the canvas is extended.

  • Layer parameters (e.g. text, image, gravity, etc.) are applied after the canvas is extended.

Overriding this behavior:

You can override this behavior by reordering your querystring parameters and adding a flush=true parameter. This will cause all parameters before the flush=true to be applied first; all subsequent parameters will then be applied on the resulting image.

Examples:

  • Example 1: You can specify ?extend=50&w=800&h=600&fit=crop to resize the image to 800x600 first, and then apply a 50-pixel border, resulting in a 900x700 image.

  • Example 2: You can specify ?extend=50&flush=true&w=800&h=600&fit=crop to have the border applied before the resize operation, meaning the resulting image will be 800x600, with a border size that's dependent on the input image's size and aspect ratio (as the border will be resized and cropped as part of the image).

extend=<int>

Adds pixels to all edges of the image.

extend-color=<string>

The color to use for the pixels added by the extend parameter(s).

extend-x=<int>

Adds pixels to the left and right edges of the image.

extend-y=<int>

Adds pixels to the top and bottom edges of the image.

extend-top=<int>

Adds pixels to the top edge of the image.

extend-bottom=<int>

Adds pixels to the bottom edge of the image.

extend-left=<int>

Adds pixels to the left edge of the image.

extend-right=<int>

Adds pixels to the right edge of the image.

bg=<string>

Sets the background color for output images that do not support transparent pixels, such as JPEGs.

This is useful when the input image has transparent pixels or when transparent pixels are introduced through transformations like rotations.

Default: #ffffff

bg-force=<bool>

Applies the background color specified by the bg parameter to output images with transparency support, such as WebP, AVIF, GIF, and PNG, else transparent pixels will be retained.

Default: false

Image Adjustment API

Use the Image Adjustment API to apply adjustments and filters to the underlying image.

blur=fast

Blurs the image by an automatic amount (fastest).

blur=<int>

Blurs the image by the given amount.

sharpen=fast

Sharpens the image by an automatic amount (fastest).

sharpen=<int>

Sharpens the image by the given amount.

brightness=<int>

Adjusts the brightness of the image.

Note: brightness is multiplicative whereas lightness is additive.

lightness=<int>

Adjusts the lightness of the image.

Note: brightness is multiplicative whereas lightness is additive.

hue=<int>

Adjusts the hue of the image.

saturation=<int>

Adjusts the saturation of the image.

grayscale=true

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

negate=true

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

negate-alpha=<bool>

Negates the alpha channel in addition to the RGB channels.

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=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.

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.

Image Layer API

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.

image=<string>

Renders another image or SVG over the image.

To use: specify the "file path" attribute of another image Applies the trim specified by ts and/or `te`as the query parameter's value.

Text Layer API

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.

text=<string>

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

color=<string>

Sets the text color.

Requires: text

font=<string>

Sets the font to use for the text.

To use: specify the "file path" attribute of a TTF file as the query parameter's value.

Requires: text

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

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

font-weight=<int>

Sets the font weight for the text.

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

Requires: text

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

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

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

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

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 behavior.

layer-w=<int>

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

layer-h=<int>

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

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=<int>

Sets the X position for the image or text.

Requires: image or text

layer-y=<int>

Sets the Y position for the image or text.

Requires: image or text

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

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-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

align=center

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

align=left

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

align=right

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

valign=bottom

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

valign=center

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

valign=top

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

padding=<int>

Sets the padding for the image or text.

Requires: image or text

padding-x=<int>

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

Requires: image or text

padding-y=<int>

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

Requires: image or text

padding-top=<int>

Sets the top padding for the image or text.

Requires: image or text

padding-bottom=<int>

Sets the bottom padding for the image or text.

Requires: image or text

padding-left=<int>

Sets the left padding for the image or text.

Requires: image or text

padding-right=<int>

Sets the right padding for the image or text.

Requires: image or text

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

premultiply=<bool>

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

Requires: image or text

Page Extraction API

The Page Extraction API allows you to specify which page(s) from a PDF, GIF, or TIFF to extract.

For PDF and TIFF inputs, if no page parameter is specified, then the first page will be extracted.

For animated GIF inputs, if no page parameter is specified and f=webp or f=gif are specified, then the output will also be animated. If the f parameter does not support animation (e.g. f=jpg) then the first page will be extracted.

page=<int>

The page to extract from the multi-page input file (PDF, GIF, TIFF).

Number is zero-based.

page-count=<int>

The number of pages to extract from the multi-page input file (PDF, GIF, TIFF).

You may specify -1 to extract all pages.

Video Thumbnail API

Use the Video Thumbnail API to generate video thumbnails (aka video poster images) from a supported video file type.

t=auto

Gets a thumbnail towards the start of the video.

When batch=true then t=auto will be interpreted as t=0.

Default: t=auto

t=<number>

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 - 86399 with up to two decimal places. To provide frame accuracy for video inputs, decimals will be interpreted as frame numbers, not milliseconds.

Important: thumbnails take considerably longer to generate further into the video compared to at the start, for some video formats.

Default: t=auto

batch=false

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)

10 seconds

Default: batch=false

batch=true

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)

10 seconds

Default: batch=false

duration=<number>

Specifies the duration the thumbnails should cover in seconds. (Only applicable when batch=true.)

Supports numbers between 1 - 86399 with up to two decimal places. To provide frame accuracy for video inputs, decimals will be interpreted as frame numbers, not milliseconds.

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

fps=<number>

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

ac=<string>

Deprecated: please use bg instead.

async=<bool>

Runs the transformation as an asynchronous transformation, which extends the transformation timeout from 55 seconds to 400 seconds.

When async=true the result will be a JSON payload of type JobSummary: the status field will change to Succeeded once the transformation completes, at which point the summary field will contain a URL to the transformed image (i.e. the "artifact").

If you prefer, when using GET requests, you can initiate asynchronous transformations by requesting the artifact URL directly (the artifact path is the same for all transformations). A 404 status code will be returned initially along with a JobSummary response. A 200 status code will be returned when the transformation succeeds, with the image as the HTTP response.

Tip: make sure w and/or h are present on the URL. If they are not, then you may experience timeouts for extremely large images.

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 behavior.

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°).

input=auto

Automatically detect the input file type based on its file extension (default).

input=image

Always treat the input file as an image or document.

input=video

Always treat the input file as a video.

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: