More Products

Media Optimizer API reference

Last updated: Mar-24-2023

The Media Optimizer API 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 > Access 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.

Note
You cannot delete the default optimization profile (the one that returns "is_default": true).

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.

Note
Deleting a transformation also deletes all the derived images based on this transformation (up to 1000). The method returns an error if there are more than 1000 derived images based on this 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.

✔️ Feedback sent!

Rate this page: