Programmable Media

Media Editor API reference

Last updated: Feb-22-2024

The Media Editor API reference details all the parameter options, types and events for configuring the Media Editor widget.

Tip
For in-depth information, see the Media Editor guide.

Parameters

The following tables list all available parameters (options) for configuring a Media Editor widget with the update method:

Required parameters

The following parameters are required when configuring the Media Editor widget:

Parameter Type Description
cloudName string Your Cloudinary product environment cloud name.
Example: "demo"
publicIds (Asset or PublicID)[] Initializes the Media Editor with the specified publicIds (Note: currently only supports a single public ID). The individual assets in the array can be described either by an Asset object (necessary for videos and/or authenticated/private assets) or by a PublicID string (as a shortcut for public images only).
Example: [{publicId: "sandy_beach", type: "authenticated"}]

Important

Besides the required parameters, only include other parameters in order to override their default values.

Widget parameters

Parameter Type Description
mode String Determines how the widget is displayed, either as modal (default) or inline within the page body (or the element given by the appendTo parameter).
language Object The text strings to use in the widget, that includes all the "key":"value" pairs of text to override the widget's default text labels. See the Localization sample as a reference implementation.
theme Object The theme properties to apply to the widget. Currently only supports customizing the logo that appears in the top left corner of the widget.
Example: theme: {logo: 'https://www.example.com/mylogo.png'}

Image parameters

Parameter Type Description
transformation Object The Cloudinary transformation to apply to all images. Any transformations, effects, and other Cloudinary transformation options can be applied and will be added in addition to any other transformations added with the Media Editor (resize, overlay, etc).
Example: [{effect: "sepia"}]
maxWidth int The maximum allowed width for the final image.
maxHeight int The maximum allowed height for the final image.
steps string[] An array of steps to include in the widget, in the specified order. Possible values: resizeAndCrop, imageOverlay, textOverlays, export
resizeAndCrop ResizeProps The properties for the resize and crop step of the widget. Only relevant when the resizeAndCrop step is included.
imageOverlay ImageOverlayProps The properties for the image overlay step of the widget. Only relevant when the imageOverlay step is included.
textOverlays TextOverlaysProps The properties for the text overlay step of the widget. Only relevant when the textOverlays step is included.
export ExportProps The properties for the export step of the widget. Only relevant when the export step is included.

Note
All transformations use the JavaScript (legacy) syntax. When looking at transformation examples in the rest of the documentation, you can change the JS tab to display the legacy (cloudinary-core) code examples.

Video parameters

Parameter Type Description
steps string[] An array of steps to include in the widget, in the specified order. Currently only supports trim.
trim TrimProps The properties for the trim step of the widget.
transformation Object The Cloudinary transformation to apply to all videos. Any manipulations, effects, and other Cloudinary transformation options can be applied and will be added in addition to any other transformations added with the trim.
Example: [{effect: "sepia"}]
maxWidth int The maximum allowed width for the final video.
maxHeight int The maximum allowed height for the final video.

Types

Asset

An object identifying an uploaded asset. This object is only necessary to identify restricted assets (private/authenticated).

Parameter Type Description
publicId string A string value representing the identifier that is used for accessing an uploaded media asset.
resourceType string The file type of the asset. Possible values: image (default) or video
type string The delivery type of the uploaded asset. Possible values: public (default), private or authenticated

ResizeProps

Parameter Type Description
presets (PredefinedPreset or CustomPreset)[] An array of preset options that the user can choose from, where each object identifies either a predefined social media preset or a custom preset.
interactiveCrop boolean Whether to allow interactive cropping. Default: true
minCropWidth int The minimum width allowed for the crop.
minCropHeight int The minimum height allowed for the crop.
aspectRatioLock boolean Whether to lock the aspect ratio. If true, aspect ratio starts locked. Default: true
toggleAspectRatio boolean Whether to allow toggling the aspect ratio. If false, the toggle is disabled and set to the value of aspectRatioLock. Default: true
flip boolean Whether to display the flip buttons, enabling the user to flip the image. Default: true
rotate boolean Whether to display the rotate buttons, enabling the user to rotate the image. Default: true
guidelinesUrl URL The URL of an informative image (with instructions for example) to appear on the right-hand side of the display. If this parameter is not given then the right-hand section will not appear.

ImageOverlayProps

Parameter Type Description
overlays OverlayProps An array of overlay objects for the user to choose from, where each object identifies a possible image overlay and its properties.
guidelinesUrl URL The URL of an informative image (with overlay instructions for example) to appear on the right-hand side of the display.

TextOverlaysProps

