Media Optimizer configuration

Cloudinary's Media Optimizer simplifies the process to optimize and deliver high-quality media with high performance, low latency and massive scalability.

This page explains how to configure your Media Optimizer setup by introducing you to the key concepts, providing some examples showing what to configure in different situations and giving detailed instructions on:

Key concepts

  • Media source: Provides details about your media storage locations and how to access them.
  • Delivery profile: Identifies a set of media assets by their delivery URL, and defines how they are delivered based on the source of the original media and applied transformations. Delivery profiles ultimately bring together all the different configuration components.
  • Mapping function: Determines media transformations that are already being applied to your media sources through existing delivery platforms. Mapping functions enable Media Optimizer to apply the same transformations when delivering the media from its original source.
  • Domain: The base part of your Media Optimizer URL. By default this is https://<cloud_name>.mo.cloudinary.net, but you can use your own domain by setting up a custom domain.
  • Path prefix: Set in the delivery profile, the path prefix can be thought of as an extension to the domain, which can be used to categorize your media. This allows you to create more than one delivery profile for the same domain, and treat some media differently to others, as shown in Example 7. The path prefix is included in your Media Optimizer URLs, but it is not a folder in your media source.
  • Media Optimizer URL: (Also known as the delivery URL). The URL required to deliver media from your media source through Media Optimizer. It combines the domain and any path prefix set in the delivery profile, with the path to the media in the media source. If you already use a platform that optimizes your media through URL parameters, you can keep these in your Media Optimizer URL and Media Optimizer will map them to Cloudinary transformations.

Configuration examples

The objective of the Media Optimizer configuration is to start optimizing the delivery of your media with minimal changes to your site. It should allow you to keep the media URLs on your site either completely unchanged, or needing only minor updates. This is achieved by defining media sources and mapping functions that are brought together in a delivery profile, determining how to treat each media URL request.

There are many different ways to configure Media Optimizer, depending on your situation.

  • If you are implementing a new website, or already have a website on which you are displaying un-optimized media, then the configurations shown in Example 1, Example 2, or Example 3 will get you started.
  • If you currently store your media in a Cloudinary account, Example 4 shows how to set up a Cloudinary media source, and choose the right mapping function.
  • If you want publicly available media to be fetched through Media Optimizer, see Example 5.
  • If you already have a website up and running, and are using a different platform for optimization, Example 6 shows how to map those optimizations to Media Optimizer transformations.
  • If you want to treat some media differently to others, check out Example 7.

The configuration is very flexible, so you can use a combination of the above examples, and others, to cater for the needs of your site.

The following examples assume a cloud name of mycloud.

Example 1: Using the default domain and a web address media source

This is the most basic example, which is covered by the Get started guide. Whether you have an existing site, or are building a new one, this configuration will get you up and running quickly, though later you may want to take a more nuanced approach, such as in Example 7.

Original URL Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Required action:

  1. Create a media source:
  2. Ensure your delivery profile includes:
    • Domain: https://mycloud.mo.cloudinary.net (Default)
    • Media Source: as created
    • Mapping Function: Media Optimizer (Default)
  3. On your site, replace https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

Example 2: Using a custom domain and a web address media source

This is the same as Example 1, but uses a custom domain instead of the default domain. Use this configuration to serve media from your domain, with no changes to your site.

Original URL Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg https://www.mydomain.com/rest/of/the/path.jpg

Required action:

  1. Create a media source:
  2. Create a custom domain. This involves creating a support request to set up the DNS routing required for you to use your own domain.
    • Domain: https://www.mydomain.com
  3. Create a delivery profile:
    • Domain: https://www.mydomain.com
    • Media Source: as created
    • Mapping Function: Media Optimizer (Default)

Example 3: Using the default domain and an AWS S3 media source

Similar to Example 1, this is the most basic example, but with media stored in an AWS S3 bucket. In the example shown, https://www.mydomain.com is the proxy used to serve media from the S3 bucket, s3://bucket_name/bucket_folder/rest/of/the/path.jpg.

Original URL Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Required action:

  1. Create a media source:
    • Type: AWS S3
    • Bucket Name: bucket_name
    • Bucket Folder: bucket_folder
    • Access Key and Secret Key: as appropriate
  2. Ensure your delivery profile includes:
    • Domain: https://mycloud.mo.cloudinary.net (Default)
    • Media Source: as created
    • Mapping Function: Media Optimizer (Default)
  3. On your site, replace https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

Example 4: Using the default domain and a Cloudinary media source

In this example, the media source is Cloudinary. As Media Optimizer does not come with Cloudinary storage, this example assumes the user has an existing Cloudinary account (with cloud name demo), and perhaps only uses optimization features, so wants to migrate to Media Optimizer, leaving their assets stored in Cloudinary.

The example shows transformations being applied to resize the image (c_fill,h_200,w_200). These transformations are interpreted by the Programmable Media mapping function to map to the equivalent transformations in Media Optimizer.

Original URL Media Optimizer URL
https://res.cloudinary.com/demo/image/upload/c_fill,h_200,w_200/docs/shoes https://mycloud.mo.cloudinary.net/image/upload/c_fill,h_200,w_200/docs/shoes

Required action:

  1. Create a media source:
  2. Create a delivery profile:
    • Domain: https://mycloud.mo.cloudinary.net (Default)
    • Media Source: as created
    • Mapping Function: Programmable Media
  3. On your site, replace https://res.cloudinary.com/demo with https://mycloud.mo.cloudinary.net.

Example 5: Using the default domain and an HTTP proxy media source

In this example, the media source is a publicly accessible HTTP URL. You can use this configuration for media on your site that you don't own, for example, to fetch social media profile pictures.

Original URL Media Optimizer URL
http://www.mydomain.com/rest/of/the/path.jpg https://mycloud.mo.cloudinary.net/http://www.mydomain.com/rest/of/the/path.jpg

Required action:

  1. Create a media source:
  2. Create a delivery profile:
    • Domain: https://mycloud.mo.cloudinary.net (Default)
    • Media Source: as created
    • Mapping Function: Media Optimizer (Default)
  3. On your site, prefix your URLs with https://mycloud.mo.cloudinary.net/.

Example 6: Mapping custom transformations in the original URL

Similar to Example 1, this example uses the default domain and a web address media source, but URLs can include optimization parameters from a different platform (e.g. size=small).

Original URL Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg?size=small https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg?size=small

Required action:

  1. Create a media source:
  2. Create a mapping function:
  3. Create a delivery profile:
    • Domain: https://mycloud.mo.cloudinary.net (Default)
    • Media Source: as created
    • Mapping Function: as created
  4. On your site, replace https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

Example 7: Using two delivery profiles and a web address media source

Depending on your site, you may find that you need a hybrid configuration, whereby some of the media on your site can be delivered with low quality settings, saving more bytes, whereas other media needs high quality settings. You can achieve this using more than one delivery profile.

Original URL Media Optimizer URL
https://www.mydomain.com/rest/of/path/hero.jpg https://mycloud.mo.cloudinary.net/high-quality/rest/of/path/hero.jpg
https://www.mydomain.com/rest/of/path/thumb.jpg https://mycloud.mo.cloudinary.net/low-quality/rest/of/path/thumb.jpg

Required action:

  1. Create a media source:
  2. Create a transformation for high quality:
    • Quality: Auto:Best
  3. Create a transformation for low quality:
    • Quality: Auto:Low
  4. Create a delivery profile for high quality:
    • Domain: https://www.mydomain.com
    • Path Prefix: high-quality
    • Media Source: as created
    • Default Transformation: select the named transformation as created for high quality
    • Mapping Function: Media Optimizer (Default)
  5. Create a delivery profile for low quality:
    • Domain: https://www.mydomain.com
    • Path Prefix: low-quality
    • Media Source: as created
    • Default Transformation: select the named transformation as created for low quality
    • Mapping Function: Media Optimizer (Default)
  6. On your site, replace https://www.mydomain.com with one of the following, depending on how you want that asset to be delivered:
    • https://mycloud.mo.cloudinary.net/high-quality
    • https://mycloud.mo.cloudinary.net/low-quality

Create a media source

Media sources provide details about your media storage locations and how to access them. You can create more than one media source if you store your media assets in multiple locations, and reference them in one or multiple delivery profiles.

To create a media source:

  1. In the Media Optimizer console, navigate to Configuration > Media Sources and click Add New.
  2. Complete the form:
  3. Click Save.

Types of media source

Media Optimizer supports a number of types of media source, as described in the following sections.

Note
If your media storage is not covered by any of the types listed, please contact support.

Cloudinary

If your media is stored in a Cloudinary account/sub-account that has a media library, your Media Optimizer sub-account must be part of the same overall account to use this option (each will have different cloud names). If the two accounts are not part of the same overall account you can use the Web address type instead.

For an asset stored at:

https://res.cloudinary.com/demo/image/upload/rest/of/the/path

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/image/upload/rest/of/the/path

Cloudinary settings
Setting Description
Storage Cloud Name The cloud name of the Cloudinary account where your media is stored. It must share the same overall Cloudinary account as the Media Optimizer sub-account.

Web address

Use the Web Address type when your media is stored on an HTTP accessible web server (most likely owned and maintained by yourself).

For an asset stored at:

http://www.mydomain.com/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Web address settings
Setting Description
URI Base The full URL of the web server (including http:// or https://).
Headers Advanced option for specifying headers in key/value pairs to include in the fetch request, for authentication or authorization purposes.

Example:
Key: Authorization
Value: Bearer {{var.token}}

{{var.token}} is an example of an interpolated variable, defined in the mapping function code.
URI Template Advanced option for specifying parameters to include in the fetch request. You can use interpolated variables that are defined in the mapping function code. For an example, see URI template.

HTTP proxy

Use the HTTP proxy type to fetch media from a publicly accessible HTTP URL.

For an asset stored at:

http://www.mydomain.com/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/http://www.mydomain.com/rest/of/the/path.jpg

HTTP proxy settings

There are no settings associated with the HTTP proxy type.


AWS S3

Use the AWS S3 type to fetch your media from an AWS S3 storage bucket.

For an asset stored at:

s3://<bucket_name>/<bucket_folder>/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

AWS S3 settings
Setting Description
Bucket Name The name of the S3 bucket.
Bucket Folder The bucket containing your media files.
Access Key The access key ID required to read from your S3 bucket.
Secret Key The secret access key required to read from your S3 bucket.
URI Template Advanced option for specifying parameters to include in the fetch request. You can use interpolated variables that are defined in the mapping function code. For an example, see URI template.

Google storage

Use the Google Storage type to fetch your media from a Google storage bucket.

For an asset stored at:

gs://<bucket_name>/<bucket_folder>/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Google storage settings
Setting Description
Bucket Name The name of the Google Storage bucket.
Bucket Folder The bucket containing your media files.
Service Account Key The JSON file downloaded from the keys page for your service account.
URI Template Advanced option for specifying parameters to include in the fetch request. You can use interpolated variables that are defined in the mapping function code. For an example, see URI template.

Create a mapping function

Mapping functions are used to identify media transformations that are already being applied to your media sources through existing delivery platforms. They enable Media Optimizer to apply the same transformations when delivering the media from its original source.

There are two mapping functions created by default:

  • Media Optimizer: This mapping function caters for transformation parameters added as a query string to the delivery URL, for example:
    https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg?tx=w_500,h_500,c_fit
  • Programmable Media: This mapping function caters for transformation parameters within a URL, as they would be if your media source was Cloudinary, for example:
    https://mycloud.mo.cloudinary.net/image/upload/w_500,h_500,c_fit/v1/sample.jpg

Both of these mapping functions cater for the Media Optimizer supported transformations.

You can provide your own custom mapping function to cater for any non-Cloudinary transformations.

To create a mapping function:

  1. Navigate to Configuration > Mapping Functions and click Add New.
  2. Complete the form:
    • Mapping Function Name: Enter a name for the mapping function.
    • Mapping Function Code: Enter here a JavaScript function. For details, see Mapping function code.
  3. Click Save.

Mapping function code

Mapping functions require JavaScript code to analyze incoming media URLs, extract transformations and determine the path to the highest quality original media.

As mapping functions are an advanced concept, our support team are on hand to help you create any that you need.

Signature

The expected signature of the function is:

Copy to clipboard
function map(request, environment) {
  ...
}

The request parameter is an object that represents the delivery URL and the context in which it was requested. It contains the following attributes:

Attribute Description Example
raw_url The full raw delivery URL. https://myhost.com/a/b/c.jpg?v=1&p=2
host The host of raw_url. myhost.com
path The path of raw_url. a/b/c.jpg
query A hash of string => string[] representing the query part of raw_url. {"v" => ["1"], "p" => ["2"]}
headers A hash of string => string representing the request headers of the original request. {"Authorization" => "Basic ABchZGRpbjpvcGVuc2VzYW1l"}

The environment parameter is an object that represents the delivery URL context for the invocation. It contains the following attributes:

Attribute Description
defaultTransformation The transformation defined in the delivery profile.
options A hash of string => string that represents the mapping function options.

Outputs

The output is a hash of string => string with the following keys:

Key Description Example
media_key A globally unique identifier for the media within Cloudinary's storage and cache. a/b/c.jpg
fwd_key Optional. An identifier for the media within a media source. By default, fwd_key and media_key are identical, but they could be different if, for example you wanted to map two different sources to the same Cloudinary cache entry. a/b/c.jpg
transformation The Cloudinary transformation. w_100,f_auto
resource_type The type of resource. image, video or raw
media_source_template_variables A hash of string => string that may be used by the media source URI Template field. {"timestamp" => "1612733077"}

Mapping function code example

Here is an example of code used in a mapping function. In the request URL there are query parameters that control the dimensions of the delivered image. The code maps these query parameters to Cloudinary transformation parameters and Media Optimizer then adds these transformations to the default transformation that's specified in the delivery profile.

Copy to clipboard
function map(request, environment) {
  let transformation = environment.defaultTransformation;
  if (request.query.width && request.query.height) {
    transformation += `w_${request.query.width},h_${request.query.height},c_limit/`;
  } else if (request.query.size) {
    switch(request.query.size) {
      case 'small':
        transformation += "w_150,h_100,c_fit/";
        break;
      case 'medium':
        transformation += "w_360,h_240,c_fit/";
        break;
      case 'large':
        transformation += "w_720,h_480,c_fit/";
        break;
    }
  }
let path = request.path;
    if (environment.pathPrefix.length > 0) {
        path = path.slice(`${environment.pathPrefix}/`.length);
    }
  return {
    fwd_key: path,
    media_key: request.path,
    transformation,
    resource_type: 'image',
  }
}

URI template

Variables defined in your mapping function can be used in the URI Template field in your media source definition.

For example:

{{fwd_key}}?ts={{media_source_template_variables.timestamp}}&s={{media_source_template_variables.signature}}

Create a custom domain

If you have your own domain name that you want to use instead of Media Optimizer's default domain (https://<cloud_name>.mo.cloudinary.net), you can create a custom domain.

To create a custom domain:

  1. Navigate to Configuration > Domains and click Add New.
  2. Complete the support request form, specifying the name of the domain you want to use.

The support team will add the domain to your configuration and set up the DNS routing required.

Create a delivery profile

Delivery profiles identify a set of media assets by their delivery URL, and define how they are delivered based on the source of the original media and defined transformations. Each delivery profile brings together one or more media sources, a mapping function, a domain and a transformation.

To create a delivery profile:

  1. Navigate to Configuration > Delivery Profiles and click Add New.
  2. Complete the form:
    • Delivery Profile Name: Enter a name for the delivery profile.
    • Delivery Profile URL: Set the domain and path prefix to define the base URL that identifies media belonging to the delivery profile.
    • Media Sources: Select one or more media sources that you have created.
    • Default Transformation: Select the transformation to apply to all media in the profile. The transformation is ignored for any raw files belonging to this delivery profile.
    • Mapping Function: Select the mapping function that should be used to extract transformations.
    • Default Media Type: Select the media type to default to if the mapping function code fails to identify the type from the extension.
    • Security: Enable the Allow only named transformations setting to block any URLs that contain transformations other than named transformations.
  3. Click Save.

Enable a delivery profile

After creating a delivery profile, you need to enable it to start optimizing your media delivery through it.

To enable a delivery profile:

  1. Navigate to Configuration > Delivery Profiles.
  2. Select the delivery profile to enable.
  3. Select Enable Delivery Profile from its kebab menu.

Default delivery profile

Test your setup

To test your setup, choose a Media Optimizer URL for a media file that you want to deliver through your site. The structure of your Media Optimizer URLs depends on your setup - you can see some examples in Configuration examples.

Enter the URL into a browser and check that it returns an image or a video.

If you get an error, ensure you have one or more delivery profile enabled. You can also check out troubleshooting.

Troubleshooting

When testing Media Optimizer URLs you may encounter errors. There could be many reasons for these errors, including (but not limited to) an incorrect configuration, an incorrect path used to the source media, incorrect credentials used to access a media storage bucket (e.g. AWS S3 or Google Storage), an issue with the mapping function or a missing media asset.

You can see information about a particular error in the x-cld-error header field of the HTTP response.

For example, if your browser shows HTTP ERROR 404, then using browser tools, you can see that the message in the x-cld-error field is Resource not found:

Browser tools showing HTTP error

If, after looking at the error message, you still cannot resolve the issue, our support team will be happy to help.

✔️ Feedback sent!

Rate this page: