@cloudinary/asset-management-mcpv0.11.6

The type of resource (image, video, raw, or auto).

The file to upload and associated parameters.

Restricts access to the asset by specifying one or more access types.
The asset is restricted unless at least one listed access type is valid.

Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.

Whether to return accessibility analysis values for the image.

A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions.
Note: You can also add the format parameter to convert other file types instead of rejecting them. In this case, only files that would normally be rejected are converted, any file format allowed for upload won't be converted.

The asset folder to assign to the asset.

When set to true, returns the uploaded asset's public_id immediately in the response, before the upload is completed (asynchronously). Default: false.

Whether to trigger automatic generation of video chapters. Chapters will be generated and saved as a .vtt file with -chapters appended to the public ID of the video. You can enable chapters as part of the Cloudinary Video Player. Relevant for videos only.

Automatically assigns tags to an asset according to detected objects or categories with a confidence score higher than the specified value.
Use together with the detection parameter for:
Use together with the categorization parameter for:

• Cloudinary AI Content Analysis
• Amazon Rekognition Celebrity Detection
• Google Automatic Video Tagging
• Google Auto Tagging
• Imagga Auto Tagging
• Amazon Rekognition Auto Tagging

Automatically remove the background of an image using an add-on.
Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).
Relevant for images only.

• Set to cloudinary_ai to use the deep-learning based Cloudinary AI Background Removal add-on.
• Note: this feature has been superseded by background removal on the fly.
• Set to pixelz to use the human-powered Pixelz Remove-The-Background Editing add-on service.

Whether to backup the uploaded asset. When set to true, backs up uploaded assets to a secondary storage bucket.

A comma-separated list of the categorization add-ons to run on the asset.
Set to google_tagging, google_video_tagging, imagga_tagging and/or aws_rek_tagging
to automatically classify the scenes of the uploaded asset.
Optionally append a language code suffix (e.g., google_tagging:fr).

Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Relevant for animated images and video only. A static image will return 0.

Whether to clear metadata field values that have become invalid due to a change in metadata rules. If false, the API returns an error if any existing metadata value is no longer valid. Default: false.

Whether to retrieve predominant colors & color histogram of the uploaded image. Note: If all returned colors are opaque, then 6-digit RGB hex values are returned. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned.

A pipe-separated list of key-value pairs of general textual context metadata to attach to the asset (e.g., "alt=My image|caption=Nice photo"). A literal = or | inside a value must be escaped with a prepending backslash, and a literal backslash must be doubled. A double quote must not be escaped.

Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.

Invokes the relevant add-on to return a list of detected content.
Set to:

• <content-aware model>_[<version>] (e.g. coco_v2) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the auto_tagging parameter to apply tags automatically.
• captioning to analyze an image and suggest a caption based on the image's contents.
• iqa to analyze the quality of an image.
• watermark-detection to detect watermarks in an image.
• adv_face to return a list of facial attributes using the Advanced Facial Attribute Detection add-on.
• aws_rek_face to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the auto_tagging parameter to apply tags automatically.

Whether to discard the name of the original uploaded file. Relevant when delivering assets as attachments (setting the flag disposition:attachment in delivery URLs).

A display name for the asset.

A list of transformations to eagerly generate for the asset. Accepts either a single transformation or a pipe-separated list of transformations.

Whether to generate the eager transformations asynchronously in the background after the upload request is completed rather than before the upload is completed.

A URL to notify when eager transformations are completed.

Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file.

Face coordinates as comma-separated values, with multiple faces separated by pipes.

Whether to detect faces in the asset.

A remote HTTP/HTTPS URL, private storage bucket URL (S3 or Google Storage), or FTP address of the file to upload.

To upload a file from your local machine, use the sign-upload tool instead.

Overrides the originally uploaded asset's file name in downloads that use flags like fl_attachment or fl_force_original.

Folder name where the uploaded asset will be stored. This parameter applies when using the Admin API, or when specifying the upload preset for unsigned uploading with the Upload API.

An optional format to convert the uploaded asset to before saving in the cloud.

An HTTP header or a list of headers lines for adding as response HTTP headers when delivering the asset to your users. Supported headers: Link, Authorization, X-Robots-Tag.

Whether to invalidate CDN cache copies of a previously uploaded asset that shares the same public ID. Default: false.

Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response.
Supported for images, video, and audio.

• Returned metadata for images includes: PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.
• Returned metadata for audio and video includes: audio_codec, audio_bit_rate, audio_frequency, channels, channel_layout.
• Additional metadata for video includes: pix_format, codec, level, profile, video_bit_rate, dar.

A pipe-separated list or a map of custom metadata fields (by external_id) and the values to assign to each of them. The = " and | characters can be supported as values when escaped with a prepended backslash (\). For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.

For all asset types, set to:

• manual to add the uploaded asset to a list of pending assets that can be moderated using the Admin API or the Cloudinary Console.
• perception_point to automatically moderate the uploaded asset using the Perception Point Malware Detection add-on.

For images only, set to:

• webpurify to automatically moderate the uploaded image using the WebPurify Image Moderation add-on.
• aws_rek to automatically moderate the uploaded image using the Amazon Rekognition AI Moderation add-on.
• duplicate:<threshold> to detect if the same or a similar image already exists using the Cloudinary Duplicate Image Detection add-on. Set threshold to a float greater than 0 and less than or equal to 1.0 to specify how similar an image needs to be in order to be considered a duplicate. Set threshold to 0 to add an image to the index of images that are searched when duplicate detection is invoked for another image.

For videos only, set to:

• aws_rek_video to automatically moderate the uploaded video using the Amazon Rekognition Video Moderation add-on.
• google_video_moderation automatically moderate the uploaded video using the Google AI Video Moderation add-on.

To request multiple moderations in a single API call:

• Send the desired list of moderations as a pipe-separated string with manual moderation, if relevant, being last.

Note: Rejected assets are automatically invalidated on the CDN within approximately ten minutes.

A URL to notify when the asset is ready.

Set to adv_ocr to extract all text elements in an image as well as the bounding box
coordinates of each detected element using the OCR text detection and extraction add-on.
Optionally append options (e.g., adv_ocr:document).

Allows you to update an asset by specifying custom logic with JavaScript that is executed after the upload to Cloudinary is completed successfully. This can be useful for conditionally adding tags, contextual metadata, and structured metadata, depending on the results of using the detection parameter on upload.

Whether to overwrite existing assets with the same public ID. When set to false, return immediately if an asset with the same public ID already exists. Default: true (when using unsigned upload, the default is false and cannot be changed to true).

Whether to return the perceptual hash (pHash) on the uploaded image for image similarity detection.

A proxy to use for fetching remote URLs. The format should be http://hostname:port.

The identifier that is used for accessing the uploaded asset. If not specified, a unique ID is generated automatically.

A string or path that's automatically prepended to the public_id with a forward slash. The value can contain the same characters as the public_id including additional forward slashes. This prefix can be useful to provide context and improve the SEO of an asset's filename in the delivery URL, but the value does not impact the location where the asset is stored.

Whether to return a quality analysis value for the image between 0 and 1, where 0 means the image is blurry and out of focus and 1 means the image is sharp and in focus. Relevant for images only.

Generates a related file based on the uploaded file.

• Set to aspose to automatically create a PDF or other image format from a raw Office document using the Aspose Document Conversion add-on. (Asynchronous)
• Set to google_speech to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from an uploaded video. (Asynchronous)
• Set to extract_text to extract all the text from a PDF file and store it in a raw JSON file with a public ID in the format: [pdf_public_id].extract_text.json. The full URL of the generated JSON file is included in the API response. Unlike the above raw_convert options, this option doesn't require registering for an add-on.(Synchronous)
• Set to azure_video_indexer to generate AI-powered video insights from Microsoft Azure. (Asynchronous)

Named region coordinate groups for cropping with region gravity.
Can be a JSON-encoded string or an object. Each region name may contain
only letters, numbers, or hyphens, and must have at least two coordinate pairs.

Settings to automatically generate breakpoints for responsive images.

Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within approximately 10 minutes using an unauthenticated API call.

A comma-separated list of tag names, or an array of tag names.

