Documentation

Serving Images

Getting Started with imgix

Once your Source has been configured and deployed, you can begin making image requests to imgix. These requests differ slightly for each imgix Source type, but they all have the same basic structure:

https:// example.imgix.net imgix domain / products/desk.jpg path ? w=600&exp=1 query string

The hostname, or domain, of the imgix URL will have the form YOUR_SOURCE_NAME.imgix.net. In the above URL, the name of the Source is example, so the hostname takes the form of example.imgix.net. Different hostnames can be set in your Source by clicking Manage under the Domains header.

The path consists of any additional directory information required to locate your image within your image storage (e.g. if you have different subfolders for your images). In this example, /products/desk.jpg completes the full path to the image.

imgix’s parameters are added to the query string of the URL. In the above example, the query string begins with ?w=600 and the additional parameters are linked with ampersands. These parameters dictate how images are processed. In the above URL, w=600 specifies the width of the image and exp=1 adjusts the exposure setting.


Amazon S3 Sources

Each object in your S3 bucket has an Amazon hostname and prefix. Setting up an Amazon S3 Source involves the option of setting a specific S3 prefix. To process an image from your S3 bucket, you must replace the Amazon hostname and the S3 prefix with the imgix hostname. All other parts of the URL can remain the same.

An Amazon S3 Source connects your imgix Source securely to an existing S3 bucket. Suppose that the Amazon S3 URL is the following, with the S3 bucket name set to example-bucket and the S3 prefix set to example-prefix.

https://
s3-us-west-1.amazonaws.com Amazon Hostname
/
example-bucket bucket
/
example-prefix prefix
/
picture.jpg file name

When you set up your Source, you must enter the bucket name, so by default the imgix hostname will replace the Amazon S3 hostname and bucket name. If all of the images in your Source share the same prefix as well, you can define that in your Source and shorten the URL even further:

https://
example.imgix.net imgix domain
/
picture.jpg path

Web Folder Sources

A Web Folder Source connects your imgix Source to any folder with a publicly-addressable URL where you are hosting your images. Suppose that the URL of an image is the following:

http://
www.yourcompany.com original domain
/
images/examples/pic.jpg original path

If you set the Base URL of your Source as https://www.yourcompany.com/images/, you can replace this part of the URL with the imgix.net hostname. If the name of your imgix Source is example, the URL that serves the image at the URL above is:

https://
example.imgix.net imgix domain
/
examples/pic.jpg path

Web Proxy Sources

A Web Proxy Source allows your imgix Source to serve any image with a publicly-addressable URL. In order to serve an image through a Web Proxy Source, the URL of the original image first needs to be URI encoded. The encoded URL is added at the end of the Web Proxy hostname. Please note that all Web Proxy URLs need to be signed (see the Securing Images guide for more information about signing URLs.

If the Web Proxy source is called example and the URL of the image you are attempting to serve is:

http://www.this.com/pic.jpg original URL

The resulting URL will look like this (where the value of the s parameter is generated by the Secure Image tool or your code:

https://
example.imgix.net imgix domain
/
http%3A%2F%2Fwww.this.com%2Fpic.jpg original URL, encoded
?
s=V5kYnb7bdDaCfgeB signature

Applying Parameters

Once you have the base URL for your images set up, you can start applying Image URL API parameters to manipulate and serve your images to your specifications. We’ll demonstrate a good basic set to use, and you can see the full range of what’s available in the documentation. For these examples, the base URL will be:

http://assets.imgix.net/examples

Basic Parameter Example

For this example, let’s say you have an online magazine that’s being read on desktops, phones, tablets, and more. Each article has a header image that spans the full width of the page. Here’s what the base image for one such header might look like:

For all examples in this section (and in the documentation), click the image to view it in the Sandbox with the parameters applied. You can experiment with the other parameters there to see their effects.

Resizing and Cropping

On the article page, let’s assume your header is constrained to a 900×300pixel container for a wide, short banner. To fit the base image into that container, we’ll need to change the dimensions and crop some data from the top and bottom.

We’ve applied four parameters to adjust the image:

  • w=900&h=300: Sets the width and height to fit the container.
  • fit=crop: Tells imgix how to deal with the extraneous data caused by the change in dimensions.
  • crop=entropy: Tells imgix how to determine the origin point of the crop. The entropy value adjusts the origin point based on areas of high contrast (the swimmer) to position him in the center of the cropped image.

Automatic Content Negotiation and Enhancement

So far, so good—the image fits in the header container now. But it’s a bit dark, and even though the file size is much smaller than the original, it’s still quite heavy at 890kB. Let’s add some automatic adjustments to solve both of these issues.

By adding two of imgix’s auto settings and setting a lower value for q (quality) we’ve shrunk the file size by almost 99% to 35kB, and brightened the overall tone considerably. Here’s how that works:

  • auto=format: For browsers that support it, converts the image to the WebP format for better compression.
  • auto=enhance: Applies a set of image adjustments to improve brightness, contrast, and other settings.
  • q=60: Reduces the image quality slightly to improve compression (default is 75).

Because format and enhance are both valid values for auto, they can be chained together with a comma.

If you need the same image in another size, all you need to do is change the parameters to fit the new container. For example, if the article is also displayed in a list of articles, you might need this image as a thumbnail instead. By just changing the w and h values, you can easily generate this version as well.

Setting Default Parameters for Your Source

If you find that there is a set of parameters that works well across all or most of your image catalog, you can set them as defaults for your Source, so that they’re applied to all of your images automatically (you can override them on a per-image basis as needed). If you wanted to set up standard cropping based on the header image above, for example, you would add the fit and crop parameters as defaults in your Source:

Screenshot-Setting default parameters in Source

Note: The auto=format and ch parameters are not available for use as a default. See our blog post for more information about what you can do with default parameters.


Order of Operations

The order of operations is currently normalized within our system. You can list your parameters in any order within a URL and we will re-order them as follows when we receive an image request:

  1. Animated GIF Frame and PDF Page Selection
  2. Color and Contrast Adjustments
  3. Sizing, Cropping, and Rotation Operations
  4. Halftone, Blur, Pixelate Effects
  5. CSS Palette Extraction
  6. Text, Watermark, and Border Compositing

Next Steps

Resizing, cropping, and automatic content negotiation and enhancement are just the beginning of what you can do. Using imgix, you can overlay text, stylize images, apply masks, add borders and padding, and much more.

These transformations are all processed by imgix’s state-of-the-art architecture that ensures images are served quickly and with the highest quality.

Finally, all of this can be integrated easily into existing applications using our robust developer tools. To continue exploring how imgix can make serving images to your customers easier, faster, and more flexible. For details about all of the available parameters, read the API documentation, and to see solutions for specific problems and use cases, check out the Tutorials.