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.

The Media Optimizer documentation includes:

Guides

References

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.

On this page:

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:

curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/ping

You should see the response:

{
    "status": "ok"
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "urls": ["https://mycloud.mo.cloudinary.net/rest/of/the/path1.mp4", 
                 "https://mycloud.mo.cloudinary.net/rest/of/the/path2.jpg"]
  }' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/invalidate

Sample response

The following is a sample response received:

JSON
{
    "message": "ok"
}

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:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/cache_warm_up -X POST --data 'url=https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex'

Sample response

The following is a sample response received:

JSON
{
    "url": "https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex",
    "status": "processing",
    "batch_id": "6ebf1479dd8b71eb4e632620520f7347978a37ee7e30595a119c0efb957fb8c3ff96"
}

Including a notification URL:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/cache_warm_up -X POST --data 'url=https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex&notification_url=https://mysite.example.com/my_notification_endpoint'

Sample response

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

JSON
{
    "notification_type": "cache_warm_up",
    "timestamp": "2021-03-15T13:54:05+00:00",
    "request_id": "d113e60a52325296dbaa435b743a434b",
    "batch_id": "cff48cde900b17b00d0c52c83057ee5626e6c1806beec8d48784b4b006c54149",
    "url": "https://mycloud.mo.cloudinary.net/rest/of/the/path.mp4?tx=t_complex"
}

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

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles

Sample response

The response contains an array of optimization profiles.

JSON
[
    {
        "id": "6713839a04e70c88a9a23a0fa82b90d5",
        "display_name": "Default",
        "path_prefix": null,
        "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
        "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
        "default_transformation": "default(auto_format_auto_quality_responsive_width)",
        "media_source_ids": [
            "5f6b45699e0104beb639934a78028f4b"
        ],
        "is_enabled": false,
        "is_default": true
    },
    {
        "id": "dd98e5785e57d7d6849f7c6678595609",
        "display_name": "my optimization profile",
        "path_prefix": "videos",
        "domain_id": "644d354ba531aba65e28af4908e8ea36",
        "mapping_function_id": "a0a4c0a642519e78f93b7480a2e13304",
        "default_transformation": "video_tx",
        "media_source_ids": [
            "2ad29ead5e268e23003fd35003566b8b"
        ],
        "is_enabled": true,
        "is_default": false
    }
]

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:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles/6713839a04e70c88a9a23a0fa82b90d5

Sample response

JSON
{
    "id": "6713839a04e70c88a9a23a0fa82b90d5",
    "display_name": "Default",
    "path_prefix": null,
    "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "default(auto_format_auto_quality_responsive_width)",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": false,
    "is_default": true
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new optimization profile", 
        "path_prefix": "images",
        "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
        "default_transformation": "small_image",
        "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
        "media_source_ids": [
            "5f6b45699e0104beb639934a78028f4b"
        ]
  }' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles

Sample response

JSON
{
    "id": "f5d8b763126204f0141533ba9d9facc3",
    "display_name": "new optimization profile",
    "path_prefix": "images",
    "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "small_image",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": false,
    "is_default": false
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "my new optimization profile",
        "is_enabled": true
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles/f5d8b763126204f0141533ba9d9facc3

Sample response

JSON
{
    "id": "f5d8b763126204f0141533ba9d9facc3",
    "display_name": "my new optimization profile",
    "path_prefix": "images",
    "domain_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "small_image",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": true,
    "is_default": false
}

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:

Curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/delivery_profiles/f5d8b763126204f0141533ba9d9facc3

Sample response

JSON
{
    "message": "ok"
}

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

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/domains

Sample response

The response contains an array of domains.

JSON
[
    {
        "id": "b72c3a9a0ed8ad931387689b516fbccb",
        "domain": "mycloud.mo.cloudinary.net"
    },
    {
        "id": "d0a4c0a642519e78f93b7480a2e13304",
        "domain": "me.mydomain.com"
    }
]

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

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions

Sample response

The response contains an array of mapping functions.

JSON
[
    {
        "id": "9468a72d37440570233dd41eeacc0b04",
        "display_name": "Media Optimizer",
        "template_type": "media_optimizer"
    },
    {
        "id": "63b432465f829b7fe342851bd1138447",
        "display_name": "Programmable Media",
        "template_type": "programmable_media"
    }
]

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:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions/9468a72d37440570233dd41eeacc0b04

Sample response

JSON
{
    "id": "9468a72d37440570233dd41eeacc0b04",
    "display_name": "Media Optimizer",
    "template_type": "media_optimizer"
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "my new mapping function",
    "code": "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 += '\''c_fit,h_100,w_150/'\'';
                break;
                case '\''medium'\'':transformation += '\''c_fit,h_240,w_360/'\'';
                break;
                case '\''large'\'':transformation += '\''c_fit,h_480,w_720/'\'';
                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'\'',
        }
    }"
  }' \
  -X POST https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions

Sample response

JSON
{
    "id": "b3f0c6094a17cf2a93e73689ae7d5830",
    "display_name": "my new mapping function",
    "code": "function map(request, environment) {\n        let transformation = environment.defaultTransformation + '/';\n        if (request.query.width && request.query.height) {\n            transformation+=`w_${request.query.width},h_${request.query.height},c_limit/`;\n        } \n        else if (request.query.size) {\n            switch(request.query.size) {\n                case 'small':transformation += 'c_fit,h_100,w_150/';\n                break;\n                case 'medium':transformation += 'c_fit,h_240,w_360/';\n                break;\n                case 'large':transformation += 'c_fit,h_480,w_720/';\n                break;\n            }\n        }\n        let path = request.path;\n        if (environment.pathPrefix.length > 0) {\n            path = path.slice(`/${environment.pathPrefix}/`.length);\n        }\n        return {\n            fwd_key: path,media_key: request.path,transformation,resource_type: 'image',\n        }\n    }",
    "template_type": "custom"
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "renamed mapping function"
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions/b3f0c6094a17cf2a93e73689ae7d5830

Sample response

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

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:

Curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions/b3f0c6094a17cf2a93e73689ae7d5830

Sample response

JSON
{
    "message": "ok"
}

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

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources

Sample response

The response contains an array of media sources.

JSON
[
    {
        "id": "5f6b45699e0104beb639934a78028f4b",
        "display_name": "my first web media source",
        "uri_type": "web",
        "config": {
            "web_uri_base": "https://mysite.com",
            "web_headers": {},
            "web_uri_template": "{{fwd_key}}"
        }
    },
    {
        "id": "9ee6d5cace98b0e261e44d7ddeffcd76",
        "display_name": "my s3 media source",
        "uri_type": "s3",
        "config": {
            "s3_bucket_name": "my s3 bucket name",
            "s3_bucket_folder": "my s3 bucket folder",
            "s3_uri_template": "s3://mybucket/images/{{vars.signature}}/{{fwd_key}}"
        }
    },
    {
        "id": "cad29ead5e268e23003fd35003566b8b",
        "display_name": "http media source",
        "uri_type": "http",
        "config": {}
    }
]

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:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/5f6b45699e0104beb639934a78028f4b

Sample response

JSON
{
    "id": "5f6b45699e0104beb639934a78028f4b",
    "display_name": "my first web media source",
    "uri_type": "web",
    "config": {
        "web_uri_base": "https://mysite.com",
        "web_headers": {},
        "web_uri_template": "{{fwd_key}}"
    }
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new s3 ms", 
        "uri_type": "s3",
        "config": {
            "s3_bucket_name": "my_bucket_name",
            "s3_bucket_folder":"my_bucket_folder",
            "s3_access_key":"123123",
            "s3_uri_template": "my.uri.template.com"
        }
  }' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources

Sample response

JSON
{
    "id": "ad4adf9b9c3e560831228d2b53e4952d",
    "display_name": "new s3 ms",
    "uri_type": "s3",
    "config": {
        "s3_bucket_name": "my_bucket_name",
        "s3_bucket_folder":"my_bucket_folder",
        "s3_access_key":"encrypted",
        "s3_uri_template": "my.uri.template.com"
    }
}

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:

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new s3 media source"
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/ad4adf9b9c3e560831228d2b53e4952d

Sample response

JSON
{
    "id": "a54ff9e93ddb98bb3291ab6538b229d1",
    "display_name": "new s3 media source",
    "uri_type": "s3",
    "config": {
        "s3_bucket_name": "my_bucket_name",
        "s3_bucket_folder":"my_bucket_folder",
        "s3_access_key":"encrypted",
        "s3_uri_template": "my.uri.template.com"
    }
}

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

Curl
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "config": {
            "s3_bucket_name": "my_bucket_name",
            "s3_bucket_folder":"my_new_bucket_folder",
            "s3_access_key":"123123",
            "s3_uri_template": "my.uri.template.com"
        }
  }' \ 
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/ad4adf9b9c3e560831228d2b53e4952d

Sample response

JSON
{
    "id": "a54ff9e93ddb98bb3291ab6538b229d1",
    "display_name": "new s3 media source",
    "uri_type": "s3",
    "config": {
        "s3_bucket_name": "my_bucket_name",
        "s3_bucket_folder":"my_new_bucket_folder",
        "s3_access_key":"encrypted",
        "s3_uri_template": "my.uri.template.com"
    }
}

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:

Curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/media_sources/a54ff9e93ddb98bb3291ab6538b229d1

Sample response

JSON
{
    "message": "ok"
}

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

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/ping

Sample response

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

JSON
{
    "status": "ok"
}

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:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations?max_results=2

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.

JSON
{
    "transformations": [
        {
            "name": "t_auto_format_auto_quality_responsive_width",
            "transformation": "f_auto,q_auto,w_responsive"
        },
        {
            "name": "t_media_lib_thumb",
            "transformation": "c_limit,h_100,w_150"
        }
    ],
    "next_cursor": "8edbc61040178db60b0973ca9494bf3a"
}

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:

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/media_lib_thumb

Sample response

JSON
{
    "name": "t_media_lib_thumb",
    "transformation": "c_limit,h_100,w_150",
    "info": [
        {
            "height": 100,
            "width": 150,
            "crop": "limit"
        }
    ]
}

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:

Curl
curl \
  -d 'transformation=c_fill,h_100,w_150' \
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/small_fill

Sample response

JSON
{
    "message": "created"
}

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:

Curl
curl \
  -d 'transformation=c_fill,h_150,w_150' \
  -X PUT \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/small_fill

Sample response

JSON
{
    "message": "updated"
}

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:

Curl
curl  \
  -X DELETE \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/transformations/small_fill

Sample response

JSON
{
    "message": "deleted"
}

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):

Curl
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/usage?date=21-02-2021

Sample response

The response contains your Media Optimizer usage.

JSON
{
    "plan": "Plus PAYG",
    "last_updated": "2021-02-21",
    "transformations": {
        "usage": 0,
        "credits_usage": 0.0
    },
    "bandwidth": {
        "usage": 0,
        "credits_usage": 0.0
    },
    "credits": {
        "usage": 0.0,
        "limit": 225.0,
        "used_percent": 0.0
    },
    "requests": 0,
    "media_limits": {
        "image_max_size_bytes": 20971520,
        "video_max_size_bytes": 524288000,
        "raw_max_size_bytes": 20971520,
        "image_max_px": 25000000,
        "asset_max_total_px": 100000000
    }
}