close anchor

Files API

Introduction

The Files API provides a sophisticated set of tools for converting, transforming, and optimizing files in Elebase Projects.

Our current API supports URL-based transformations on image files, but in the coming months it will be extended to support other formats including PDF documents, geospatial data files, Markdown/HTML files, and more. If there is a feature or format you would like us to support in the future, we want to hear about it, so email us any time.

Image files

Base URL
https://cdn.elebase.io
Order of operations

While URL parameters can be provided in any order, the operations performed as a result of these parameters always occur in the same sequence. This sequence is useful to know if, for example, an image needs to be cropped to a specific size and position, then rotated 90°. Since rotation always occurs before cropping, the crop position specified would need to account for the fact that the rotation has already occurred.

  1. Filter (adjustments, effects)
  2. Rotate (flipping, rotation)
  3. Resize (cropping, scaling)
  4. Sharpen
  5. Encode (compression, interlacing)
Supported formats

The following image formats support all transformation parameters:

  • PNG - Full support for 8-bit, 24-bit, and 32-bit formats.
  • JPEG - Full support for standard and progressive (PJPEG) formats.

Size

Width w

Sets the image width in pixels.

<img src="https://cdn.elebase.io/image.jpg?w=500">

Original:
2000x1600 • 709 KB
Modified:
500x400 • 45 KB

Height h

Sets the image height in pixels.

<img src="https://cdn.elebase.io/image.jpg?h=300">

Original:
2000x1600 • 709 KB
Modified:
375x300 • 28 KB

Fit fit

Controls how the image is fitted to its target dimensions. Use one of the following values:

  • contain (default): Resizes the image to fit within the specified width and height boundaries without cropping or altering the aspect ratio.
  • max: Same as contain, but will not upscale the image if it is smaller than the output dimensions.
  • crop: Resizes the image proportionally to fill the target dimensions and crops any excess image data. The default behavior is to crop relative to the image's center point. To override this, append a crop position:
    • -top-left
    • -top
    • -top-right
    • -right
    • -bottom-right
    • -bottom
    • -bottom-left
    • -left
<img src="https://cdn.elebase.io/image.jpg?w=300&h=500&fit=crop-bottom-right">

Original:
2000x1600 • 709 KB
Modified:
300x500 • 30 KB

Device pixel ratio dpr

Sets the device pixel ratio to apply when resizing. The device pixel ratio is used to convert easily between device independent pixels and device pixels. Use this parameter to display images at optimal size on high-DPI displays. Requires w and/or h parameters. Use values between 1 and 8.

Note: The srcset attribute is presently one of the best ways to take advantage of this parameter on the web. It's quick to implement and has a polyfill for backward compatibility.

<img
  srcset="https://cdn.elebase.io/image.jpg?w=400 1x,
          https://cdn.elebase.io/image.jpg?w=400&dpr=2 2x,
          https://cdn.elebase.io/image.jpg?w=400&dpr=3 3x"
  src="https://cdn.elebase.io/image.jpg?w=400"
>

Original:
2000x1600 • 709 KB
Modified:
400x320 • 30 KB • @1x
800x640 • 97 KB • @2x
1200x960 • 191 KB • @3x

Crop crop

Cuts out a rectangular portion of the image prior to any other resize operations. The value provided should be a set of comma-separated integers in the following format: {width},{height},{x},{y}. The x and y coordinate values (both optional) allow precise control over where the top-left corner of the rectangular cutout is positioned. A value of 0 for both x and y, for instance, would position the cutout at the upper-left corner of the source image. By default, the cutout will be horizontally and vertically centered.

<img src="https://cdn.elebase.io/image.jpg?crop=500,500,600,150">

Original:
2000x1600 • 709 KB
Modified:
500x500 • 31 KB


Rotation

Flip flip

Reflects the image horizontally and/or vertically. Use a value of x , y , or xy to flip the image horizontally, vertically, or on both axes, respectively.

<img src="https://cdn.elebase.io/image.jpg?w=700&flip=x">

Original:
2000x1600 • 709 KB
Modified:
700x560 • 79 KB • flipped horizontally

Rotate rot

Rotates the image counter-clockwise by a given angle in degrees. Use values between 0 and 360 or a value of auto to adjust the image orientation automatically based in its exif data, if available.

<img src="https://cdn.elebase.io/image.jpg?w=700&rot=45">

Original:
2000x1600 • 709 KB
Modified:
700x700 • 70 KB • rotated 45°


Adjustments

Brightness bri

Adjust the brightness of the image. Use values between -100 and 100.

<img src="https://cdn.elebase.io/image.jpg?w=700&bri=-10">

Original:
2000x1600 • 709 KB
Modified:
700x560 • 78 KB • darkened 10%

Contrast con

Adjust the contrast of the image. Use values between -100 and 100.

<img src="https://cdn.elebase.io/image.jpg?w=700&con=-10">

Original:
2000x1600 • 709 KB
Modified:
700x560 • 85 KB • contrast reduced 10%

Sharpness sharp

Adjust the sharpness of the image. Use values between 0 and 100.

<img src="https://cdn.elebase.io/image.jpg?w=700&sharp=10">

Original:
2000x1600 • 709 KB
Modified:
700x560 • 103 KB • sharpened 10%


Effects

Pixelate pix

Applies a pixelation effect to the image. Use values between 0 and 100 to control the block size.

<img src="https://cdn.elebase.io/image.jpg?w=700&pix=15">

Original:
2000x1600 • 709 KB
Modified:
700x560 • 59 KB • pixelated with 15px block size

Color col

Applies a color filter to the image. The following values are supported:

  • gray or grey
  • sepia
<img src="https://cdn.elebase.io/image.jpg?w=700&col=gray">

Original:
2000x1600 • 709 KB
Modified:
700x560 • 69 KB • grayscale filter


Optimizations

Quality q

Defines the output quality of the image (only works on JPEGs). Use values between 0 and 100. Lower values yield smaller file sizes at the expense of image quality. By default, a setting of 90 will be used if any transformations are performed. Original source images are never compressed.

Note: JPEG files can only have their quality decreased. A low quality source image will not be improved by setting a high value (e.g. 100) for this parameter. For best results, always upload images to a Project at maximum quality and use this parameter in websites or applications to optimize them for fast delivery.

<img src="https://cdn.elebase.io/image.jpg?q=50">

Original:
2000x1600 • 709 KB
Modified:
2000x1600 • 185 KB • 50% quality

Interlacing i

Determines whether the image should be output in interlaced or standard encoding mode. If the image is a JPEG and interlaced mode is enabled (default behavior when transformations are performed), it will be encoded as a progressive JPEG. Use a value of true to enable interlaced mode or false to use standard encoding.

Note: Progressive JPEGs provide a number of advantages over traditional JPEGs including potentially smaller file sizes and faster perceived load times. When a progressive JPEG is rendered, only 15% of the image needs to be downloaded before a preview can be displayed. As the remainder of the image data is downloaded, the image fills in and becomes progressively sharper, giving an impression of much quicker loading.

<img src="https://cdn.elebase.io/image.jpg?i=true">

Original:
2000x1600 • 709 KB
Modified:
2000x1600 • 459 KB • progressive

Register for an Invitation
Thank you!
We'll be in touch.
First Name*
Last Name*
(optional) Business Name
Role*
Email*