An incoming transformation to run on the uploaded asset before its storage. In contrast to eager, this parameter is applied before the file is stored.

The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload).

Whether the display name should be unique.

When set to false and used together with use_filename, if an asset with the same file name already exists, no random characters are appended to the file name. Instead, the asset is overwritten. Default: true (random characters are added to the file name if needed).

(Required for unsigned uploading / optional for signed uploading)
Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload Presets page of the Console Settings. An upload preset may be marked as unsigned, which allows unsigned uploading directly from the browser and restricts the optional parameters to: public_id, folder, tags, context, face_coordinates, regions and custom_coordinates.

Whether to add the asset_folder value as a prefix to the public_id value (prepended with a forward slash). This ensures that the public ID path will always match the initial asset folder, and can help to retain the behavior that previously existed in fixed folder mode. However, keep in mind that even when this option is used during upload, an asset with a certain public ID path can later be moved to a completely different asset folder hierarchy without impacting the public ID. This option only ensures path matching for the initial upload. Relevant only when public_id_prefix (or folder) has not been separately specified.

Whether to use the original file name of the uploaded asset if available for the public ID. The file name is normalized and random characters are appended to ensure uniqueness if the file name already exists. Default: false.

Whether to automatically assign the original filename of the uploaded asset as the asset's display name. Relevant only if the display_name parameter isn't set.

Whether to index the image for use with visual searches. Relevant for images only.

The type of resource (image, video, or raw).

The rename request parameters.

Whether to include contextual metadata in the response. Default is false.

The public ID of the asset to rename.

Whether to invalidate CDN cache copies of the renamed asset. Default is false.

Whether to include structured metadata in the response. Default is false.

URL to notify when the operation is complete.

Whether to overwrite the target asset if it already exists. Default is false.

The new public ID for the asset.

The target delivery type for the renamed asset. If omitted, the delivery type remains unchanged.

The current delivery type of the asset.

The type of resource for archive generation (image, video, or raw).

The archive generation parameters.

Whether to allow missing assets in the archive. If false, the operation will fail if any asset is not found.

A list of asset folder paths to include in the archive, or a single folder path string. Only available when asset folders are enabled for your account.

("create" mode only), specifies whether to generate the archive asynchronously.

("download" mode only) Unix timestamp indicating when the generated archive URL should expire.

Whether to flatten all files to be in the root of the archive file.

Whether to flatten the folder structure of the derived assets.

A list of fully qualified public IDs (resource_type/type/public_id) to include in the archive.

Whether to keep the derived assets used for generating the archive.

The method for generating and delivering the archive. Options:
download - Generates and delivers the archive file without storing it
create - Creates and stores the archive as a raw asset, returning URLs in the response
create_and_download - Creates, stores, and delivers the archive file

("create" mode only), specifies the URL to notify when the archive generation is complete.

Select all assets where the public ID starts with this prefix.

The list of public IDs to include in the archive.

A search expression to select assets to include in the archive.

Whether to skip adding the transformation details to the file names in the archive.

Tags to filter which assets to include in the archive. Assets matching any of the specified tags are included.

The folder in your product environment where the generated archive should be stored.

The filename for the downloaded archive file. Extension must match target_format (zip or tgz).

The format of the generated archive.

The public ID to assign to the generated archive, or the filename of the downloaded archive file.

A list of tag names to assign to the generated archive.

The transformations to apply to the assets before including them in the archive (separated by "|").

All supported delivery types.

Whether to use the original filenames of the assets in the archive instead of public IDs (when available).

The asset ID of the resource. Must be a 32-character hexadecimal string.

The version ID of the backup to download. Must be a 32-character hexadecimal string.

The asset to delete and related options.

A 32-character hexadecimal asset ID.

Whether to invalidate CDN cache. Default is false.

URL to receive completion notification.

The delivery type to filter by. When omitted, returns assets of all delivery types.

A public_id prefix. When specified, all assets with that prefix are returned.

An array of public IDs to return.

Whether to include the list of tag names assigned to each asset. Default is false.

Cursor for pagination.

Maximum number of results to return (1-500).

The sort direction for the results. Default is "desc".

An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither prefix nor public_ids were passed.

Additional fields to include in the response. The fields public_id and asset_id are always included.

The delivery type to filter by. When omitted, returns assets of all delivery types.

A public_id prefix. When specified, all assets with that prefix are returned.

An array of public IDs to return.

Whether to include the list of tag names assigned to each asset. Default is false.

Cursor for pagination.

Maximum number of results to return (1-500).

The sort direction for the results. Default is "desc".

An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither prefix nor public_ids were passed.

Additional fields to include in the response. The fields public_id and asset_id are always included.

The delivery type to filter by. When omitted, returns assets of all delivery types.

A public_id prefix. When specified, all assets with that prefix are returned.

An array of public IDs to return.

Whether to include the list of tag names assigned to each asset. Default is false.

Cursor for pagination.

Maximum number of results to return (1-500).

The sort direction for the results. Default is "desc".

An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither prefix nor public_ids were passed.

Additional fields to include in the response. The fields public_id and asset_id are always included.

The asset ID of the resource. Must be a 32-character hexadecimal string.

Whether to include color information (predominant colors and histogram of 32 leading colors). Default: false.

Whether to include IPTC, XMP, and detailed Exif metadata in the response. Default: false.

Whether to include a list of coordinates of detected faces. Default: false.

Whether to return quality analysis scores for the image. Default: false.

Whether to return accessibility analysis scores for the image. Default: false.

Whether to report the number of pages in multi-page documents (e.g., PDF). Default: false.

Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: false.

Whether to include previously specified custom cropping coordinates and faces coordinates. Default: false.

Whether to include details of all the backed up versions of the asset. Default: false.

Maximum number of derived assets to return. Default: 10.

The cursor for the next page of derived assets when there are more derived images than max_results.

The asset ID of the resource. Must be a 32-character hexadecimal string.

The asset attributes to update.

Restricts access to the asset by specifying one or more access types.
The asset is restricted unless at least one listed access type is valid.

The folder where the asset should be placed.

Confidence threshold for auto-tagging.

The background removal provider to use for the resource. Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).

The type of categorization to perform on the resource. Optionally append a language code suffix (e.g., google_tagging:fr).

Whether to clear invalid metadata fields. If false, invalid fields will be preserved. Default: false

A pipe-separated list of key-value pairs of general textual context metadata to attach to the asset (e.g., "alt=My image|caption=Nice photo"). A literal = or | inside a value must be escaped with a prepending backslash, and a literal backslash must be doubled. A double quote must not be escaped.

Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.

The type of detection to perform on the resource.

The display name of the resource.

Face coordinates as comma-separated values, with multiple faces separated by pipes.

A pipe-separated list or a map of custom metadata fields (by external_id) and the values to assign to each of them. The = " and | characters can be supported as values when escaped with a prepended backslash (\). For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.

The moderation status of the resource.

The type of OCR to perform on the resource. Set to adv_ocr, optionally with options (e.g., adv_ocr:document).

Quality override value that will override any automatic quality transformations.

The conversion to apply for raw files (e.g., aspose, google_speech, extract_text).

A JSON-encoded object of named groups of coordinate pairs representing regions. Each region name may contain only letters, numbers, or hyphens, and must have at least two coordinate pairs.

A comma-separated list of tag names, or an array of tag names.

Whether to ensure the display name is unique across all resources. If false, the operation will fail if a resource with the same display name exists. Default: false

Whether to index the resource with visual search. If true, the resource will be indexed for visual search capabilities. Default: false

The type of resource (image, video, or raw).

Limit the returned tags to those that start with the specified prefix.

Cursor for pagination.

Maximum number of results to return (1-500).

The derived resource IDs to delete.

Array of derived resource IDs to delete specific derived resources

Whether to invalidate the CDN cache for the deleted resources

The type of resource (image, video, or raw).

The tag command, the tags to apply, and the assets to apply them to.

The tag operation to apply.

• add adds the given tags, leaving existing tags untouched.
• remove removes the given tags, leaving other tags untouched.
• replace overwrites the full tag list with the given tags.
• remove_all clears every tag. The tags field is ignored.

The public IDs of the assets to apply the operation to. At most 1000 are processed per request; any beyond the first 1000 are ignored rather than rejected. Public IDs that do not exist, or that the caller lacks update permission for, are skipped rather than failing the request, so the returned public_ids may be shorter than the requested list.

The tag names to apply. Required for add, remove, and replace; ignored for remove_all. A tag name must not contain a comma.

The delivery type of the assets to operate on. Defaults to upload.

The type of resource (image, video, or raw).

The context command, the metadata to apply, and the assets to apply it to.

The contextual-metadata operation to apply.

already present are overwritten; keys not mentioned are left intact. context
is required.

• add merges the given key-value pairs into each asset's existing context. Keys
• remove_all clears all contextual metadata. The context field is ignored.

The key-value pairs to merge. Required for add; ignored for remove_all.
An empty value deletes that key rather than storing an empty string, so "alt=" removes alt while leaving other keys intact. Deletes and sets may be combined: "alt=|owner=new".
A literal = or | inside a value must be escaped with a prepending backslash, and a literal backslash must be doubled. A double quote must not be escaped.

The public IDs of the assets to apply the operation to. At most 1000 are processed per request; any beyond the first 1000 are ignored rather than rejected. Public IDs that do not exist, or that the caller lacks update permission for, are skipped rather than failing the request, so the returned public_ids may be shorter than the requested list.

The delivery type of the assets to operate on. Defaults to upload.

The type of resource (image, video, or raw).

The structured metadata values to assign and the assets to assign them to.

Whether to clear a value already stored on the asset that is no longer valid — for example because its datasource entry was deleted — instead of failing the update for that asset. Applies only to fields governed by an active conditional metadata rule; an invalid value sent in this request is always rejected. Default is false.

A pipe-separated list or a map of custom metadata fields (by external_id) and the values to assign to each of them. The = " and | characters can be supported as values when escaped with a prepended backslash (\). For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.

The public IDs of the assets to apply the operation to. At most 1000 are processed per request; any beyond the first 1000 are ignored rather than rejected. Public IDs that do not exist, or that the caller lacks update permission for, are skipped rather than failing the request, so the returned public_ids may be shorter than the requested list.

The delivery type of the assets to operate on. Defaults to upload.

The date for which to retrieve usage details (YYYY-MM-DD). If not specified, returns the current usage.

The asset ID of the resource. Must be a 32-character hexadecimal string.

The asset IDs to relate.

Relates the asset to all the assets specified in this array of up to 10 assets, specified by their asset IDs.

The asset ID of the resource. Must be a 32-character hexadecimal string.

The asset IDs to unrelate.

Unrelates the asset from all the assets specified in this array of assets, specified by their asset IDs.

The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.

The new folder path.

The new path for the folder.

The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.

The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.

The (Lucene-like) string expression specifying the search query. If not passed, returns all folders (up to max_results).

Sort order for the results. Each item maps a field name to a direction.

Maximum number of folders to return (max 500, default 50).

The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.

The search query parameters.

Fields or ranges to aggregate search results by. Requires a Tier 2 search plan; on Tier 1 the field is accepted but aggregations are omitted from the response.

The Lucene-like search expression. Supports token match (:), exact match (=), trailing * for prefix match, ranges ([a TO b], {a TO b}), and comparisons (>, <, >=, <=). Combine terms with uppercase AND, OR, NOT, or +/-. NOT must appear between clauses — a leading NOT is a parse error; use -field:value to negate the first clause. Group with parentheses.

Wrap values containing spaces, colons, or other reserved characters (! ( ) { } [ ] ^ ~ ? \ = & < > |) in double quotes, e.g. tags:"service:mantels", tags:"brand:openhaul", aspect_ratio:"16:9". Send raw </>, never HTML-escaped.

Wildcards are prefix-only (trailing *). A bare * (e.g. folder:*, context.alt:*, metadata.key:*, tags:*, -tags:*) is a parse error — there is no "has any value" / presence probe. Either drop the clause, use a concrete prefix, or filter on a known token.

Dates: ISO-8601 in quotes (uploaded_at>"2024-01-15", created_at>"2026-01-01T00:00:00Z"), or relative shorthand Nh, Nd, Nw (uploaded_at>1d, created_at:[4w TO 1w]).

Supported fields: public_id, asset_id, filename, display_name, folder / asset_folder (singular, not folders), tags, context.<key>, metadata.<external_id>, resource_type, type, format, bytes, width, height, duration, pages, aspect_ratio, transparent, grayscale, status, moderation_status, moderation_kind, uploaded_at, created_at, taken_at, updated_at, last_updated.<kind>, face_count, illustration_score, quality_score. Fields under image_metadata.*, image_analysis.*, quality_analysis.*, and accessibility_analysis.* also require the matching with_field to be returned in the response.

See the [search expressions guide](https://cloudinary.com/documentation/search_expressions.md) for the full reference.

A comma-separated list of fields to include in the response.
Notes:

• This parameter takes precedence over the with_field parameter, so if you want any additional asset attributes returned, make sure to also include them in this list (e.g., tags or context).
• The following fields are always included in the response: public_id, asset_id, asset_folder, created_at, status, type, and resource_type.

The maximum number of results to return. Default - 50. Maximum - 500.
Set to 0 to get only total_count and aggregations without any resources in the response — useful for counting or aggregation-only queries.

The cursor value to get the next page of results. Available when a previous search returned more results than max_results.

An array of single-key objects mapping a field to a sort direction. Each object must contain exactly one field name mapped to 'asc' or 'desc'.
Default: [{"created_at": "desc"}].

The additional asset attributes to include in each search result. The fields parameter takes precedence over this parameter. image_metadata, image_analysis, and metadata require a Tier 2 search plan.

The visual search parameters.

A JSON object containing the generation request parameters.

Whether to perform the generation asynchronously. When true, the API
returns immediately with a 202 and completes in the background. Once
complete, a webhook notification is sent to the specified URL and/or to
the URLs defined in the product environment's settings.

Desired output image format. Optional; defaults to png when omitted.
Mapped to the closest format the chosen model supports — webp falls
back to png on models that don't support it (e.g. FLUX.2 Pro), and the
request is ignored entirely by models that don't expose a format option
(e.g. Recraft).

Desired output size, given in one of two mutually exclusive forms:

* DimensionsImageSize: width and height in pixels, for precise
control.
* DeclarativeImageSize: aspect_ratio (and an optional resolution
tier), resolved server-side to the closest size the chosen model
supports. This is the portable form: most providers natively accept
an aspect ratio plus a resolution tier rather than raw pixels.

Omit image_size entirely to use the model's default size.

Selects the model, in one of three mutually exclusive forms (omit to use
the default: nano-banana-2, or nano-banana-2-edit for
image-to-image):
* ModelByFamily: family (+ optional tier); the stable-over-time
selector.
* ModelById: an explicit id, pinning one exact model.
* ModelAuto: mode: auto, letting the service choose the model for
the request (+ optional preference).

The webhook URL to notify when the generation is complete. Only relevant when async is set to true.

The text description of the image to generate.

Seed for reproducible generation. Supported by the flux, nano-banana
and ideogram models and by qwen-image-3; silently ignored by the
models that don't support it, which report seed as null in the
response.

Where the generated image goes, determined by target_type. Use
temporary when the user only wants the image: a short-lived URL,
nothing saved to their account. Omit it, or use managed_asset, to
store the image permanently in their Media Library. If the caller lacks
upload permission, the image is returned as temporary instead, with a
warning notice.

A JSON object containing the image-to-image generation request parameters.

Whether to perform the generation asynchronously. When true, the API
returns immediately with a 202 and completes in the background. Once
complete, a webhook notification is sent to the specified URL and/or to
the URLs defined in the product environment's settings.

Desired output image format. Optional; defaults to png when omitted.
Mapped to the closest format the chosen model supports — webp falls
back to png on models that don't support it (e.g. FLUX.2 Pro), and the
request is ignored entirely by models that don't expose a format option
(e.g. Recraft).

Desired output size, given in one of two mutually exclusive forms:

* DimensionsImageSize: width and height in pixels, for precise
control.
* DeclarativeImageSize: aspect_ratio (and an optional resolution
tier), resolved server-side to the closest size the chosen model
supports. This is the portable form: most providers natively accept
an aspect ratio plus a resolution tier rather than raw pixels.

Omit image_size entirely to use the model's default size.

Selects the model, in one of three mutually exclusive forms (omit to use
the default: nano-banana-2, or nano-banana-2-edit for
image-to-image):
* ModelByFamily: family (+ optional tier); the stable-over-time
selector.
* ModelById: an explicit id, pinning one exact model.
* ModelAuto: mode: auto, letting the service choose the model for
the request (+ optional preference).

The webhook URL to notify when the generation is complete. Only relevant when async is set to true.

The text instruction describing the desired edit / output.

Reference images that steer the generation, in order (1-indexed; the
prompt may address them positionally as [1], [2], …). Each entry
is either a managed asset (by asset_id) or an external url. The
platform accepts up to 4; a specific model may accept fewer — the
recraft-v3-edit and mai-image edit models accept 1, and the
grok-imagine and qwen-image edit models accept 3. Exceeding the
selected model's capacity returns 400.

Seed for reproducible generation. Supported by the flux, nano-banana
and ideogram models and by qwen-image-3; silently ignored by the
models that don't support it, which report seed as null in the
response.

Where the generated image goes, determined by target_type. Use
temporary when the user only wants the image: a short-lived URL,
nothing saved to their account. Omit it, or use managed_asset, to
store the image permanently in their Media Library. If the caller lacks
upload permission, the image is returned as temporary instead, with a
warning notice.

The ID of the generation task.

Case-insensitive filter on the collection name. Returns collections with a word in their name that starts with this text (for example, sum matches "Summer Campaign").

Sort expression: <field> <direction>, optionally comma-separated for a multi-key sort (e.g. name asc, created_at desc). field is one of name, created_at, or updated_at, the same field names the response uses, and direction is asc or desc. Defaults to updated_at desc.

Maximum number of collections to return (1-100, default 20).

Opaque cursor from a previous response's next_cursor to fetch the next page.

Configuration for a dynamic collection. Required when creating a dynamic collection, and not allowed for a manual collection.

The [search expression](search_expressions) that defines which assets are included in a dynamic collection. Cloudinary evaluates the expression against your product environment's assets, so the collection's contents update as assets begin or stop matching the criteria. In the Media Library, a collection whose expression was set through the API shows it as a single Expression filter; any filters added to the collection there are combined with it using AND.

Optional description of the collection.

Name of the collection.

Type of the collection. manual holds an explicit asset list and starts empty until you add assets with the Add assets to a collection endpoint; dynamic is defined by a saved filter expression and is populated automatically.

External ID of the collection to retrieve, update, or delete.

External ID of the collection to retrieve, update, or delete.

The collection attributes to update. Only the fields you include are changed. A collection's type is set when the collection is created and can't be changed.

Configuration for a dynamic collection. Required when creating a dynamic collection, and not allowed for a manual collection.

The [search expression](search_expressions) that defines which assets are included in a dynamic collection. Cloudinary evaluates the expression against your product environment's assets, so the collection's contents update as assets begin or stop matching the criteria. In the Media Library, a collection whose expression was set through the API shows it as a single Expression filter; any filters added to the collection there are combined with it using AND.

New description for the collection. Send null or an empty string to clear it. Omit to leave the current description unchanged.

New name for the collection. Omit to leave the current name unchanged.

External ID of the collection to retrieve, update, or delete.

External ID of the collection whose assets to list, add, or remove.

Sort expression: <field> <direction>, optionally comma-separated for a multi-key sort (e.g. bytes desc, created_at asc). field is one of created_at, uploaded_at, public_id, display_name, or bytes, and direction is asc or desc. Defaults to created_at desc. When paging with next_cursor, send the same sort_by on every page; a cursor is only valid for the sort it was issued with.

Maximum number of assets to return (1-100, default 20).

Opaque cursor from a previous response's next_cursor to fetch the next page. Send it with the same sort_by (and max_results) as the request that returned it.

External ID of the collection whose assets to list, add, or remove.

External ID of the collection whose assets to list, add, or remove.

External ID of the collection to create or list public pages for.

Settings for the public page. Every field is optional; omitted fields use their documented default.

When the page becomes active. If omitted or null, the page is active immediately.

When true, any name in download_transformations that isn't yet set as a transformation template is set as one automatically. It then appears in the Console's templates list and counts toward your product environment's template limit. When false or omitted, the request instead fails with download_transformation_not_available if any listed name isn't yet set as a transformation template, and nothing is changed.

Named transformations that viewers of the public page can apply when downloading assets, referenced by name (see the Admin API's [Get transformations](admin_api#get_transformations) endpoint to list the named transformations in your product environment). By default, each name must already be set as a transformation template; set create_download_transformations to true to set any listed name that isn't one yet automatically. Omit or pass null to leave the page without download transformations. At most 200 entries.

When the page expires. If omitted or null, the page never expires.

Optional display name for the public page.

Whether viewers can download the original asset. Omit to use the account default set by an administrator in the [Media Library Preferences](dam_admin_media_library_options#download_options_for_external_sharing).

External ID of the collection to create or list public pages for.

External ID of the collection the public page belongs to.

External ID of the public page.

External ID of the collection the public page belongs to.

External ID of the public page.

Partial-update payload. Only the fields you include are forwarded and changed; any field you omit is left unchanged. Sending null does not clear a value.

Whether any email address is allowed to access the page when it is protected. After the update, an email_otp page needs allow_any: true or at least one entry in allowed_emails or allowed_domains; otherwise the request fails with 400 invalid_protection_settings. Omit to leave the current value unchanged.

Email domains allowed to access the page when it is protected, as bare lowercase domains such as example.com. The list replaces the current one; send an empty array to clear it (the page must still satisfy the allow_any rule). Together with allowed_emails, at most 500 entries. Omit to leave the current value unchanged.

Email addresses allowed to access the page when it is protected. The list replaces the current one; send an empty array to clear it (the page must still satisfy the allow_any rule). Together with allowed_domains, at most 500 entries. Omit to leave the current value unchanged.

New activation time for the page. Omit to leave the current value unchanged.

When true, any name in download_transformations that isn't yet set as a transformation template is set as one automatically. It then appears in the Console's templates list and counts toward your product environment's template limit. When false or omitted, the request instead fails with download_transformation_not_available if any listed name isn't yet set as a transformation template, and nothing is changed.

URL of a custom HTML page in your product environment to use in place of the public page's default design. It must be an https URL on a cloudinary.com host that belongs to this product environment, at most 2048 bytes. Setting it requires the custom collection layout feature on your plan; otherwise the request fails with 403. Pass an empty string to return to the default design. Omit to leave the current value unchanged.

Named transformations that viewers of the public page can apply when downloading assets, referenced by name (see the Admin API's [Get transformations](admin_api#get_transformations) endpoint to list the named transformations in your product environment). The list replaces the page's current download transformations; pass an empty list to remove them all. Omit to leave the current value unchanged. At most 200 entries.

New expiry time for the page. Omit to leave the current value unchanged.

New display name for the public page. Omit to leave the current value unchanged.

Secured-sharing protection mode. none removes protection and clears the allowed emails, domains and allow_any. email_otp protects the page so viewers must verify an allowed email address with a one-time passcode; a protected page needs at least one allowed email or domain, or allow_any: true. Omit to leave the current mode unchanged: on a protected page the allowlist fields below then update its allowlist, but on an unprotected page they are ignored, so send email_otp to protect it.

Whether viewers may download the original asset. Omit to leave the current value unchanged.

External ID of the collection the public page belongs to.

External ID of the public page.

The public ID of the existing asset to transform

VALIDATED transformation string using ONLY parameters from get-tx-reference docs. Examples: 'c_fill,w_300,h_200' or 'e_sepia/a_90'. MUST follow component rules: commas within components, slashes between components.

The resource type of the asset

Whether to invalidate cached versions

One or more sets of Cloudinary Upload API parameters to sign. Returns one signed credential object per entry, in the same order. Only genuine Upload API params are signed; file, resource_type, api_key, and signature are excluded.