Parameter Type Description
fonts (string or FontProps)[] An array of fonts for the user to choose from, where each font in the array is either a predefined 'built-in' font, or defines a custom font and its properties. Default (all the built-in fonts): ["Ariel", "Verdana", "Helvetica", "Trebuchet MS", "Times New Roman", "Georgia", "Courier New", "Open Sans", "Roboto", "Montserrat"]
presets (PredefinedTextPreset or CustomTextPreset)[] An array of text preset objects for the user to choose from, where each object identifies an initial text overlay and its properties. Default: ["heading", "body", "subtitle", "caption"]
guidelinesUrl URL The URL of an informative image (with overlay instructions for example) to appear on the right-hand side of the display.
initialColors string[] An array of preset colors for the user to initially select from. The colors can be given as an RGB or RGBA hex triplet or quadruplet, a 3- or 4-digit RGB/RGBA hex, or a named color. Default: ["#ffffff", "#000000"]
showColorPicker boolean Whether to display the color picker in addition to the preset colors. Default: true

TrimProps (Beta)

Parameter Type Description
startOffset float The initial location of the starting trim handle for the video in seconds. Default: 0
endOffset float The initial location of the ending trim handle for the video in seconds. Default: the full duration of the video.
minDuration float The minimum duration for the trimmed video. Default: 0
maxDuration float The maximum duration for the trimmed video. Default: the full duration of the video.

PredefinedTextPreset

These are the values of the predefined text presets:

label previewText size font
heading ABC 59 Georgia
subtitle ABC 16 Ariel
body ABC 14 Roboto
caption ABC 12 Montserrat

CustomTextPreset

Property Type Description
label string (required) The label of the preset.
size int (required) The font size in points.
font string (required) The name of the font.
previewText string The preview text to showcase this text overlay preset. Maximum 3 characters. Default: "ABC"
weight enum Either normal or bold. Default: "normal"
style enum Either normal or italic. Default: "normal"
color string The color of the text. Default: "#000000"
underline boolean Whether to include an underline. Default: false

For example:

FontProps

Property Type Description
font string The name of the custom font.
styles object An object detailing the public_ids of your custom font files. You can add up to four font files to use as values for each of the following keys: regular, bold, italic and boldItalic, and include whether to support underline.

Notes for using custom fonts
  • All custom fonts you want to use need to be first uploaded to Cloudinary as raw, authenticated files.
  • Since the custom font is uploaded as an authenticated file, you will also need to implement the onSign method to return the signature needed for the widget to access a restricted asset.
  • You need to specify the font's full public_id (as a raw file this will include the extension).

For example:

ExportProps

Parameter Type Description
formats string[] An array of image formats (including auto) for the user to choose from, by file extension. If this parameter is not given, defaults to the original file type, and no options are provided to the user.
quality string[] An array of image qualities for the user to choose from. If this parameter is not given, defaults to auto, best, good, eco
download Boolean Whether the download button is displayed. Default true
share Boolean Whether to display the HTTPS URL and enable the copy URL function when clicked. Default true

PredefinedPreset

Value Label Dimensions
original Original {The original dimensions of the image}
square Square Ratio: 1:1
landscape-16:9 Landscape Ratio: 16:9
landscape-4:3 Landscape Ratio: 4:3
portrait-9:16 Portrait Ratio: 9:16
portrait-3:4 Portrait Ratio: 3:4
facebookStory Facebook Story 1080 x 1920
facebookPost Facebook Post 940 x 788
facebookCover Facebook Cover 820 x 312
facebookAd Facebook Ad 1200 x 628
facebookEvent Facebook Event 1920 x 1080
instagramStory Instagram Story 1080 x 1920
instagramPost Instagram Post 1080 x 1080
twitterTweet Twitter Tweet 1024 x 512
twitterAd Twitter Ad 800 x 320
linkedInCover LinkedIn Cover 1584 x 396
linkedInCompanyCover LinkedIn Company Cover 1536 x 768
linkedInAd LinkedIn Ad 1200 x 627
pinterestBoardCover Pinterest Board Cover 222 x 150
pinterestPin Pinterest Pin 600 x 900

CustomPreset

Property Type Description
label string (required) The label of the preset.
width int The desired width of the image.
height int The desired height of the image
aspectRatio string The desired aspect ratio of the image. If neither width nor height is provided, use the original width for portrait images and the height for landscape images. Ignore this property if both width and height are given.

For example:

OverlayProps

Parameter Type Description
publicId String required. The ID of the image to be placed as an overlay.
publicIds Asset or PublicID The image to be placed as an overlay. The image can be described either by an Asset object (necessary for authenticated/private assets) or by a PublicID string (as a shortcut for public images only).
Example: {publicId: "company_logo", type: "authenticated"}
label String The label for this overlay option.
transformations Object[] An array of Cloudinary transformation objects to apply to the overlay. Any transformations, effects, and other Cloudinary transformation options can be applied.
placementOptions (PredefinedPlacement or CustomPlacement)[] An array of overlay placement options for the user to choose from, where each object identifies either a predefined placement or a custom placement location.
Example:
[ {"x": 0.8, "y": 0.8, "width": 300, "height": 300, "gravity": "north_west"}, {"x": 0, "y": 0, "width": 200, "height": 200, "gravity": "north_east", "top"}]

CustomPlacement

Parameter Type Description
width int or float The width of the overlay: an integer sets the value in pixels (e.g., 150 sets the width to exactly 150 pixels) and a float sets the value as a multiple of the base image width (e.g., 0.1 sets the width to 10% of the base image width).
height int or float The height of the overlay: an integer sets the value in pixels (e.g., 100 sets the height to exactly 100 pixels) and a float sets the value as a multiple of the base image height (e.g., 0.2 sets the height to 20% of the base image height).
gravity string Specifies where to place the overlay on the base image. Possible values: north_east, north, north_west, west, south_west, south, south_east, east, center
x int or float The horizontal offset of the overlay from the specified gravity: an integer sets the value in pixels (e.g., 10 sets the horizontal offset to exactly 10 pixels) and a float sets the value as a multiple of the base image width (e.g., 0.15 sets the horizontal offset to 15% of the base image width).
y int or float The vertical offset of the overlay from the specified gravity: an integer sets the value in pixels (e.g., 15 sets the vertical offset to exactly 15 pixels) and a float sets the value as a multiple of the base image height (e.g., 0.1 sets the vertical offset to 10% of the base image height).

For example:

PredefinedPlacement

Value Description
top "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "north"
top_right "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "north_east"
right "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "east"
bottom_right "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "south_east"
bottom "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "south"
bottom_left "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "south_west"
left "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "west"
top_left "x": 0.05, "y": 0.05, "width": 0.1, "height": 0.1, "gravity": "north_west"
middle "x": 0, "y": 0, "width": 0.1, "height": 0.1, "gravity": "center"

Instance methods

The following methods can be used with the Media Editor instance returned by the mediaEditor initialization method:

Update

The update method accepts a map of configuration parameters to update an already initialized widget. The new configuration is merged with the existing configuration, so any new values will replace old ones. This includes arrays, where the entire array of values is replaced with the new array.

For example:

Show

Displays an initialized Media Editor widget object, or a previously hidden widget.

For example:

Hide

Hides a previously displayed widget without removing it from memory.

For example:

Destroy

Use the destroy method to erase the Media Editor widget and remove it from memory and your DOM, and closes the event emitter.

For example:

On

Use the on method to register to a specific event. For a full listing of available events, see the Events section.

For example:

Sample response:

getConfig

Returns the current configuration of the Media Editor widget.

For example:

getVersion

Returns the widget version.

For example:

triggerExport

Triggers the export function (as if the user had clicked on the export button).

For example:

onSign

Use the onSign method to resolve the delivery signature needed for a restricted asset or a custom font (see Authenticated access to media assets). You should provide the code in the form of a Promise that will request the delivery URL from your back-end server, and then set the url parameter with the full delivery URL of the image (including a signature component or token query string if required).

For example:

Events

The following table lists the events that can be registered with the on method of a Media Editor instance.

Event Params Description
aspectratioclick The aspect ratio toggle has been clicked.
close The widget was closed with the X button.
copyurl resourceType The URL was copied.
cropclick presetName A crop preset has been clicked.
dimensionsedit width, height An image's dimensions were edited (width or height).
download resourceType The image was downloaded.
formatclick selectedFormat A format option was clicked.
interactivecropresize An image was interactively resized.
interactivecropmove An image was interactively moved.
next fromStep, toStep The user moved to the next widget step.
overlayclick selectedPreset An overlay preset has been clicked.
overlayplacementclick An overlay placement has been clicked.
prev fromStep, toStep The user moved to the previous widget step.
qualityclick selectedQuality A quality option was clicked.
flipvertically The flip vertical button has been clicked.
fliphorizontally The flip horizontal button has been clicked.
rotateclockwise The rotate clockwise button has been clicked.
rotatecounterclockwise The rotate counterclockwise button has been clicked.
textalign type The text alignment type, either: canvas when the text layer was aligned to the center (vertical or horizontal or both), or layer when the text layer was aligned to another layer.

The following information is included when the event is triggered, and is available in the (data) structure:

  • action: The action that triggered the event.
  • label: A description of the event.
  • params: Additional information returned as key/values pairs (see the table above for details).

We also support 2 special events:

  • analytics - Registers to all the events, which is useful for analytics purposes. The (data) structure will also include the event that triggered.
  • export - The user clicks on the "Export" button. The (data) structure will also include an array of assets with the url, secureUrl and downloadUrl. For example:

See also
For more information on the Cloudinary Media Editor, see the Media Editor guide.

✔️ Feedback sent!

Rate this page: