Media Optimizer API reference

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

This page covers the Media Optimizer API, which is a rate-limited API that lets you manage your Media Optimizer configuration components, such as media sources and optimization profiles, manage your Media Optimizer cache and other administration functionality.

For a complete overview of Media Optimizer and how it can help you to optimize the media on your site, see the Media Optimizer Guide.

API overview

The Media Optimizer API endpoints are accessed using HTTPs. By default, the API endpoints use the following format:

https://mo-api.cloudinary.com/v1/:cloud_name/:action

The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret are used for the authentication. You can find them in your Media Optimizer Console under Settings > Security > API Keys.

Try pinging the Media Optimizer servers by replacing <API_KEY>, <API_SECRET>, and <CLOUD_NAME> in the cURL command below:

You should see the response:

For most actions, request parameters are appended to the URL. In a few cases, they are passed as JSON objects. The response is in a JSON snippet and includes information about the action that was performed.

---

Cache invalidation

Invalidates media that is cached internally and on the CDN. Use this if you have updated your source media and want to ensure that your Media Optimizer URLs deliver the latest versions of the media.

Method	Description
POST/invalidate	Invalidate all caches

---

Invalidate all caches

Invalidate all derived media that is cached internally and on the CDN.

Syntax

POST /invalidate

Required parameters

Parameter	Type	Description
urls	Array	An array of up to 20 Media Optimizer URLs to invalidate. These URLs, and any derived media from the specified assets, are invalidated. Transformation parameters can be given in the URLs, but all derived assets are invalidated, regardless.

Examples

Specifying two URLs to invalidate:

Sample response

The following is a sample response received:

---

Cache warm up

Populates the cache with optimized media, ready for delivery right from the first request.

Method	Description
POST/cache_warm_up	Warm up the cache

---

Warm up the cache

Fetch media from its source to make it available on the CDN cache with required optimizations. This is most useful for large images and videos that cannot be transformed on the fly. It can also be used for transformations that take time to complete, so the derived version of the media is ready in the cache for the first request.

Syntax

POST /cache_warm_up

Required parameters

Parameter	Type	Description
url	String	The Media Optimizer URL to cache. Any default (base) transformations specified in the relevant optimization profile are applied to the cached media. You can also specify other transformations, which are handled by your mapping function, as part of the URL.

Optional parameters

Parameter	Type	Description
notification_url	String	An HTTP or HTTPS URL to receive the response (a webhook) when the derived media is available on the cache. If not specified, the response is sent to the global Notification URL (if defined) in the Delivery Settings of your Cloudinary Console.

Examples

Not including a notification URL:

Sample response

The following is a sample response received:

Including a notification URL:

Sample response

The following is a sample response received at the notification URL:

---

Optimization profiles

Enables you to manage optimization profiles (formerly called delivery profiles).

Method	Description
GET /delivery_profiles	Get all optimization profiles
GET /delivery_profiles/:id	Get details of an optimization profile
POST/delivery_profiles	Create an optimization profile
PUT/delivery_profiles/:id	Update an optimization profile
DELETE/delivery_profiles/:id	Delete an optimization profile

---

Get optimization profiles

List all optimization profiles.

Syntax

GET /delivery_profiles

Example

Sample response

The response contains an array of optimization profiles.

---

Get optimization profile details

Get details of a single optimization profile.

Syntax

GET /delivery_profiles/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the optimization profile.

Examples

Get optimization profile by ID:

Sample response

---

Create an optimization profile

Create a new optimization profile. Newly created optimization profiles are disabled by default.

Syntax

POST /delivery_profiles

Required parameters

Parameter	Type	Description
display_name	String	The display name of the optimization profile.
domain_id	String	The ID of the domain name.
mapping_function_id	String	The ID of the mapping function.
media_source_ids	Array	An array of media source IDs.

Optional parameters

Parameter	Type	Description
path_prefix	String	Part of the base URL that identifies media belonging to the optimization profile.
default_transformation	String	The name of the transformation to apply to all media in the profile.

Example

Create a new optimization profile:

Sample response

---

Update an optimization profile

Update an optimization profile.

Syntax

PUT /delivery_profiles/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the optimization profile.

Optional parameters

Parameter	Type	Description
display_name	String	The new display name of the optimization profile.
domain_id	String	The ID of the domain name.
mapping_function_id	String	The ID of the mapping function.
media_source_ids	Array	An array of media source IDs.
path_prefix	String	Part of the base URL that identifies media belonging to the optimization profile.
default_transformation	String	The name of the transformation to apply to all media in the profile.
is_enabled	Boolean	The enabled status of the optimization profile.

Example

Update the display name of an optimization profile:

Sample response

---

Delete an optimization profile

Delete a single optimization profile.

Syntax

DELETE /delivery_profiles/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the optimization profile to delete.

Examples

Delete an optimization profile by ID:

Sample response

---

Domains

Enables you to view your domains. You need to create a support request to set up a custom domain.

Method	Description
GET /domains	Get all domains

---

Get domains

List all domains.

Syntax

GET /domains

Example

Sample response

The response contains an array of domains.

---

Mapping functions

Enables you to manage mapping functions.

Media Optimizer provides two built-in mapping functions that allow you to specify Media Optimizer transformations as part of the delivery URL (applied in addition to those defined in the optimization profile):

• 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=c_fit,h_500,w_500
  • The resource type specified as a query string, overriding any determining of resource_type in the mapping function due to the extension given. This is particularly useful if no extension is given, for example:
    https://mycloud.mo.cloudinary.net/rest/of/the/path?resource_type=image
    where resource_type can be set to image, video or raw.
• 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/c_fit,h_500,w_500/v1/sample.jpg

The template_type values for these built-in types are media_optimizer and programmable_media respectively. When you create your own mapping functions, they get a template_type of custom.

You can update and delete only the mapping functions that have a template_type of custom.

Method	Description
GET /mapping_functions	Get all mapping functions
GET /mapping_functions/:id	Get details of a mapping function
POST/mapping_functions	Create a mapping function
PUT/mapping_functions/:id	Update a mapping function
DELETE/mapping_functions/:id	Delete a mapping function

---

Get mapping functions

List all mapping functions.

Syntax

GET /mapping_functions

Example

Sample response

The response contains an array of mapping functions.

---

Get mapping function details

Get details of a single mapping function.

Syntax

GET /mapping_functions/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the mapping function.

Examples

Get mapping function by ID:

Sample response

---

Create a mapping function

Create a new custom mapping function.

Syntax

POST /mapping_functions

Required parameters

Parameter	Type	Description
display_name	String	The display name of the mapping function.
code	String	Custom code for the mapping function.

Example

Create a new mapping function:

Sample response

---

Update a mapping function

Update a mapping function.

Syntax

PUT /mapping_functions/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the mapping function.

Optional parameters

Parameter	Type	Description
display_name	String	The new display name of the mapping function.
code	String	The new custom code for the mapping function.

Example

Update the display name of a mapping function:

Sample response

---

Delete a mapping function

Delete a single mapping function.

Syntax

DELETE /mapping_functions/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the mapping function to delete.

Examples

Delete a mapping function by ID:

Sample response

---

Media sources

Enables you to manage media sources.

Method	Description
GET /media_sources	Get all media sources
GET /media_sources/:id	Get details of a media source
POST/media_sources	Create a media source
PUT/media_sources/:id	Update a media source
DELETE/media_sources/:id	Delete a media source

---

Get media sources

List all media sources.

Syntax

GET /media_sources

Example

Sample response

The response contains an array of media sources.

---

Get media source details

Get details of a single media source.

Syntax

GET /media_sources/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the media source.

Examples

Get media source by ID:

Sample response

---

Create a media source

Create a new media source configuration, allowing Media Optimizer to connect to a media source.

Syntax

POST /media_sources

Required parameters

Parameter	Type	Description
display_name	String	The display name of the media source configuration.
uri_type	String	The type of media source. Possible values: http, s3, gs, web, cloudinary
config	JSON	Configuration parameters required for the type of media source. http: Not applicable. s3 - see AWS S3 settings for details of each parameter: s3_bucket_name s3_bucket_folder s3_access_key s3_secret_key s3_uri_template gs - see Google storage settings for details of each parameter: gs_bucket_name gs_bucket_folder gs_service_account_key gs_uri_template web - see Web address settings for details of each parameter: web_uri_base web_headers web_uri_template cloudinary - see Cloudinary settings for details of the parameter: cld_cloud_name

Example

Create an S3 media source configuration:

Sample response

---

Update a media source

Update a single media source configuration.

Syntax

PUT /media_sources/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the media source configuration.

Optional parameters

You only need to specify parameters that you want to update, however, if updating one of the config parameters, you must supply all those required for the uri_type.

Parameter	Type	Description
display_name	String	The new display name of the media source.
uri_type	String	The type of media source. Possible values: http, s3, gs, web, cloudinary
config	JSON	Configuration parameters required for the type of media source. http: Not applicable. s3 - see AWS S3 settings for details of each parameter: s3_bucket_name s3_bucket_folder s3_access_key s3_secret_key s3_uri_template gs - see Google storage settings for details of each parameter: gs_bucket_name gs_bucket_folder gs_service_account_key gs_uri_template web - see Web address settings for details of each parameter: web_uri_base web_headers web_uri_template cloudinary - see Cloudinary settings for details of the parameter: cld_cloud_name

Examples

Update the display name of a media source configuration:

Sample response

Update one of the configuration parameters of a media source configuration:

Sample response

---

Delete a media source

Delete a single media source configuration.

Syntax

DELETE /media_sources/:id

Required parameters

Parameter	Type	Description
id	String	The ID of the media source to delete.

Examples

Delete a media source configuration by ID:

Sample response

---

Ping

Tests the reachability of the Media Optimizer API.

Method	Description
GET/ping	Ping Media Optimizer servers

---

Ping Media Optimizer servers

Check that the Media Optimizer API is reachable and accepting requests.

Syntax

GET /ping

Example

Sample response

The response contains the current status of the Media Optimizer servers.

---

Transformations

Enables you to manage named transformations.

Method	Description
GET /transformations	Get all transformations
GET /transformations/:transformation_name	Get details of a transformation
POST/transformations/:transformation_name	Create a named transformation
PUT/transformations/:transformation_name	Update a transformation
DELETE/transformations/:transformation_name	Delete a transformation

---

Get transformations

List all transformations.

Syntax

GET /transformations

Optional parameters

Parameter	Type	Description
max_results	Integer	Maximum number of transformations to return (up to 500). Default: 10.
next_cursor	String	When a request has more results to return than max_results, the next_cursor value is returned as part of the response. You can then specify this value as the next_cursor parameter of a following request.

Examples

List all transformations, returning two at a time:

Sample response

The response contains an array of transformations. If the number of transformations exceeds the max_results value, the next_cursor parameter is also returned. You can specify this value as the next_cursor parameter of the following listing request.

---

Get transformation details

Get details of a single transformation.

Syntax

GET /transformations/:transformation_name

Required parameters

Parameter	Type	Description
transformation_name	String	The name of the transformation.

Examples

Get transformation by name:

Sample response

---

Create a named transformation

Create a new named transformation.

Syntax

POST /transformations/:transformation_name

Required parameters

Parameter	Type	Description
transformation_name	String	The name of the transformation.
transformation	String	The transformation parameters.

Examples

Create a named transformation:

Sample response

---

Update a transformation

Update a single transformation.

Syntax

PUT /transformations/:transformation_name

Required parameters

Parameter	Type	Description
transformation_name	String	The name of the transformation.
transformation	String	The new transformation parameters.

Examples

Update the small_fill transformation to a specify a different height:

Sample response

---

Delete a transformation

Delete a single transformation.

Syntax

DELETE /transformations/:transformation_name

Required parameters

Parameter	Type	Description
transformation_name	String	The name of the transformation or the transformation parameters.

Examples

Delete transformation by name:

Sample response

---

Usage

Enables you to get a report on the status of your Media Optimizer account usage details.

Method	Description
GET/usage	Get account usage details

---

Get account usage details

Get your Media Optimizer account usage details.

Syntax

GET /usage

Optional parameters

Parameter	Type	Description
date	String	The date for the usage report. Must be within the last three months and given in the format: dd-mm-yyyy. Default: the current date.

Examples

Return a usage report for the 21st of February, 2021 (21-02-2021):

Sample response

The response contains your Media Optimizer usage.