Media Optimizer API reference

The Media Optimizer API is a rate-limited API that lets you manage your Media Optimizer configuration components, such as media sources and delivery profiles, manage your Media Optimizer cache and other administration functionality.

Tip
For in-depth information, 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:

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

You should see the response:

Copy to clipboard
{
    "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 on the CDN. Use this if you have updated your source media and want to ensure your Media Optimizer URLs deliver the latest versions of the media.

Methods Description
POST/invalidate_all_derived_resources Invalidate all derived resources

Invalidate all derived resources

Invalidate all derived media that is cached on the CDN.

Syntax

POST /invalidate_all_derived_resources

Required parameters

Specify one of the following to tell Media Optimizer which media to invalidate:

  • urls
  • media_resources
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 resources are invalidated, regardless.

urls is required if media_resources is not specified.

media_resources Array An array of up to 20 media resources to invalidate. Each media resource contains:

  • media_key: The unique identifier of the media within Cloudinary.
  • resource_type: The type of media. Possible values: image, video.

media_resources is required if urls is not specified.

Examples

Specifying an array of URLs:

Copy to clipboard
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_all_derived_resources

Specifying an array of media resources:

Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{
        "media_resources": [{"media_key": "rest/of/the/path1.mp4", "resource_type": "video"},
                            {"media_key": "rest/of/the/path2.jpg", "resource_type": "image"}]
  } ' \ 
  -X POST \
  https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/invalidate_all_derived_resources

Sample response

The following is a sample response received:

Copy to clipboard
{
    "message": "ok"
}

Cache warm up

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

Methods Description
POST/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 transformations that take time to complete, so the derived version of the media is ready in the cache for the first request.

Syntax

POST /warm_up

Required parameters

Parameter Type Description
url String The Media Optimizer URL to cache. Any default transformations specified in the relevant delivery 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 account console.

Examples

Not including a notification URL:

Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/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:

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

Including a notification URL:

Copy to clipboard
curl https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/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:

Copy to clipboard
{
    "notification_type": "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"
}

Delivery profiles

Enables you to manage delivery profiles.

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

Get delivery profiles

List all delivery profiles.

Syntax

GET /delivery_profiles

Example

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

Sample response

The response contains an array of delivery profiles.

Copy to clipboard
[
    {
        "id": "6713839a04e70c88a9a23a0fa82b90d5",
        "display_name": "Default",
        "path_prefix": null,
        "cname_id": "b72c3a9a0ed8ad931387689b516fbccb",
        "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
        "default_transformation": "default(auto_format_auto_quality)",
        "media_source_ids": [
            "5f6b45699e0104beb639934a78028f4b"
        ],
        "is_enabled": false
    },
    {
        "id": "dd98e5785e57d7d6849f7c6678595609",
        "display_name": "my delivery profile",
        "path_prefix": "videos",
        "cname_id": "644d354ba531aba65e28af4908e8ea36",
        "mapping_function_id": "a0a4c0a642519e78f93b7480a2e13304",
        "default_transformation": "video_tx",
        "media_source_ids": [
            "2ad29ead5e268e23003fd35003566b8b"
        ],
        "is_enabled": true
    }
]

Get delivery profile details

Get details of a single delivery profile.

Syntax

GET /delivery_profiles/:id

Required parameters

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

Examples

Get delivery profile by ID:

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

Sample response

Copy to clipboard
{
    "id": "6713839a04e70c88a9a23a0fa82b90d5",
    "display_name": "Default",
    "path_prefix": null,
    "cname_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "default(auto_format_auto_quality)",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": false
}

Create a delivery profile

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

Syntax

POST /delivery_profiles

Required parameters

Parameter Type Description
display_name String The display name of the delivery profile.
cname_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 delivery profile.
default_transformation String The name of the transformation to apply to all media in the profile.

Example

Create a new delivery profile:

Copy to clipboard
curl \
  -H "Content-Type: application/json" \
  -d '{          
        "display_name": "new delivery profile", 
        "path_prefix": "images",
        "cname_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

Copy to clipboard
{
    "id": "f5d8b763126204f0141533ba9d9facc3",
    "display_name": "new delivery profile",
    "path_prefix": "images",
    "cname_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "small_image",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": false
}

Update a delivery profile

Update a delivery profile.

Syntax

PUT /delivery_profiles/:id

Required parameters

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

Optional parameters

Parameter Type Description
display_name String The new display name of the delivery profile.
cname_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 delivery 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 delivery profile.

Example

Update the display name of a delivery profile:

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

Sample response

Copy to clipboard
{
    "id": "f5d8b763126204f0141533ba9d9facc3",
    "display_name": "my new delivery profile",
    "path_prefix": "images",
    "cname_id": "b72c3a9a0ed8ad931387689b516fbccb",
    "mapping_function_id": "4d890086dd2160609ad3a7f1a2546468",
    "default_transformation": "small_image",
    "media_source_ids": [
        "5f6b45699e0104beb639934a78028f4b"
    ],
    "is_enabled": true
}

Delete a delivery profile

Delete a single delivery profile.

Syntax

DELETE /delivery_profiles/:id

Required parameters

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

Examples

Delete a delivery profile by ID:

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

Sample response

Copy to clipboard
{
    "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

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

Sample response

The response contains an array of domains.

Copy to clipboard
[
    {
        "id": "b72c3a9a0ed8ad931387689b516fbccb",
        "domains": "mycloud.mo.cloudinary.net"
    },
    {
        "id": "d0a4c0a642519e78f93b7480a2e13304",
        "domains": "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 delivery 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=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

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

Copy to clipboard
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.

Copy to clipboard
[
    {
        "id": "9468a72d37440570233dd41eeacc0b04",
        "display_name": "Media Optimizer",
        "code": "",
        "template_type": "media_optimizer"
    },
    {
        "id": "63b432465f829b7fe342851bd1138447",
        "display_name": "Programmable Media",
        "code": "",
        "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:

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

Sample response

Copy to clipboard
{
    "id": "9468a72d37440570233dd41eeacc0b04",
    "display_name": "Media Optimizer",
    "code": "",
    "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:

Copy to clipboard
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 += '\''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'\'',
        }
    }"
  }' \
  -X POST https://<API_KEY>:<API_SECRET>@mo-api.cloudinary.com/v1/<CLOUD_NAME>/mapping_functions

Sample response

Copy to clipboard
{
    "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 += 'w_150,h_100,c_fit/';\n                break;\n                case 'medium':transformation += 'w_360,h_240,c_fit/';\n                break;\n                case 'large':transformation += 'w_720,h_480,c_fit/';\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:

Copy to clipboard
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

Copy to clipboard
{
    "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 += 'w_150,h_100,c_fit/';\n                break;\n                case 'medium':transformation += 'w_360,h_240,c_fit/';\n                break;\n                case 'large':transformation += 'w_720,h_480,c_fit/';\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:

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

Sample response

Copy to clipboard
{
    "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

Copy to clipboard
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.

Copy to clipboard
[
    {
        "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:

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

Sample response

Copy to clipboard
{
    "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.

Syntax

POST /media_sources

Required parameters

Parameter Type Description
display_name String The display name of the media source.
uri_type String The type of media source.

Possible values: http, s3, gs, cloudinary, web

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

cloudinary - see Cloudinary settings for details of the parameter:

  • cld_cloud_name

web - see Web address settings for details of each parameter:

  • web_uri_base
  • web_headers
  • web_uri_template

Example

Create an S3 media source:

Copy to clipboard
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

Copy to clipboard
{
    "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.

Syntax

PUT /media_sources/:id

Required parameters

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

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, cloudinary, web

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

cloudinary - see Cloudinary settings for details of the parameter:

  • cld_cloud_name

web - see Web address settings for details of each parameter:

  • web_uri_base
  • web_headers
  • web_uri_template

Examples

Update the display name of a media source:

Copy to clipboard
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

Copy to clipboard
{
    "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:

Copy to clipboard
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

Copy to clipboard
{
    "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.

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 by ID:

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

Sample response

Copy to clipboard
{
    "message": "ok"
}

Ping

Tests the reachability of the Media Optimizer API.

Methods 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

Copy to clipboard
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.

Copy to clipboard
{
    "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:

Copy to clipboard
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.

Copy to clipboard
{
    "transformations": [
        {
            "name": "t_auto_format_auto_quality",
            "transformation": "f_auto,q_auto"
        },
        {
            "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:

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

Sample response

Copy to clipboard
{
    "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:

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

Sample response

Copy to clipboard
{
    "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:

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

Sample response

Copy to clipboard
{
    "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:

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

Sample response

Copy to clipboard
{
    "message": "deleted"
}

Usage

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

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

Copy to clipboard
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.

Copy to clipboard
{
    "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
    }
}

✔️ Feedback sent!

Rate this page: