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:

Use the Bytescale Dashboard to upload a file manually.

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

Use our external storage options to process external images.

2 Build your image URL

Build an image processing URL:

Get the raw URL for your file:

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

Replace "raw" with "image":

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

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 (Animated GIFs: use page to extract a specific frame.)
HEIC
HEIF
JFIF
JP2
JPEG (Progressive-scan JPEGs: up to 256 million input pixels per image are supported. Baseline JPEGs can be much larger.)
JPF
PNG
RAW
SVG
TIFF (Multi-page TIFFs: use page to extract a specific page.)
WebP (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 Container	Video 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
.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.

The input PDF file must not exceed 1GB.

Image Optimization API

Use the Image Optimization API to reduce the file size of your images.

Reducing your image file sizes

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.

Reducing your processing time

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.

Measuring processing time

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

Further performance optimizations

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 Bytescale's Extended Coverage CDN for lower-latency downloads from the Asia Pacific & Africa.

Output Format f

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.

Output Format Fallback f2

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.

Quality q

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

Compression c

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:

Replace raw with image in your image URL.
Append ?f=meta to the URL to return the input image's metadata.
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.

Width w

w=<int>

Width to resize the image to (in pixels).

Width (Portrait) wp

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.

Height h

h=<int>

Height to resize the image to (in pixels).

Height (Portrait) hp

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

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