openapi: 3.1.0
info:
  title: Cloudinary Asset Management API
  version: 0.7.7 # x-release-please-version
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    name: Cloudinary Support
    email: support@cloudinary.com
    url: https://support.cloudinary.com
  termsOfService: https://cloudinary.com/tou
servers:
  - url: https://{region}.cloudinary.com
    description: Regional API endpoints for optimal performance.
    variables:
      region:
        default: api
        description: Regional endpoint selection
        enum:
          - api
          - api-eu
          - api-ap
  - url: https://{host}
    description: Custom domains for enterprise deployments.
    variables:
      host:
        default: api.cloudinary.com
        description: API host domain.
security:
  - basicAuth: []
  - oauth2:
      - asset_management
      - upload
      - media_generation
tags:
  - name: upload
    description: Uploads files to the active product environment.
  - name: assets
    description: Enables you to manage all the resources (assets) stored in your product environment.
  - name: asset_relations
    description: Enables you to manage relationships between assets.
  - name: asset_metadata
    description: Enables you to manage the tags, contextual metadata, and structured metadata values stored on specific assets.
  - name: video_analytics
    description: Gets video analytics
  - name: explode
    description: Generates derived images from a multi-frame/page file.
  - name: tags
    description: Enables you to manage the tags used in your product environment.
  - name: backups
    description: Enables you to manage backup versions.
  - name: initial_backup
    description: Enables you to initiate and track an initial backup of existing assets in your product environment.
  - name: folders
    description: Enables you to manage the asset folders in your product environment.
  - name: usage
    description: Gets usage details
  - name: search
    description: APIs for searching resources using text and visual search capabilities
  - name: people
    description: APIs for accessing and managing face recognition results.
  - name: Generation
    description: Generate images from text prompts using AI models.
  - name: Tasks
    description: Query the status of async generation tasks.
paths:
  /v1_1/{cloud_name}/{resource_type}/upload:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/upload_resource_type'
    post:
      operationId: upload
      summary: Uploads media assets (images, videos, raw files) to your Cloudinary product environment
      description: |
        Uploads media assets (images, videos, raw files) to your Cloudinary product environment. The file is securely stored
        in the cloud with backup and revision history. Cloudinary automatically analyzes and saves important data about each
        asset, such as format, size, resolution, and prominent colors, which is indexed to enable searching on those attributes.

        Supports uploading from:
        - Local file paths (SDKs/MCP server only). For MCP server path MUST start with file://
        - Remote HTTP/HTTPS URLs
        - Base64 Data URIs (max ~60 MB)
        - Private storage buckets (S3 or Google Storage)
        - FTP addresses

        The uploaded asset is immediately available for transformation and delivery upon successful upload.

        Transform media files using transformation syntax in delivery URLs, which creates derived files accessible immediately without re-uploading the original.
      tags:
        - upload
      x-speakeasy-mcp:
        name: upload-asset
        scopes:
          - librarian
          - builder
        title: Upload Asset
      requestBody:
        $ref: '#/components/requestBodies/upload_request_body'
      responses:
        '200':
          description: Successful upload
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/upload_response'
                  - $ref: '#/components/schemas/async_upload_response'
        '302':
          description: Redirect to callback URL (when 'callback' parameter is provided and request is not XHR).
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/html_redirect'
        '400':
          description: Bad request (e.g., missing parameters, invalid type, target exists without overwrite)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Not allowed (e.g., insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found (e.g. when uploading from a remote URL that does not exist)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/upload:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    post:
      operationId: uploadNoResourceType
      summary: Upload with automatic file type detection
      description: Uploads a file to Cloudinary. The file type is automatically detected based on its content, so you don't need to specify the type manually.
      tags:
        - upload
      x-speakeasy-mcp:
        disabled: true
      requestBody:
        $ref: '#/components/requestBodies/upload_request_body'
      responses:
        '200':
          description: Successful upload
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/upload_response'
                  - $ref: '#/components/schemas/async_upload_response'
        '302':
          description: Redirect to callback URL (when 'callback' parameter is provided and request is not XHR).
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/html_redirect'
        '400':
          description: Bad request (e.g., missing parameters, invalid type, target exists without overwrite)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Not allowed (e.g., insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found (e.g. when uploading from a remote URL that does not exist)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/upload_chunked:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/upload_resource_type'
    post:
      operationId: uploadChunk
      summary: Upload a single chunk of a large file
      description: |
        Uploads a single chunk of a large file as part of a chunked upload process. This enables efficient upload of
        large files with the ability to resume interrupted uploads. Each request uploads one chunk of the file.
        It is required for any files that are larger than 100 MB. This is often relevant for video files, as they
        tend to have larger file sizes. Minimum chunk size is 5 MB.

        The `file` field accepts either the chunk bytes (multipart) or an HTTP/HTTPS URL. When a URL is supplied,
        Cloudinary downloads it and validates the response `Content-Length` against the chunk-size contract
        (exact match in the uniform-size flow; within 5 MB floor and 5 GiB cap in explicit-order mode) before
        storing any bytes. A mismatch aborts with 400 and persists no state. The remote server must return a
        `Content-Length` header; chunked transfer-encoded responses are rejected.

        **Explicit-order totals** (`X-Upload-Part-Number`): `X-Upload-Total-Parts` may be omitted on non-terminal
        chunks until the session total *N* is established by any earlier chunk that sent the header. After *N* is
        known, the chunk for part index *N* must include `X-Upload-Total-Parts: N`. Whenever the header appears,
        its value must be the same integer *N* for that `X-Unique-Upload-Id` (no conflicting totals).
      tags:
        - upload
      x-speakeasy-mcp:
        disabled: true
        scopes:
          - librarian
      parameters:
        - name: Content-Range
          in: header
          required: false
          schema:
            type: string
          description: |
            The range of bytes being uploaded in the current chunk, in the format "bytes start-end/total".
            For example, "bytes 0-999999/3000000" indicates the first 1MB chunk of a 3MB file. Required for the
            default uniform-size chunked upload flow. In explicit-order mode (`X-Upload-Part-Number`), this
            header remains optional; clients do not have to send `Content-Range`, `X-Upload-Part-Number`, and
            `X-Upload-Total-Parts` together on every request—`X-Upload-Total-Parts` may be omitted on some chunks
            subject to the rules documented on that header.
          example: bytes 0-999999/3000000
        - name: X-Unique-Upload-Id
          in: header
          required: true
          schema:
            type: string
          description: A unique identifier for the upload. Must be the same for all chunks of the same file.
          example: 2fd4e1c67a2d28fce
        - name: X-Upload-Part-Number
          in: header
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
          description: |
            The 1-based part number for this chunk when uploading parts of uneven size with explicit
            client-supplied order. Requires `X-Unique-Upload-Id`. When present, activates explicit-order mode
            and `Content-Range` is optional. Parts must use contiguous indices `1`…`N`, where `N` is the session
            total. If `X-Upload-Total-Parts` is omitted on a chunk, the server still enforces `X-Upload-Part-Number ≤ N`
            once `N` has been learned from any prior chunk for the same upload that supplied `X-Upload-Total-Parts`.
          example: 2
        - name: X-Upload-Total-Parts
          in: header
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
          description: |
            Declared session total `N` (optional on chunks where omission is allowed). When present on a chunk,
            it must satisfy either `X-Upload-Part-Number < X-Upload-Total-Parts` (non-terminal) or
            `X-Upload-Part-Number == X-Upload-Total-Parts` (terminal). The same integer `N` must appear whenever
            this header is sent for a given `X-Unique-Upload-Id` (no conflicting declared totals). Chunks may omit
            the header entirely until `N` is established; after `N` is known, non-terminal indices may still omit
            it. Once `N` is known for the session, the request for part index `N` (the final part) must include
            `X-Upload-Total-Parts: N`. The upload completes when all parts `1`…`N` have been received.
          example: 3
      requestBody:
        $ref: '#/components/requestBodies/upload_request_body'
      responses:
        '200':
          description: Chunk upload successful. For all but the final chunk, this returns upload status. For the final chunk, it returns the complete upload response.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/non_final_chunk_upload_response'
                  - $ref: '#/components/schemas/upload_response'
                  - $ref: '#/components/schemas/async_upload_response'
        '302':
          description: Redirect to callback URL (when 'callback' parameter is provided and request is not XHR).
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/html_redirect'
        '400':
          description: |
            Bad request. Examples: invalid Content-Range format; chunk size below the 5 MB minimum
            (non-final parts); part_number outside 1..total_parts; when `file` is a URL: Content-Length
            missing, Content-Length does not match the declared chunk size, Content-Length exceeds the
            5 GiB per-chunk cap, or the remote server returned a non-2xx status.

            Explicit-order mode examples: `X-Upload-Total-Parts` disagrees with an earlier declared total for the
            same upload; part index `N` reached without `X-Upload-Total-Parts` after `N` was already established;
            `X-Upload-Part-Number` greater than `X-Upload-Total-Parts`; non-terminal chunk shape where
            `X-Upload-Part-Number` equals `X-Upload-Total-Parts` but the part is not the terminal index (invalid
            combination for the declared totals).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Not allowed (e.g., insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/rename:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    post:
      x-speakeasy-mcp:
        name: asset-rename
        scopes:
          - librarian
        title: Asset Rename
        idempotentHint: true
      summary: Updates an existing asset's identifier (public ID) and optionally other metadata in your Cloudinary account
      tags:
        - assets
      operationId: renameAsset
      requestBody:
        description: The rename request parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rename_request'
      responses:
        '200':
          description: Asset renamed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/upload_response'
        '400':
          description: Bad request (e.g., missing parameters, invalid type, target exists without overwrite)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Source asset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/download:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    get:
      x-speakeasy-mcp:
        name: download-asset
        disabled: true
        scopes:
          - admin
      summary: Generates a download link for a specific asset (image)
      tags:
        - assets
      operationId: downloadAsset
      parameters:
        - $ref: '#/components/parameters/public_id_query'
        - name: format
          in: query
          required: false
          schema:
            type: string
          description: The format to convert the asset to before downloading.
        - $ref: '#/components/parameters/delivery_type_query'
        - name: expires_at
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Unix timestamp indicating when the download URL should expire.
        - name: attachment
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to force download as an attachment.
        - name: target_filename
          in: query
          required: false
          schema:
            type: string
          description: The desired filename for the downloaded file.
        - name: transformation
          in: query
          required: false
          schema:
            type: string
          description: A transformation to apply to the asset before downloading.
        - $ref: '#/components/parameters/api_key_query'
        - $ref: '#/components/parameters/signature_query'
        - $ref: '#/components/parameters/timestamp_query'
      responses:
        '200':
          description: Asset downloaded successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
            video/*:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request (e.g., missing parameters, invalid format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden (e.g., insufficient permissions for private assets)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/destroy:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    post:
      operationId: destroyAsset
      summary: Destroys an asset/resource
      tags:
        - upload
      requestBody:
        description: The asset to destroy and related options.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/destroy_request'
      responses:
        '200':
          description: Asset/resource destroyed successfully or not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destroy_response'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset/resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/explode:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          enum:
            - image
        description: The type of resource to explode. Only "image" is supported.
    post:
      summary: Create derived images from multi-page file
      description: Generates derived images for each of the individual pages/frames in a multi-page/frame file (such as a PDF or animated image).
      tags:
        - explode
      operationId: explodeResource
      requestBody:
        description: The explode operation parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/explode_request'
      responses:
        '200':
          description: Explode operation started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/explode_response'
        '400':
          description: Bad request (e.g., missing pg_all parameter, invalid transformation)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/explicit:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    post:
      summary: Apply operations on an existing asset
      description: |
        Applies actions such as transformations, tags, or metadata updates to an existing asset without re-uploading it.
        This is useful for applying new transformations, adding tags, or updating metadata on assets that are already in your cloud.

        Note: Always prefer delivery URL transformations over this method, unless eager transformations are specifically required.
      tags:
        - assets
      operationId: explicitAsset
      requestBody:
        description: The asset and operations to apply.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/explicit_request'
      responses:
        '200':
          description: Operations applied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/upload_response'
        '400':
          description: Bad request (e.g., missing parameters, invalid type)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden (e.g., insufficient permissions for private assets)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/tags:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    post:
      x-speakeasy-mcp:
        name: manage-asset-tags
        scopes:
          - librarian
        title: Manage Asset Tags
        destructiveHint: true
      summary: Adds, removes, or replaces tags on multiple assets
      description: |
        Applies a tag command to the given assets, addressing them by public ID.

        The number of tags multiplied by the number of public IDs must not exceed 10,000.
      tags:
        - asset_metadata
      operationId: updateAssetsTags
      requestBody:
        description: The tag command, the tags to apply, and the assets to apply them to.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tags_update_request'
            example:
              command: add
              public_ids:
                - sample
                - product_image
                - banner_2023
              tags:
                - animal
                - dog
      responses:
        '200':
          description: Tag command applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_ids_response'
              example:
                public_ids:
                  - sample
                  - product_image
                  - banner_2023
        '400':
          description: Bad request (e.g., invalid command, blank tag, tag containing a comma, or the 10,000 tags-times-assets limit exceeded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: 'Invalid command - bogus. Must be one of: add, remove, replace, remove_all'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: api_secret mismatch
        '403':
          description: Forbidden (e.g., insufficient permissions for the requested assets)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: This token is unauthorized to perform the requested action
  /v1_1/{cloud_name}/{resource_type}/context:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    post:
      x-speakeasy-mcp:
        name: manage-asset-context
        scopes:
          - librarian
        title: Manage Asset Contextual Metadata
        destructiveHint: true
      summary: Adds or clears contextual metadata on multiple assets
      description: |
        Applies a contextual-metadata command to the given assets, addressing them by public ID.
      tags:
        - asset_metadata
      operationId: updateAssetsContext
      requestBody:
        description: The context command, the metadata to apply, and the assets to apply it to.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/context_update_request'
            example:
              command: add
              public_ids:
                - sample
                - product_image
                - banner_2023
              context: alt=My image|caption=Nice photo
      responses:
        '200':
          description: Context command applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_ids_response'
              example:
                public_ids:
                  - sample
                  - product_image
                  - banner_2023
        '400':
          description: Bad request (e.g., invalid command, or `context` missing when adding)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Missing required parameter - context
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: api_secret mismatch
        '403':
          description: Forbidden (e.g., insufficient permissions for the requested assets)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: This token is unauthorized to perform the requested action
  /v1_1/{cloud_name}/{resource_type}/metadata:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/resource_type'
    post:
      x-speakeasy-mcp:
        name: manage-asset-metadata
        scopes:
          - librarian
        title: Manage Asset Structured Metadata
        destructiveHint: true
      summary: Sets structured metadata values on multiple assets
      description: |
        Assigns structured metadata field values to the given assets, addressing them by public ID.

        Values are merged into each asset's existing structured metadata: fields not mentioned
        keep their current values, and an empty value clears the field. Every referenced field
        must already exist in the product environment. Conditional metadata rules are evaluated
        as part of the update.
      tags:
        - asset_metadata
      operationId: updateAssetsMetadata
      requestBody:
        description: The structured metadata values to assign and the assets to assign them to.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/metadata_update_request'
            example:
              public_ids:
                - sample
                - product_image
                - banner_2023
              metadata:
                in_stock_id: 50
                color_id:
                  - green
                  - red
      responses:
        '200':
          description: Structured metadata applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/public_ids_response'
              example:
                public_ids:
                  - sample
                  - product_image
                  - banner_2023
        '400':
          description: Bad request (e.g., unknown metadata field, invalid value for the field type, or no metadata fields defined in the product environment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: 'The following metadata fields do not exist: ["colour_id"]'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: api_secret mismatch
        '403':
          description: Forbidden (e.g., insufficient permissions for the requested assets)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: This token is unauthorized to perform the requested action
  /v1_1/{cloud_name}/{resource_type}/generate_archive:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/archive_resource_type'
    post:
      x-speakeasy-mcp:
        name: generate-archive
        scopes:
          - librarian
        title: Generate Archive
      summary: Creates an archive (ZIP or TGZ file) that contains a set of assets from your product environment.
      description: Creates a downloadable ZIP or other archive format containing the specified resources.
      tags:
        - assets
      operationId: generateArchive
      requestBody:
        description: The archive generation parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/generate_archive_request'
      responses:
        '200':
          description: Archive successfully generated or downloaded
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/generate_archive_response'
              example:
                asset_id: 3cd9f196fe3ee1882c0f66223bc568f9
                public_id: atufggsrkjjefdsy90nr.zip
                version: 1747234673
                version_id: 42f240f70d86aab6e9249fe5b664c237
                signature: 689ea4a513604414f44f0d779fc7d049bbdad6d2
                resource_type: raw
                created_at: '2025-05-14T14:57:53Z'
                tags: []
                bytes: 3574651
                type: upload
                etag: 47ac8d2c1b74ac107937d6e9181dd047
                placeholder: false
                url: http://res.cloudinary.com/customerafdb058c4adc/raw/upload/v1747234673/atufggsrkjjefdsy90nr.zip
                secure_url: https://res.cloudinary.com/customerafdb058c4adc/raw/upload/v1747234673/atufggsrkjjefdsy90nr.zip
                asset_folder: ''
                display_name: koetjd3qrme0cfcfnjet.zip
                resource_count: 6
                file_count: 6
        '400':
          description: Bad request (e.g., missing parameters, invalid format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/download_backup:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    get:
      x-speakeasy-mcp:
        name: download-asset-backup
        scope:
          - advanced_librarian
        title: Download Asset Backup
        readOnlyHint: true
        idempotentHint: true
      summary: Download a backup copy of an asset
      tags:
        - assets
      operationId: downloadBackupAsset
      parameters:
        - $ref: '#/components/parameters/asset_id_query'
        - name: version_id
          in: query
          required: true
          schema:
            type: string
            pattern: ^[0-9a-f]{32}$
          description: The version ID of the backup to download. Must be a 32-character hexadecimal string.
          example: a3978316b0045e5eaf198f4d6885ca35
        - $ref: '#/components/parameters/api_key_query'
        - $ref: '#/components/parameters/signature_query'
        - $ref: '#/components/parameters/timestamp_query'
      responses:
        '200':
          description: Asset backup downloaded successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            image/*:
              schema:
                type: string
                format: binary
            video/*:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              examples:
                illegal_id:
                  summary: Invalid or non-existent asset_id/version_id
                  value:
                    error:
                      message: Illegal id
                missing_version_id:
                  summary: Missing version_id parameter
                  value:
                    error:
                      message: Missing required parameter - version_id
                missing_asset_id:
                  summary: Missing asset_id parameter
                  value:
                    error:
                      message: Missing required parameter - asset_id
                stale_request:
                  summary: Request timestamp is too old
                  value:
                    error:
                      message: Stale request - reported time is {timestamp} which is more than 1 hour ago
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              examples:
                invalid_signature:
                  summary: Invalid signature with signing string
                  value:
                    error:
                      message: Invalid Signature {signature}. String to sign - '{parameters}'.
                expired_timestamp:
                  summary: Request has expired
                  value:
                    error:
                      message: Request timestamp expired
        '404':
          description: Version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/asset/destroy:
    post:
      x-speakeasy-mcp:
        name: delete-asset
        scopes:
          - admin
        title: Delete Asset
        destructiveHint: true
        idempotentHint: true
      summary: Delete asset by asset ID
      description: |
        Deletes an asset using its immutable asset ID.
      tags:
        - assets
      operationId: destroyByAssetId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The asset to delete and related options.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/destroy_by_asset_id_request'
      responses:
        '200':
          description: Resource successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/destroy_by_asset_id_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/asset/download:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    get:
      x-speakeasy-mcp:
        name: download-asset-by-asset-id
        disabled: true
        scopes:
          - admin
      summary: Download an asset by asset ID
      description: |
        Generates a download link for a specific asset identified by its immutable asset ID,
        instead of the resource type, delivery type and public ID.
      tags:
        - assets
      operationId: downloadAssetByAssetId
      parameters:
        - $ref: '#/components/parameters/asset_id_query'
        - name: format
          in: query
          required: false
          schema:
            type: string
          description: The format to convert the asset to before downloading.
        - name: transformation
          in: query
          required: false
          schema:
            type: string
          description: A transformation to apply to the asset before downloading.
        - name: attachment
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to force download as an attachment.
        - name: target_filename
          in: query
          required: false
          schema:
            type: string
          description: The desired filename for the downloaded file.
        - name: streaming_attachment
          in: query
          required: false
          schema:
            type: boolean
          description: Whether to stream a video asset as an attachment.
        - name: expires_at
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: Unix timestamp indicating when the download URL should expire.
        - $ref: '#/components/parameters/api_key_query'
        - $ref: '#/components/parameters/signature_query'
        - $ref: '#/components/parameters/timestamp_query'
      responses:
        '200':
          description: Asset downloaded successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
            video/*:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request (e.g., missing or invalid asset_id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden (e.g., insufficient permissions for private assets)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/{resource_type}/text:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          enum:
            - image
        description: The type of resource to create. Must be "image" for text generation.
    post:
      summary: Create image from text
      description: Dynamically generates an image from a specified text string.
      tags:
        - upload
      operationId: text
      requestBody:
        description: The text content and styling parameters for image generation.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/text_request'
      responses:
        '200':
          description: Text image created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/text_response'
        '400':
          description: Bad request (e.g., missing required parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/video/concat:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    post:
      operationId: concat
      summary: Concatenate ordered video segments into a single MP4 asset
      description: |
        Accepts an ordered list of remote HTTP(S) URLs pointing to video segments
        and concatenates them, remuxing the result into a single MP4 asset that is
        uploaded to your product environment using the supplied upload parameters.
        Concatenation and the resulting upload happen asynchronously; supply a
        `notification_url` to be notified when the upload completes.
      tags:
        - upload
      x-speakeasy-mcp:
        name: concat
        scopes:
          - librarian
          - builder
        title: Concatenate Video Segments
        disabled: true
      requestBody:
        description: The concat request parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/concat_request'
      responses:
        '200':
          description: concat job accepted; the upload completes asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/concat_response'
        '400':
          description: Bad request (e.g., missing urls, invalid upload parameters).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources:
    get:
      summary: Get resource types
      description: Returns a list of all resource types that correspond to assets currently in your product environment.
      tags:
        - assets
      operationId: listResourceTypes
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      responses:
        '200':
          description: The list of resource types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource_types_response'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/api_error'
                  - example:
                      error:
                        message: Invalid credentials
  /v1_1/{cloud_name}/resources/image:
    get:
      x-speakeasy-mcp:
        name: list-images
        scopes:
          - librarian
        title: List Images
        readOnlyHint: true
        idempotentHint: true
      summary: Get image assets
      description: |
        Retrieves a list of image assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
      tags:
        - assets
      operationId: listImages
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/delivery_type_all_query'
        - $ref: '#/components/parameters/prefix'
        - $ref: '#/components/parameters/public_ids_query'
        - $ref: '#/components/parameters/tags_query'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/start_at'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/video:
    get:
      x-speakeasy-mcp:
        name: list-videos
        scopes:
          - librarian
        title: List Videos
        readOnlyHint: true
        idempotentHint: true
      summary: Get video assets
      description: |
        Retrieves a list of video assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
      tags:
        - assets
      operationId: listVideos
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/delivery_type_all_query'
        - $ref: '#/components/parameters/prefix'
        - $ref: '#/components/parameters/public_ids_query'
        - $ref: '#/components/parameters/tags_query'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/start_at'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/raw:
    get:
      x-speakeasy-mcp:
        name: list-files
        scopes:
          - librarian
        title: List Files
        readOnlyHint: true
        idempotentHint: true
      summary: Get raw assets
      description: |
        Retrieves a list of raw assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
      tags:
        - assets
      operationId: listRawFiles
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/delivery_type_all_query'
        - $ref: '#/components/parameters/prefix'
        - $ref: '#/components/parameters/public_ids_query'
        - $ref: '#/components/parameters/tags_query'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/start_at'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/by_asset_folder:
    get:
      summary: Get resources by asset folder
      description: Retrieves a list of resources within a specific asset folder. Requires folder decoupling to be enabled.
      tags:
        - assets
      operationId: listResourcesByAssetFolder
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_folder_query'
        - $ref: '#/components/parameters/resource_type_query'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/by_asset_ids:
    get:
      summary: Get resources by asset IDs
      description: Retrieves details for specific resources using their asset IDs (or external IDs).
      tags:
        - assets
      operationId: listResourcesByAssetIDs
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_ids_query'
        - $ref: '#/components/parameters/resource_type_query'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: One or more asset IDs not found (partial success possible)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/{resource_type}/context:
    get:
      summary: Get resources by context
      description: Retrieves resources matching specific context key/value pairs.
      tags:
        - assets
      operationId: listResourcesByContext
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/context_key'
        - $ref: '#/components/parameters/context_value'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
        - $ref: '#/components/parameters/direction'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/{resource_type}/moderations/{moderation_kind}/{moderation_status}:
    get:
      summary: Get resources by moderation kind and status
      description: Retrieves resources matching specific moderation kind and status.
      tags:
        - assets
        - moderations
      operationId: listResourcesByModerationKindAndStatus
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/moderation_kind'
        - $ref: '#/components/parameters/moderation_status'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
        - $ref: '#/components/parameters/direction'
      responses:
        '200':
          description: List of resources retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/restore:
    post:
      summary: Restore assets by asset ID
      description: Restores one or more resources from backup using their asset IDs. Can optionally specify versions to restore.
      tags:
        - assets
      operationId: restoreResourcesByAssetIDs
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The asset IDs to restore and optional version parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/restore_request'
      responses:
        '200':
          description: Resources restored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restore_response'
              examples:
                restoreResponseFullRestoreExample:
                  $ref: '#/components/examples/RestoreResourcesFullRestoreExample'
                restoreResponsePartialRestoreExample:
                  $ref: '#/components/examples/RestoreResourcesPartialRestoreExample'
                restoreResponseFailedRestoreExample:
                  $ref: '#/components/examples/RestoreResourcesFailedRestoreExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              examples:
                invalid_asset_id:
                  summary: Invalid asset ID format
                  value:
                    error:
                      message: 'Invalid asset_id: abc123'
                missing_parameter:
                  summary: Missing required parameter
                  value:
                    error:
                      message: asset_ids parameter is required
                version_count_mismatch:
                  summary: Version count doesn't match asset_ids count
                  value:
                    error:
                      message: versions count must match ids count
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              examples:
                unauthorized:
                  summary: Invalid API credentials
                  value:
                    error:
                      message: Invalid signature
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              examples:
                insufficient_permissions:
                  summary: No permission to restore assets
                  value:
                    error:
                      message: Update operation not authorized for account
  /v1_1/{cloud_name}/resources/by_external_ids:
    get:
      summary: Get resources by external IDs
      description: Retrieves details for specific resources using their external IDs (or asset IDs).
      tags:
        - assets
      operationId: listResourcesByExternalIDs
      x-speakeasy-ignore: true
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - name: external_ids
          in: query
          required: true
          explode: false
          schema:
            type: array
            items:
              type: string
          description: List of external IDs for identifying the assets to retrieve. Either external_ids or asset_ids must be provided.
        - $ref: '#/components/parameters/resource_type_query'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/tags_query'
        - $ref: '#/components/parameters/context_query'
        - $ref: '#/components/parameters/metadata_query'
        - $ref: '#/components/parameters/moderations_query'
      responses:
        '200':
          description: Successfully retrieved resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_response'
              examples:
                listResourcesExample:
                  $ref: '#/components/examples/ListResourcesResponseExample'
        '400':
          description: Bad request - missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: One or more external IDs not found (partial success possible)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/{resource_type}/{type}:
    delete:
      summary: Delete resources by public ID
      description: Deletes assets uploaded to your product environment, identified by their public IDs.
      tags:
        - assets
      operationId: deleteResourcesByPublicId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/delivery_type_all'
      requestBody:
        description: The public IDs and options for the resources to delete.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteResourceByPublicIdsRequest'
      responses:
        '200':
          description: Resource successfully deleted
          content:
            application/json:
              schema:
                type: object
              examples:
                deleteResourceResponseExample:
                  $ref: '#/components/examples/DeleteResourcesResponseExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resources not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/{resource_type}/{type}/{public_id}:
    get:
      summary: Get resource by public ID
      description: Returns the details of a single resource specified by its public ID.
      tags:
        - assets
      operationId: getResourceByPublicId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/delivery_type_all'
        - $ref: '#/components/parameters/public_id'
        - $ref: '#/components/parameters/colors'
        - $ref: '#/components/parameters/media_metadata'
        - $ref: '#/components/parameters/faces'
        - $ref: '#/components/parameters/quality_analysis'
        - $ref: '#/components/parameters/accessibility_analysis'
        - $ref: '#/components/parameters/pages'
        - $ref: '#/components/parameters/phash'
        - $ref: '#/components/parameters/coordinates'
        - $ref: '#/components/parameters/versions'
        - $ref: '#/components/parameters/max_derived_results'
        - $ref: '#/components/parameters/derived_next_cursor'
      responses:
        '200':
          description: Resource details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/info'
              examples:
                getResourceResponseExample:
                  $ref: '#/components/examples/GetResourceResponseExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    post:
      summary: Update asset by public ID
      description: |
        Updates one or more attributes of a specified resource (asset) identified by its public ID. Note that you can also update many attributes of an existing asset using the explicit method, which is not rate limited.
      tags:
        - assets
      operationId: updateResourceByPublicId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/delivery_type_all'
        - $ref: '#/components/parameters/public_id'
      requestBody:
        description: The asset attributes to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceUpdateRequest'
      responses:
        '200':
          description: Asset successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/info'
              examples:
                updateResourceResponseExample:
                  $ref: '#/components/examples/UpdateResourceResponseExample'
        '400':
          description: Bad request - Invalid parameters or values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized - Invalid API key or secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/{asset_id}:
    get:
      x-speakeasy-mcp:
        name: get-asset-details
        scopes:
          - librarian
        title: Get Asset Details
        readOnlyHint: true
        idempotentHint: true
      summary: Get resource by asset ID
      description: Returns the details of a single resource specified by its asset ID.
      tags:
        - assets
      operationId: getResourceByAssetId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/colors'
        - $ref: '#/components/parameters/media_metadata'
        - $ref: '#/components/parameters/faces'
        - $ref: '#/components/parameters/quality_analysis'
        - $ref: '#/components/parameters/accessibility_analysis'
        - $ref: '#/components/parameters/pages'
        - $ref: '#/components/parameters/phash'
        - $ref: '#/components/parameters/coordinates'
        - $ref: '#/components/parameters/versions'
        - $ref: '#/components/parameters/max_derived_results'
        - $ref: '#/components/parameters/derived_next_cursor'
      responses:
        '200':
          description: Resource details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/info'
              examples:
                getResourceResponseExample:
                  $ref: '#/components/examples/GetResourceResponseExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    put:
      x-speakeasy-mcp:
        name: asset-update
        scopes:
          - librarian
        title: Asset Update
        idempotentHint: true
      summary: Updates an existing asset's metadata, tags, and other attributes using its asset ID
      description: |
        Updates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. Note that you can also update attributes of an existing asset using the explicit API endpoint.
      tags:
        - assets
      operationId: updateResourceByAssetId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_id'
      requestBody:
        description: The asset attributes to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceUpdateRequest'
      responses:
        '200':
          description: Resource successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/info'
              examples:
                updateResourceResponseExample:
                  $ref: '#/components/examples/UpdateResourceResponseExample'
        '400':
          description: Bad request - Invalid parameters or values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized - Invalid API key or secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/tags/{resource_type}:
    get:
      x-speakeasy-mcp:
        name: list-tags
        scopes:
          - librarian
        title: List Tags
        readOnlyHint: true
        idempotentHint: true
      summary: Retrieves a list of tags currently applied to assets in your Cloudinary account
      description: |
        Retrieves a comprehensive list of all tags that exist in your product environment for assets of the specified type.

        [Cloudinary Admin API documentation](https://cloudinary.com/documentation/admin_api)
      tags:
        - assets
        - tags
      operationId: listResourceTags
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/prefix_tags'
        - $ref: '#/components/parameters/next_cursor'
        - $ref: '#/components/parameters/max_results'
      responses:
        '200':
          description: List of tags retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tags_list_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/backup/{asset_id}:
    delete:
      summary: Delete backed up versions
      description: |
        Deletes specific backed up versions of an asset identified by asset ID.
        This operation is irreversible and deleted versions cannot be recovered.
      tags:
        - assets
        - backups
      operationId: deleteBackupVersions
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_id'
      requestBody:
        description: The asset IDs and version IDs to delete.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/delete_backup_versions_request'
      responses:
        '200':
          description: Backup versions successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_backup_versions_response'
        '207':
          description: Multi-status - some versions deleted successfully, others failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_backup_versions_partial_response'
        '400':
          description: Bad request - Invalid parameters or values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized - Invalid API key or secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/usage:
    get:
      x-speakeasy-mcp:
        name: get-usage-details
        scopes:
          - admin
        title: Get Usage Details
        readOnlyHint: true
        idempotentHint: true
      summary: Retrieves comprehensive usage metrics and account statistics
      description: A report on the status of product environment usage, including storage, credits, bandwidth, requests, number of resources, and add-on usage. No date parameter needed to get current usage statistics.
      tags:
        - usage
      operationId: getUsage
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - name: date
          in: query
          required: false
          description: The date for which to retrieve usage details (YYYY-MM-DD). If not specified, returns the current usage.
          schema:
            type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
      responses:
        '200':
          description: Usage details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usage_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/video/analytics/views:
    get:
      summary: Get video views
      description: |
        Retrieves analytics data for video views. Results can be filtered using expressions based on various criteria
        such as video public ID, view duration, viewer information, and more.
      tags:
        - video_analytics
      operationId: getVideoViews
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - name: expression
          in: query
          required: false
          schema:
            type: string
          description: 'A set of conditions used to limit the results to rows that match those conditions. For example: `?expression=video_public_id=skate`'
        - $ref: '#/components/parameters/max_results_query'
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - view_ended_at
              - video_duration
              - view_watch_time
              - -view_ended_at
              - -video_duration
              - -view_watch_time
            default: -view_ended_at
          description: Specifies the expression field by which to sort the results. Prepend values with a '-' to reverse the order.
        - $ref: '#/components/parameters/next_cursor_query'
      responses:
        '200':
          description: List of video views retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/video_views_response'
              example:
                request_id: 1d39ccc69109b1cefac697957bda7952
                next_cursor: 2a54714067686dc630b44e3b863163dc
                data:
                  - video_public_id: dog
                    video_duration: 100
                    video_transformation: w_100,h_100
                    video_extension: mp4
                    viewer_application_name: Chrome
                    viewer_location_country_code: US
                    viewer_os_identifier: Linux
                    view_watch_time: 313
                    view_ended_at: '2025-05-13T09:59:21.000Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/related_assets/{asset_id}:
    post:
      x-speakeasy-mcp:
        name: create-asset-relations
        scopes:
          - librarian
        title: Create Asset Relations
      operationId: createAssetRelationsByAssetId
      summary: Add related assets by asset ID
      description: Relates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.
      tags:
        - asset_relations
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_id'
      requestBody:
        description: The asset IDs to relate.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/relate_assets_by_asset_id_request'
      responses:
        '200':
          description: Successfully created all asset relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_response'
        '207':
          description: Partially successful - some relations were created, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    delete:
      x-speakeasy-mcp:
        name: delete-asset-relations
        scopes:
          - librarian
        title: Delete Asset Relations
        destructiveHint: true
        idempotentHint: true
      operationId: deleteAssetRelationsByAssetId
      summary: Delete asset relations by asset ID
      description: Unrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.
      tags:
        - asset_relations
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/asset_id'
      requestBody:
        description: The asset IDs to unrelate.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unrelate_assets_by_asset_id_request'
      responses:
        '200':
          description: Successfully deleted all asset relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_delete_response'
        '207':
          description: Partially successful - some relations were deleted, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_delete_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/related_assets/{resource_type}/{type}/{public_id}:
    post:
      operationId: createAssetRelationsByPublicId
      summary: Create asset relations by public ID
      description: Relates an asset to other assets by public IDs. This allows you to indicate that the asset is logically related to other assets in some way (e.g., similar content, or a peripheral asset like video/transcript, etc). This is a bidirectional process, meaning that the asset is also added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other.
      tags:
        - asset_relations
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/delivery_type'
        - $ref: '#/components/parameters/public_id'
      requestBody:
        description: The assets to relate by public ID.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/relate_assets_by_public_id_request'
      responses:
        '200':
          description: Successfully created all asset relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_response'
        '207':
          description: Partially successful - some relations were created, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    delete:
      operationId: deleteAssetRelationsByPublicId
      summary: Delete asset relations by public ID
      description: Unrelates the asset from other assets, specified by public IDs. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified.
      tags:
        - asset_relations
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/resource_type'
        - $ref: '#/components/parameters/delivery_type'
        - $ref: '#/components/parameters/public_id'
      requestBody:
        description: The assets to unrelate by public ID.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unrelate_assets_by_public_id_request'
      responses:
        '200':
          description: Successfully deleted all asset relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_delete_response'
        '207':
          description: Partially successful - some relations were deleted, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asset_relations_delete_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folders/{folder}:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/folder_path'
    get:
      summary: List sub-folders
      description: Returns a list of sub-folders under the specified folder path.
      tags:
        - folders
      operationId: showFolder
      responses:
        '200':
          description: List of sub-folders retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folders_list_response'
        '400':
          description: Bad request (e.g., invalid path format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    put:
      x-speakeasy-mcp:
        name: move-folder
        scopes:
          - librarian
        title: Move Folder
        idempotentHint: true
      summary: Renames or moves an entire folder (along with all assets it contains) to a new location
      description: Renames or moves an entire folder (along with all assets it contains) to a new location within your Cloudinary media library.
      tags:
        - folders
      operationId: updateFolder
      requestBody:
        description: The new folder path.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/move_folder_request'
      responses:
        '200':
          description: Folder renamed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/move_folder_response'
        '400':
          description: Bad request (e.g., invalid path format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    post:
      x-speakeasy-mcp:
        name: create-folder
        scopes:
          - librarian
        title: Create Folder
      tags:
        - folders
      summary: Creates a new empty folder in your Cloudinary media library
      description: Creates a new folder at the specified path
      operationId: createFolder
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - $ref: '#/components/parameters/folder_path'
      responses:
        '200':
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_folder_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '409':
          description: Folder already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    delete:
      x-speakeasy-mcp:
        name: delete-folder
        scopes:
          - librarian
        title: Delete Folder
        destructiveHint: true
        idempotentHint: true
      summary: Deletes an existing folder from your media library
      description: Deletes a folder and all assets within it.
      tags:
        - folders
      operationId: destroyFolder
      responses:
        '200':
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_folder_response'
        '400':
          description: Bad request (e.g., invalid path format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folders:
    get:
      summary: Get root folders
      description: |
        Retrieves an array of all root folders in your Cloudinary product environment. Limited to 2000 results.
      tags:
        - folders
      operationId: listRootFolders
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      responses:
        '200':
          description: The root folders were successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folders_list_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folders/search:
    get:
      x-speakeasy-mcp:
        name: search-folders
        scopes:
          - librarian
        title: Search Folders
        readOnlyHint: true
        idempotentHint: true
      summary: Searches for folders whose attributes match a given expression
      description: |
        Lists the folders that match the specified search expression. Limited to 2000 results. If no parameters are passed, returns the 50 most recently created folders in descending order of creation time.
      operationId: searchFolders
      tags:
        - folders
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - name: expression
          in: query
          required: false
          schema:
            type: string
          description: The (Lucene-like) string expression specifying the search query. If not passed, returns all folders (up to max_results).
        - name: sort_by
          in: query
          required: false
          description: Sort order for the results. Each item maps a field name to a direction.
          schema:
            $ref: '#/components/schemas/search_sort_by'
          example:
            - name: asc
        - $ref: '#/components/parameters/max_results_folders_query'
        - $ref: '#/components/parameters/next_cursor_query'
      responses:
        '200':
          description: A listing of all folders that match the search expression criteria according to the requested sorting order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folders_search_response'
              example:
                total_count: 14
                time: 1136
                next_cursor: 0a37f8c9f65e79c1cbe782d47987ed108d9f9e0dad4b0666adbf4eac9a634191996204a0ef84ce7b3e0e
                folders:
                  - name: 1_folder_param
                    path: my_parent/1_folder_param
                    created_at: '2024-12-16T11:31:00+00:00'
                    external_id: c7c08f8ecf093353d669d2ea3123967c7
                  - name: a_folder_param
                    path: my_parent/a_folder_param
                    created_at: '2024-12-16T11:08:32+00:00'
                    external_id: c7c08b736592482c1125ba5d689ab8779
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    post:
      summary: Searches for folders in your product environment
      description: |
        Lists the folders that match the specified search expression. Limited to 2000 results. If no parameters are passed, returns the 50 most recently created folders in descending order of creation time.
      operationId: searchFoldersPost
      tags:
        - folders
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The folder search query parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/folder_search_request'
            example:
              expression: name:folder AND path:my_parent AND created_at=>4w
              sort_by:
                - name: asc
              max_results: 10
      responses:
        '200':
          description: A listing of all folders that match the search expression criteria according to the requested sorting order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folders_search_response'
              example:
                total_count: 14
                time: 1136
                next_cursor: 0a37f8c9f65e79c1cbe782d47987ed108d9f9e0dad4b0666adbf4eac9a634191996204a0ef84ce7b3e0e
                folders:
                  - name: 1_folder_param
                    path: my_parent/1_folder_param
                    created_at: '2024-12-16T11:31:00+00:00'
                    external_id: c7c08f8ecf093353d669d2ea3123967c7
                  - name: a_folder_param
                    path: my_parent/a_folder_param
                    created_at: '2024-12-16T11:08:32+00:00'
                    external_id: c7c08b736592482c1125ba5d689ab8779
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folder_operations/invite/{folder_id}:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/folder_id'
    get:
      x-speakeasy-mcp:
        name: get-folder-roles
        disabled: true
        scopes:
          - admin
        title: Get Folder Roles
        readOnlyHint: true
        idempotentHint: true
      summary: Get folder roles
      description: |
        Lists the principals (users, groups, or API keys) and their role assignments on a specific folder, including roles inherited from ancestor folders. 
      tags:
        - folders
      operationId: getFolderRoles
      parameters:
        - $ref: '#/components/parameters/permitted_roles_query'
      responses:
        '200':
          description: Principals and their roles successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder_roles_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
    post:
      x-speakeasy-mcp:
        name: assign-folder-roles
        disabled: true
        scopes:
          - admin
        title: Assign Folder Roles
      summary: Assign folder roles
      description: |
        Assigns or removes folder roles for a principal (user, group, or API key).
        Supports all system folder roles (see [System roles reference](https://cloudinary.com/documentation/permissions_system_roles_policies#folder_roles)).
        Enterprise customers can also assign custom roles by ID.
        Note: Assigning roles to users or groups via this endpoint requires their user or group IDs, which are available through the Provisioning API (Enterprise only). Free customers can use this endpoint to assign roles only to API keys, but can assign folder roles to users and groups through the UI.
      tags:
        - folders
      operationId: assignFolderRoles
      requestBody:
        description: The folder role assignments.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/assign_folder_roles_request'
      responses:
        '200':
          description: Roles added or removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folder_operations/rename:
    put:
      x-speakeasy-mcp:
        name: rename-folder
        scopes:
          - librarian
        title: Rename Folder
        idempotentHint: true
        disabled: true
      summary: Rename or move a folder
      description: Renames or moves the folder at the specified path, along with all the assets it contains, to a new path.
      tags:
        - folders
      operationId: renameFolderOperation
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The source and destination folder paths.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/folder_rename_request'
      responses:
        '200':
          description: The folder was successfully renamed or moved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder_rename_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folders/by_id:
    put:
      x-speakeasy-mcp:
        name: get-folder-by-id
        scopes:
          - librarian
        title: Get Folder By ID
        idempotentHint: true
        disabled: true
      summary: Get a folder by its identifier
      description: Returns the details of the folder with the specified identifier, including its ancestors.
      tags:
        - folders
      operationId: getFolderById
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The identifier of the folder to retrieve.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/folder_by_id_request'
      responses:
        '200':
          description: The folder was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder_detail_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folders/by_path:
    put:
      x-speakeasy-mcp:
        name: get-folder-by-path
        scopes:
          - librarian
        title: Get Folder By Path
        idempotentHint: true
        disabled: true
      summary: Get a folder by its path
      description: Returns the details of the folder at the specified path, including its ancestors.
      tags:
        - folders
      operationId: getFolderByPath
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The path of the folder to retrieve.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/folder_by_path_request'
      responses:
        '200':
          description: The folder was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder_detail_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/folders/descendants:
    put:
      x-speakeasy-mcp:
        name: get-folder-descendants
        scopes:
          - librarian
        title: Get Folder Descendants
        idempotentHint: true
        disabled: true
      summary: Get the descendants of a folder
      description: Returns the descendant folders of the folder with the specified identifier, optionally filtered to a set of folder identifiers.
      tags:
        - folders
      operationId: getFolderDescendants
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The parent folder identifier and optional filter.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/folder_descendants_request'
      responses:
        '200':
          description: The descendant folders were successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder_descendants_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/derived_resources:
    delete:
      x-speakeasy-mcp:
        name: delete-derived-assets
        scopes:
          - librarian
        title: Delete Derived Assets
        destructiveHint: true
        idempotentHint: true
      summary: Delete derived resources
      description: Deletes derived resources by derived resource ID
      tags:
        - assets
      operationId: derivedDestroy
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The derived resource IDs to delete.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DerivedDestroyRequest'
      responses:
        '200':
          description: Derived resources successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DerivedDestroyResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/derived_resources/invalidate_by_urls:
    delete:
      x-speakeasy-mcp:
        name: invalidate-derived-by-urls
        scopes:
          - librarian
        title: Invalidate Derived Assets By URLs
        destructiveHint: true
        idempotentHint: true
        disabled: true
      summary: Invalidate derived assets by delivery URLs
      description: Deletes and invalidates the cached derived assets that back the specified delivery URLs.
      tags:
        - assets
      operationId: invalidateDerivedByUrls
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The delivery URLs whose derived assets should be invalidated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/invalidate_by_urls_request'
      responses:
        '200':
          description: The derived assets were successfully invalidated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invalidate_by_urls_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/get_resource:
    post:
      x-speakeasy-mcp:
        name: get-resource-by-body
        scopes:
          - librarian
        title: Get Resource By Body Params
        readOnlyHint: true
        idempotentHint: true
        disabled: true
      summary: Get the details of a single asset by body parameters
      description: Returns the details of a single asset identified by its public ID, delivery type, and resource type passed in the request body.
      tags:
        - assets
      operationId: getResourceByBody
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The identifying attributes of the asset to retrieve.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resource_get_by_body_request'
      responses:
        '200':
          description: The asset details were successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource_internal_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/update:
    post:
      x-speakeasy-mcp:
        name: update-resource-by-body
        scopes:
          - librarian
        title: Update Resource By Body Params
        disabled: true
      summary: Update the details of a single asset by body parameters
      description: Updates the details of an existing asset (such as tags, contextual metadata, structured metadata, and moderation status) identified by its public ID, delivery type, and resource type passed in the request body.
      tags:
        - assets
      operationId: updateResourceByBody
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The asset identifiers plus the attributes to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resource_update_by_body_request'
      responses:
        '200':
          description: The asset was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource_internal_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '404':
          description: Asset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/by_container_id/{container_id}:
    get:
      x-speakeasy-mcp:
        name: list-resources-by-container-id
        scopes:
          - librarian
        title: List Resources By Container ID
        readOnlyHint: true
        idempotentHint: true
        disabled: true
      summary: List the assets in a folder by container ID
      description: Returns the assets contained in the folder identified by the given container ID.
      tags:
        - assets
      operationId: listResourcesByContainerId
      parameters:
        - $ref: '#/components/parameters/cloud_name'
        - name: container_id
          in: path
          required: true
          schema:
            type: string
          description: The immutable identifier of the folder container whose assets are listed.
          example: cd7e9d690a014c68ae8b58f08e090cb03a
        - $ref: '#/components/parameters/max_results_query'
        - $ref: '#/components/parameters/next_cursor_query'
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
          description: The field by which the assets are sorted. Default is "uploaded_at".
        - name: fields
          in: query
          required: false
          schema:
            type: string
          description: A comma-separated list of asset fields to include in each returned asset.
      responses:
        '200':
          description: The assets in the folder were successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resources_by_container_id_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '403':
          description: Folder decoupling is not enabled for the product environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/eval:
    post:
      x-speakeasy-mcp:
        name: eval-upload-params
        scopes:
          - librarian
        title: Evaluate Upload Parameters
        disabled: true
      summary: Evaluate a dynamic upload-parameter expression
      description: Evaluates a dynamic eval expression against the supplied upload parameters and returns the resulting upload parameters.
      tags:
        - upload
      operationId: evalUploadParams
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The eval expression and the upload parameters to evaluate it against.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/eval_request'
      responses:
        '200':
          description: The evaluated upload parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eval_response'
        '400':
          description: Bad request (e.g. an invalid eval expression).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/search:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    post:
      operationId: searchAssets
      summary: Provides a powerful query interface to filter and retrieve assets and their details
      description: |
        Returns a list of resources matching the specified search criteria.

        Uses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions.

        Examples: `tags:shirt AND uploaded_at>1d`, `resource_type:image AND bytes>1000000`, `folder:products OR context.category:electronics`. See the [search expressions guide](https://cloudinary.com/documentation/search_expressions.md) for the full syntax and field reference.
      tags:
        - search
      x-speakeasy-mcp:
        name: search-assets
        scopes:
          - librarian
        title: Search Assets
        readOnlyHint: true
        idempotentHint: true
      requestBody:
        description: The search query parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/search_parameters'
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/resources/visual_search:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    post:
      operationId: visualSearchAssets
      summary: Finds images in your asset library based on visual similarity or content
      description: |
        Returns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways:
        - Provide a URL of an image
        - Specify the asset ID of an existing image
        - Provide a textual description
      tags:
        - search
      x-speakeasy-mcp:
        name: visual-search-assets
        scopes:
          - librarian
        title: Visual Search Assets
        readOnlyHint: true
        idempotentHint: true
      requestBody:
        description: The visual search parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/visual_search_parameters'
      responses:
        '200':
          description: Successful visual search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v1_1/{cloud_name}/operations/initial_backup:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    post:
      x-speakeasy-mcp:
        name: create-initial-backup
        scopes:
          - librarian
        title: Create Initial Backup
        disabled: true
      operationId: createInitialBackup
      summary: Create initial backup
      description: |
        Initiates an initial backup of existing assets for the active product environment.
        Backup for new uploads must be enabled on the product environment, and the requester must be permitted to
        initiate a backup.
      tags:
        - initial_backup
      requestBody:
        description: The initial backup configuration.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/initial_backup_create_request'
      responses:
        '200':
          description: Initial backup queued successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/initial_backup_create_response'
              example:
                ok: true
        '400':
          description: Invalid request, backup not enabled, or self-service threshold exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Backup for new uploads isn't enabled. Turn it on before starting an initial backup of existing assets.
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid credentials
        '403':
          description: Not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Not allowed
    get:
      x-speakeasy-mcp:
        name: list-initial-backups
        scopes:
          - librarian
        title: List Initial Backups
        readOnlyHint: true
        idempotentHint: true
        disabled: true
      operationId: listInitialBackups
      summary: List initial backups
      description: Lists initial backup operations for the active product environment, ordered from most recent to oldest.
      tags:
        - initial_backup
      parameters:
        - $ref: '#/components/parameters/max_results_query'
        - $ref: '#/components/parameters/next_cursor_query'
      responses:
        '200':
          description: Initial backup operations retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/initial_backup_list_response'
              example:
                initial_backups:
                  - id: abc123def456
                    status: completed
                    created_at: '2024-05-07T10:00:00Z'
                next_cursor: eyJpZCI6MTIzfQ==
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid credentials
  /v1_1/{cloud_name}/operations/initial_backup/{id}:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - $ref: '#/components/parameters/initial_backup_id'
    get:
      x-speakeasy-mcp:
        name: get-initial-backup
        scopes:
          - librarian
        title: Get Initial Backup
        readOnlyHint: true
        idempotentHint: true
        disabled: true
      operationId: getInitialBackup
      summary: Get initial backup
      description: Retrieves the progress and status of a single initial backup operation by its ID.
      tags:
        - initial_backup
      responses:
        '200':
          description: Initial backup retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/initial_backup_progress_response'
              example:
                status: completed
                start_time: '2024-05-07T10:00:00Z'
                completion_time: '2024-05-07T11:00:00Z'
                processed_assets_count: 42
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid credentials
        '403':
          description: Not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Not allowed
        '404':
          description: Initial backup operation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Operation does not exist
  /v1_1/{cloud_name}/people:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
    get:
      x-speakeasy-mcp:
        disabled: true
        name: list-people
        scopes:
          - admin
        title: List People
        readOnlyHint: true
        idempotentHint: true
      operationId: listPeople
      summary: List recognized people
      description: |
        Returns a list of all recognized people in your product environment.
        People Search must be enabled for this product environment.
      tags:
        - people
      parameters:
        - name: max_results
          in: query
          required: false
          description: 'The maximum number of people to return. Default: 50.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          example: 20
        - $ref: '#/components/parameters/next_cursor_query'
        - name: name_status
          in: query
          required: false
          description: 'Filter by whether the person has been named. Default: all.'
          schema:
            type: string
            enum:
              - all
              - named
              - unnamed
            default: all
          example: named
        - name: name_prefix
          in: query
          required: false
          description: Filter people whose names start with the given prefix (case insensitive).
          schema:
            type: string
          example: Alice
        - name: status
          in: query
          required: false
          description: Filter by person status.
          schema:
            $ref: '#/components/schemas/person_status'
          example: active
        - name: sort_by
          in: query
          required: false
          description: |
            The field to sort results by. Default: name (ascending).
          schema:
            type: string
            enum:
              - name
              - created_at
              - updated_at
            default: name
          example: created_at
        - $ref: '#/components/parameters/direction'
      responses:
        '200':
          description: People retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/people_list_response'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid sort_by value
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid credentials
        '403':
          description: Feature not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: People Search is not enabled for this customer
  /v1_1/{cloud_name}/people/{person_id}:
    parameters:
      - $ref: '#/components/parameters/cloud_name'
      - name: person_id
        in: path
        required: true
        description: The unique identifier of the person.
        schema:
          type: string
        example: f10f893da5a1586dca6764b22514aa0d25e6b867baffc4fb43a2318a25d8e5b2
    get:
      x-speakeasy-mcp:
        disabled: true
        name: get-person
        scopes:
          - admin
        title: Get Person
        readOnlyHint: true
        idempotentHint: true
      operationId: getPerson
      summary: Get person details
      description: |
        Returns details of a specific recognized person.
        People Search must be enabled for this product environment.
      tags:
        - people
      responses:
        '200':
          description: Person retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/person_response'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Missing person_id
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid credentials
        '403':
          description: Feature not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: People Search is not enabled for this customer
        '404':
          description: Person not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Can't find Person with id nonexistent
    put:
      x-speakeasy-mcp:
        disabled: true
        name: update-person
        scopes:
          - admin
        title: Update Person
        idempotentHint: true
      operationId: updatePerson
      summary: Update a person
      description: |
        Updates a recognized person's name, status, or thumbnail image.
        At least one of name, status, or thumbnail_asset_id must be provided.
        People Search must be enabled for this product environment.
      tags:
        - people
      requestBody:
        description: The updated person attributes.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_person_request'
      responses:
        '200':
          description: Person updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_person_response'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              examples:
                name_too_long:
                  value:
                    error:
                      message: Name is too long, maximum is 255
                invalid_status:
                  value:
                    error:
                      message: Invalid status value, must be one of active, hidden
                missing_params:
                  value:
                    error:
                      message: Missing required parameter
                no_face:
                  value:
                    error:
                      message: No faces detected in the provided Asset
                wrong_person:
                  value:
                    error:
                      message: The provided Asset does not contain a face for this Person
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Invalid credentials
        '403':
          description: Feature not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: People Search is not enabled for this customer
        '404':
          description: Person not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
              example:
                error:
                  message: Can't find Person with id nonexistent
  /v1_1/{cloud_name}/people/inspect:
    post:
      x-speakeasy-mcp:
        name: inspect-people-permissions
        scopes:
          - admin
        title: Inspect People Permissions
        readOnlyHint: true
        idempotentHint: true
        disabled: true
      summary: Inspect the caller's permitted actions on people
      description: Returns, for each requested person and action, whether the authenticated caller is permitted to perform that action.
      tags:
        - people
      operationId: inspectPeoplePermissions
      parameters:
        - $ref: '#/components/parameters/cloud_name'
      requestBody:
        description: The people and actions to inspect.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/people_inspect_request'
      responses:
        '200':
          description: The permission inspection results were successfully computed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/people_inspect_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_error'
  /v2/generate/{cloud_name}/text_to_image:
    parameters:
      - $ref: "#/components/parameters/cloudName"
    post:
      x-speakeasy-mcp:
        name: generate-image
        scopes:
          - builder
        title: Generate an Image
      tags:
        - Generation
      summary: Generate an image
      description: >
        Generate an image from a text prompt using AI models.


        The model is selected via the optional `model` object:

        1. If `model.id` is provided, use that exact model.

        2. Else if `model.family` (+ optional `model.tier`) is provided, resolve
        via the model registry; a missing tier defaults to `standard`.

        3. Else if `model.mode` is `auto`, the service picks the model for the
        request (optionally steered by `model.preference`).

        4. Otherwise, use the global default (nano-banana / premium, i.e.
        `nano-banana-2`).
      operationId: generate_image
      requestBody:
        required: true
        description: A JSON object containing the generation request parameters.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateImageRequest"
            examples:
              BasicExample:
                $ref: "#/components/examples/GenerateImageBasicExample"
              DeclarativeSizeExample:
                $ref: "#/components/examples/GenerateImageDeclarativeSizeExample"
              DimensionsSizeExample:
                $ref: "#/components/examples/GenerateImageDimensionsSizeExample"
              AsyncExample:
                $ref: "#/components/examples/GenerateImageAsyncExample"
              AutoModelExample:
                $ref: "#/components/examples/GenerateImageAutoModelExample"
      responses:
        "200":
          description: Image generated successfully (synchronous).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateImageResult"
              examples:
                Success:
                  $ref: "#/components/examples/GenerateImageSuccessExample"
                SuccessManagedAsset:
                  $ref: "#/components/examples/GenerateImageManagedAssetSuccessExample"
        "202":
          $ref: "#/components/responses/GenerationAcceptedResponse"
        "400":
          $ref: "#/components/responses/BadRequestResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntityResponse"
        "429":
          $ref: "#/components/responses/RateLimitedResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        "502":
          $ref: "#/components/responses/ModelUnavailableResponse"
  /v2/generate/{cloud_name}/image_to_image:
    parameters:
      - $ref: "#/components/parameters/cloudName"
    post:
      x-speakeasy-mcp:
        name: generate-image-from-images
        scopes:
          - builder
        title: Generate an Image from Reference Images
      tags:
        - Generation
      summary: Generate an image from reference images
      description: |
        Generate an image guided by one or more **reference images** — restyle,
        on-brand variants, character consistency, virtual try-on, edit/extend —
        steered by `prompt`.

        Only edit-capable models are selectable here. The model is selected via
        the optional `model` object, exactly like `text_to_image`, but IDs are
        restricted to edit models:
        1. If `model.id` is provided, use that exact edit model.
        2. Else if `model.family` (+ optional `model.tier`) is provided, resolve
           to that family's edit model (e.g. `nano-banana` / `premium` →
           `nano-banana-2-edit`).
        3. Else if `model.mode` is `auto`, the service picks an edit model for
           the request (optionally steered by `model.preference`).
        4. Otherwise, use the default edit model (`nano-banana-2-edit`).

        Each reference image is either a stored managed asset (by `asset_id`,
        read-permission checked) or an external HTTPS `url`.
      operationId: generate_image_from_images
      requestBody:
        required: true
        description: A JSON object containing the image-to-image generation request parameters.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImageToImageRequest"
            examples:
              BasicExample:
                $ref: "#/components/examples/ImageToImageBasicExample"
              FamilyModelExample:
                $ref: "#/components/examples/ImageToImageFamilyModelExample"
              ExplicitModelExample:
                $ref: "#/components/examples/ImageToImageExplicitModelExample"
              AutoModelExample:
                $ref: "#/components/examples/ImageToImageAutoModelExample"
      responses:
        "200":
          description: Image generated successfully (synchronous).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateImageResult"
        "202":
          $ref: "#/components/responses/GenerationAcceptedResponse"
        "400":
          $ref: "#/components/responses/BadRequestResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "403":
          $ref: "#/components/responses/ForbiddenResponse"
        "404":
          $ref: "#/components/responses/NotFoundResponse"
        "422":
          $ref: "#/components/responses/UnprocessableEntityResponse"
        "429":
          $ref: "#/components/responses/RateLimitedResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        "502":
          $ref: "#/components/responses/ModelUnavailableResponse"
  /v2/generate/{cloud_name}/tasks/{task_id}:
    parameters:
      - $ref: "#/components/parameters/cloudName"
      - in: path
        name: task_id
        description: The ID of the generation task.
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{1,256}$
        examples:
          default:
            value: 053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
    get:
      x-speakeasy-mcp:
        name: get-generation-task
        scopes:
          - builder
        title: Get a Generation Task
        readOnlyHint: true
        idempotentHint: true
      tags:
        - Tasks
      summary: Get a generation task
      description: Get the status of a generation task.
      operationId: get_generation_task_status
      responses:
        "200":
          description: Generation task status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskResponse"
              examples:
                Completed:
                  $ref: "#/components/examples/GenerateTaskCompletedExample"
        "400":
          $ref: "#/components/responses/BadRequestResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedResponse"
        "404":
          $ref: "#/components/responses/NotFoundResponse"
        "429":
          $ref: "#/components/responses/RateLimitedResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Cloudinary API Key and API Secret.
    oauth2:
      type: oauth2
      description: OAuth2 Authorization Code flow for user authentication
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.cloudinary.com/oauth2/auth
          tokenUrl: https://oauth.cloudinary.com/oauth2/token
          scopes:
            asset_management: Allows managing assets, including reading, updating, and deleting.
            upload: Allows uploading new assets.
            media_generation: Generate media
  parameters:
    cloud_name:
      name: cloud_name
      in: path
      required: true
      schema:
        type: string
      description: The cloud name of your product environment.
      example: my_cloud
    upload_resource_type:
      name: resource_type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/upload_resource_type'
      description: The type of resource (image, video, raw, or auto).
    resource_type:
      name: resource_type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/resource_type'
      description: The type of resource (image, video, or raw).
    public_id_query:
      name: public_id
      in: query
      required: true
      schema:
        type: string
      description: The public ID of the asset.
    delivery_type_query:
      name: type
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/managed_delivery_type'
      description: The delivery type of the asset. Default is "upload".
    api_key_query:
      name: api_key
      in: query
      required: false
      schema:
        type: string
      example: '472851639284736'
      description: The API key to use for the request. This is automatically computed by the Cloudinary's SDKs.
    signature_query:
      name: signature
      in: query
      required: false
      schema:
        type: string
      example: c08ed49d293e966cbe613a13d8e9476fdb76817bd668feb5b17001b168579fbc
      description: |
        (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters.
    timestamp_query:
      name: timestamp
      in: query
      required: false
      schema:
        type: integer
        format: int64
      example: 1623087658
      description: The timestamp to use for the request in unix time. This is automatically computed by the Cloudinary's SDKs.
    archive_resource_type:
      name: resource_type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/archive_resource_type'
      description: The type of resource for archive generation (image, video, or raw).
    asset_id_query:
      name: asset_id
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/asset_id'
      description: The asset ID of the resource. Must be a 32-character hexadecimal string.
      example: f4e6579cf84dd9cf5683b21f5b30c7d9
    delivery_type_all_query:
      name: type
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/delivery_type_all'
      description: The delivery type to filter by. When omitted, returns assets of all delivery types.
    prefix:
      name: prefix
      in: query
      required: false
      schema:
        type: string
      description: A public_id prefix. When specified, all assets with that prefix are returned.
    public_ids_query:
      name: public_ids
      in: query
      required: false
      explode: false
      schema:
        type: array
        items:
          type: string
        maxItems: 100
      description: An array of public IDs to return.
      example:
        - sample
        - product_image
        - banner_2023
    tags_query:
      name: tags
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to include the list of tag names assigned to each asset. Default is false.
    next_cursor:
      name: next_cursor
      in: query
      required: false
      schema:
        type: string
      description: Cursor for pagination.
    max_results:
      name: max_results
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
      description: Maximum number of results to return (1-500).
    direction:
      name: direction
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/direction_enum'
      description: The sort direction for the results. Default is "desc".
    start_at:
      name: start_at
      in: query
      required: false
      schema:
        type: string
        format: date-time
      description: An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.
    fields:
      name: fields
      in: query
      required: false
      explode: false
      schema:
        anyOf:
          - type: string
            description: A comma-separated list of field names.
          - type: array
            items:
              $ref: '#/components/schemas/resource_fields_enum'
      description: Additional fields to include in the response. The fields public_id and asset_id are always included.
    asset_folder_query:
      name: asset_folder
      in: query
      required: true
      schema:
        type: string
      description: The full path of the asset folder.
    resource_type_query:
      name: resource_type
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/resource_type'
      description: Resource type filter.
    asset_ids_query:
      name: asset_ids
      in: query
      required: true
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/asset_id'
        maxItems: 100
      description: List of asset IDs to retrieve (max 100).
    context_key:
      name: key
      in: query
      required: true
      schema:
        type: string
      description: Context key to filter by.
    context_value:
      name: value
      in: query
      required: false
      schema:
        type: string
      description: Context value to filter by.
    moderation_kind:
      name: moderation_kind
      in: path
      required: true
      schema:
        type: string
        enum:
          - manual
          - webpurify
          - aws_rek
          - aws_rek_video
          - perception_point
          - google_video_moderation
          - duplicate
      description: The type of moderation to filter by.
    moderation_status:
      name: moderation_status
      in: path
      required: true
      schema:
        type: string
        enum:
          - approved
          - rejected
          - pending
          - queued
          - aborted
      description: The moderation status to filter by.
    context_query:
      name: context
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to include key-value pairs of contextual metadata associated with each asset. Default is false.
    metadata_query:
      name: metadata
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to include the structured metadata fields and values assigned to each asset. Default is false.
    moderations_query:
      name: moderations
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: Whether to include image moderation status of each asset. Default is false.
    delivery_type_all:
      name: type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/delivery_type_all'
      description: The delivery type of the asset.
    public_id:
      name: public_id
      in: path
      required: true
      schema:
        type: string
      example: sample
      description: The public ID of the asset.
    colors:
      name: colors
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to include color information (predominant colors and histogram of 32 leading colors). Default: false.'
    media_metadata:
      name: media_metadata
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to include IPTC, XMP, and detailed Exif metadata in the response. Default: false.'
    faces:
      name: faces
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to include a list of coordinates of detected faces. Default: false.'
    quality_analysis:
      name: quality_analysis
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to return quality analysis scores for the image. Default: false.'
    accessibility_analysis:
      name: accessibility_analysis
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to return accessibility analysis scores for the image. Default: false.'
    pages:
      name: pages
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to report the number of pages in multi-page documents (e.g., PDF). Default: false.'
    phash:
      name: phash
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to include the perceptual hash (pHash) of the uploaded photo for image similarity detection. Default: false.'
    coordinates:
      name: coordinates
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to include previously specified custom cropping coordinates and faces coordinates. Default: false.'
    versions:
      name: versions
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: 'Whether to include details of all the backed up versions of the asset. Default: false.'
    max_derived_results:
      name: max_results
      in: query
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
      required: false
      description: 'Maximum number of derived assets to return. Default: 10.'
    derived_next_cursor:
      name: derived_next_cursor
      in: query
      schema:
        type: string
      required: false
      description: The cursor for the next page of derived assets when there are more derived images than max_results.
    asset_id:
      name: asset_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/asset_id'
      description: The asset ID of the resource. Must be a 32-character hexadecimal string.
      example: f4e6579cf84dd9cf5683b21f5b30c7d9
    prefix_tags:
      name: prefix
      in: query
      required: false
      schema:
        type: string
      description: Limit the returned tags to those that start with the specified prefix.
    max_results_query:
      name: max_results
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 10
      description: The maximum number of results to return. Default is 10.
    next_cursor_query:
      name: next_cursor
      in: query
      required: false
      schema:
        type: string
      description: The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results.
    delivery_type:
      name: type
      in: path
      required: true
      schema:
        allOf:
          - $ref: '#/components/schemas/managed_delivery_type'
          - default: upload
      description: The delivery type of the asset.
    folder_path:
      name: folder
      in: path
      required: true
      schema:
        type: string
        pattern: ^(?!.*//)[^/].+(?<!/)$
      description: The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.
      example: product/test
    max_results_folders_query:
      name: max_results
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
      description: Maximum number of folders to return (max 500, default 50).
    folder_id:
      name: folder_id
      in: path
      required: true
      schema:
        type: string
      description: The immutable identifier of the folder, returned by the Get root folders and Get subfolders endpoints.
      example: cd7e9d690a014c68ae8b58f08e090cb03a
    permitted_roles_query:
      name: permitted_roles
      in: query
      required: false
      description: |
        Whether to include in the response the roles the authenticated user can assign on this folder, based on their permission level. Default: `false`.
      schema:
        type: boolean
    initial_backup_id:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the initial backup operation.
      example: abc123def456
    cloudName:
      in: path
      name: cloud_name
      description: The cloud name of your Cloudinary product environment.
      schema:
        type: string
      required: true
      examples:
        default:
          value: your-cloud-name
  schemas:
    upload_resource_type:
      type: string
      enum:
        - image
        - video
        - raw
        - auto
      description: |
        The type of resource to upload:
        - "image" for uploading strictly images
        - "video" for uploading strictly videos
        - "raw" for uploading non-media files
        - "auto" for allowing Cloudinary to automatically detect the type of the uploaded file
      default: auto
    signature_parameters:
      type: object
      properties:
        api_key:
          type: string
          description: The API key to use for the request. This is automatically computed by the Cloudinary's SDKs.
          example: '472851639284736'
        timestamp:
          type: integer
          format: int64
          description: The timestamp to use for the request in unix time. This is automatically computed by the Cloudinary's SDKs.
          example: 1623087658
        signature:
          type: string
          description: |
            (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters.
          example: c08ed49d293e966cbe613a13d8e9476fdb76817bd668feb5b17001b168579fbc
      example:
        api_key: '472851639284736'
        signature: c08ed49d293e966cbe613a13d8e9476fdb76817bd668feb5b17001b168579fbc
        timestamp: 1623087658
    access_control_item:
      type: object
      description: Access control rule that defines when and how the asset can be accessed.
      required:
        - access_type
      properties:
        access_type:
          type: string
          enum:
            - token
            - anonymous
          description: The type of access control to apply to the asset.
        key:
          type: string
          pattern: ^[a-zA-Z0-9]+$
          description: The authentication key identifier for token-based access. Default key is used if not specified or if set to 'default'.
          example: prod2024
        start:
          oneOf:
            - type: string
            - type: integer
          description: The start date and time when anonymous access becomes available. Accepts ISO 8601 string or Unix timestamp.
          example: '2024-03-15T09:00:00Z'
        end:
          oneOf:
            - type: string
            - type: integer
          description: The end date and time when anonymous access expires. Accepts ISO 8601 string or Unix timestamp.
          example: '2024-06-30T23:59:59Z'
    access_control:
      type: array
      description: |
        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.
      items:
        $ref: '#/components/schemas/access_control_item'
      example:
        - access_type: token
          key: prod2024
        - access_type: anonymous
          start: '2024-03-15T09:00:00Z'
          end: '2024-06-30T23:59:59Z'
    structured_metadata_value:
      type: object
      description: A map of custom metadata fields (by external_id) and the values to assign to each of them.
      additionalProperties:
        oneOf:
          - type: string
          - type: integer
          - type: array
            items:
              type: string
      example:
        in_stock_id: 50
        color_id:
          - green
          - red
        caption_id: Summer collection
        shot_date_id: '2024-06-15'
    structured_metadata_param:
      description: |
        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.
      oneOf:
        - type: string
          description: A pipe-separated list of custom metadata fields (by external_id) and the values to assign to each of them.
          example: in_stock_id=50|color_id=["green","red"]
        - $ref: '#/components/schemas/structured_metadata_value'
    coordinate_pair:
      type: array
      description: A single [x, y] coordinate pair.
      minItems: 2
      maxItems: 2
      items:
        type: integer
    region_coordinates:
      type: array
      description: Coordinate pairs defining the region boundary.
      minItems: 2
      items:
        $ref: '#/components/schemas/coordinate_pair'
    region_mapping:
      type: object
      description: |
        A map of named region coordinate groups for cropping with region gravity.
        Each key is a region name (letters, numbers, or hyphens only).
        Each value is an array of at least two [x, y] integer coordinate pairs
        defining the region boundary.
      additionalProperties:
        $ref: '#/components/schemas/region_coordinates'
      example:
        face:
          -   - 100
              - 200
          -   - 300
              - 400
        body:
          -   - 50
              - 60
          -   - 70
              - 80
          -   - 90
              - 100
    responsive_breakpoint:
      type: object
      properties:
        create_derived:
          type: boolean
          description: Whether to generate and store the derived images. Default is true.
        max_width:
          type: integer
          description: The maximum width for responsive breakpoint images.
        min_width:
          type: integer
          description: The minimum width for responsive breakpoint images.
        bytes_step:
          type: integer
          description: The minimum byte size difference between consecutive breakpoint images.
        max_images:
          type: integer
          description: The maximum number of breakpoint images to generate.
        transformation:
          type: string
          description: A transformation string to apply before generating breakpoints.
    upload_base_parameters:
      type: object
      description: Upload configuration parameters such as access control, backup, moderation, and notification settings.
      properties:
        accessibility_analysis:
          type: boolean
          description: Whether to return accessibility analysis values for the image.
        asset_folder:
          type: string
          description: The asset folder to assign to the asset.
        async:
          type: boolean
          description: |
            When set to true, returns the uploaded asset's public_id immediately in the response, before the upload is completed (asynchronously). Default: false.
        auto_chaptering:
          type: boolean
          description: 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.
        auto_tagging:
          type: number
          description: |
            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:
            - Cloudinary AI Content Analysis
            - Amazon Rekognition Celebrity Detection
            Use together with the categorization parameter for:
            - Google Automatic Video Tagging
            - Google Auto Tagging
            - Imagga Auto Tagging
            - Amazon Rekognition Auto Tagging
          example: 0.5
          minimum: 0
          maximum: 1
        auto_transcription:
          oneOf:
            - type: boolean
              description: Whether to trigger automatic generation of video transcription. Transcription will be generated and saved as a .vtt file with -transcription appended to the public ID of the video. Relevant for videos only.
              example: true
            - type: object
              description: Configuration object for automatic video transcription with translation options.
              properties:
                translate:
                  type: array
                  items:
                    type: string
                  description: Array of target language codes for transcription translation.
                  example:
                    - pl-PL
                    - he-IL
              example:
                translate:
                  - pl-PL
                  - he-IL
        access_control:
          $ref: '#/components/schemas/access_control'
        access_mode:
          type: string
          deprecated: true
          x-speakeasy-deprecation-message: The access_mode parameter is no longer supported. To restrict access to assets, you can use the access_control parameter.
          x-speakeasy-deprecation-replacement: access_control
          enum:
            - public
            - authenticated
          description: |
            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.
        backup:
          type: boolean
          description: Whether to backup the uploaded asset. When set to true, backs up uploaded assets to a secondary storage bucket.
        background_removal:
          type: string
          description: |
            Automatically remove the background of an image using an add-on.
            - Set to cloudinary_ai to use the deep-learning based Cloudinary AI Background Removal add-on.
              Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).
            - 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.
            Relevant for images only.
          example: cloudinary_ai
        callback:
          deprecated: true
          x-speakeasy-deprecation-message: The callback parameter is deprecated. Not relevant for modern browsers. Starting July 2025 new customers will not be able to use this parameter.
          type: string
          description: |
            A URL to redirect to after the upload/explicit is completed instead of returning the upload response.
            Signed upload result parameters are added to the callback URL. This parameter is ignored for XHR (Ajax XMLHttpRequest) or JavaScript Fetch API upload requests.
            Note: This parameter is relevant for direct uploads from a form in the browser. It is automatically set if you perform direct upload from the browser using Cloudinary's SDKs and the jQuery plugin.
        categorization:
          type: string
          description: |
            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).
          example: google_tagging
        cinemagraph_analysis:
          type: boolean
          description: 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.
        colors:
          type: boolean
          description: '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.'
          default: false
        detection:
          type: string
          description: |
            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.
          example: coco_v2
        discard_original_filename:
          type: boolean
          description: Whether to discard the name of the original uploaded file. Relevant when delivering assets as attachments (setting the flag disposition:attachment in delivery URLs).
        display_name:
          type: string
          description: A display name for the asset.
        eager_async:
          type: boolean
          description: Whether to generate the eager transformations asynchronously in the background after the upload request is completed rather than before the upload is completed.
        eager_notification_url:
          type: string
          format: uri
          description: A URL to notify when eager transformations are completed.
        eval:
          type: string
          description: 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.
        faces:
          type: boolean
          description: Whether to detect faces in the asset.
        filename_override:
          type: string
          description: Overrides the originally uploaded asset's file name in downloads that use flags like fl_attachment or fl_force_original.
        folder:
          type: string
          deprecated: true
          x-speakeasy-deprecation-message: |
            If Dynamic folders mode is enabled on your product environment, this parameter is deprecated, and it's recommended to use the asset_folder parameter to control where the asset will be placed. If you also want your public_id to match the initial asset folder path, include the use_asset_folder_as_public_id_prefixparameter.
          description: 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.
        format:
          type: string
          description: An optional format to convert the uploaded asset to before saving in the cloud.
          example: jpg
        invalidate:
          type: boolean
          description: |
            Whether to invalidate CDN cache copies of a previously uploaded asset that shares the same public ID. Default: false.
        media_metadata:
          type: boolean
          description: |
            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.
        metadata:
          $ref: '#/components/schemas/structured_metadata_param'
        clear_invalid:
          type: boolean
          description: '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.'
          default: false
        moderation:
          type: string
          description: |
            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.
          example: aws_rek|duplicate:0|perception_point|manual
        notification_url:
          type: string
          format: uri
          description: A URL to notify when the asset is ready.
        ocr:
          type: string
          description: |
            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).
          example: adv_ocr
        on_success:
          type: string
          description: 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.
        overwrite:
          type: boolean
          description: |
            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).
        phash:
          type: boolean
          description: |
            Whether to return the perceptual hash (pHash) on the uploaded image for image similarity detection.
        proxy:
          type: string
          description: A proxy to use for fetching remote URLs. The format should be http://hostname:port.
        public_id:
          type: string
          description: The identifier that is used for accessing the uploaded asset. If not specified, a unique ID is generated automatically.
        public_id_prefix:
          type: string
          description: 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.
        quality_analysis:
          type: boolean
          description: 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.
        raw_convert:
          type: string
          pattern: ^(aspose|azure_video_indexer(:\D+)*|google_speech(:(vt|sr)t)*(:[a-zA-Z-]+)?|extract_text)$
          description: |
            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)
          example: google_speech:vtt:en-US
        regions:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/region_mapping'
          description: |
            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.
          example: '{"face": [[100, 200], [300, 400]], "body": [[50, 60], [70, 80], [90, 100]]}'
        responsive_breakpoints:
          description: Settings to automatically generate breakpoints for responsive images.
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/responsive_breakpoint'
            - $ref: '#/components/schemas/responsive_breakpoint'
        return_delete_token:
          type: boolean
          description: 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.
        upload_preset:
          type: string
          description: 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.
        use_asset_folder_as_public_id_prefix:
          type: boolean
          description: 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.
        use_filename:
          type: boolean
          description: |
            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.
        use_filename_as_display_name:
          type: boolean
          description: 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.
        unique_display_name:
          type: boolean
          description: Whether the display name should be unique.
        unique_filename:
          type: boolean
          description: |
            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).
        visual_search:
          type: boolean
          description: Whether to index the image for use with visual searches. Relevant for images only.
    tags_param:
      anyOf:
        - type: string
          description: A comma-separated list of tag names.
        - type: array
          items:
            type: string
          description: An array of tag names.
      description: A comma-separated list of tag names, or an array of tag names.
      example: animal,dog
    context_param:
      type: string
      description: 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.
      example: alt=My image|caption=Nice photo
    upload_serializable_input:
      type: object
      description: Upload parameters that accept encoded string values, such as comma-separated tags, pipe-separated context metadata, and transformation strings.
      properties:
        tags:
          $ref: '#/components/schemas/tags_param'
        context:
          $ref: '#/components/schemas/context_param'
        eager:
          type: string
          description: A list of transformations to eagerly generate for the asset. Accepts either a single transformation or a pipe-separated list of transformations.
        transformation:
          type: string
          description: 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.
        allowed_formats:
          type: string
          description: |
            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.
          example: mp4,ogv,jpg,png,pdf
        headers:
          type: string
          description: |
            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.
          example: 'X-Robots-Tag: noindex'
        face_coordinates:
          type: string
          description: Face coordinates as comma-separated values, with multiple faces separated by pipes.
          pattern: ^(\d+,\d+,\d+,\d+)(\|\d+,\d+,\d+,\d+)*$
          example: 10,20,150,130|213,345,82,61
        custom_coordinates:
          type: string
          description: Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.
          pattern: ^(\d+,\d+,\d+,\d+)(\|\d+,\d+,\d+,\d+)*$
          example: 10,20,150,130
    upload_common_parameters:
      description: Common parameters for configuring an asset, including transformation, tagging, metadata, and moderation options.
      allOf:
        - $ref: '#/components/schemas/upload_base_parameters'
        - $ref: '#/components/schemas/upload_serializable_input'
    managed_delivery_type:
      type: string
      enum:
        - upload
        - private
        - authenticated
      description: Managed delivery types for assets uploaded and stored by Cloudinary.
    asset_delivery_type:
      type: string
      enum:
        - asset
      description: Static asset delivery type.
    upload_delivery_type:
      anyOf:
        - $ref: '#/components/schemas/managed_delivery_type'
        - $ref: '#/components/schemas/asset_delivery_type'
      description: Delivery types accepted by upload and rename operations.
    upload_type_parameter:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/upload_delivery_type'
          description: The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload).
    upload_parameters:
      description: Parameters for configuring asset uploads, including transformation, tagging, metadata, and delivery options.
      allOf:
        - $ref: '#/components/schemas/upload_common_parameters'
        - $ref: '#/components/schemas/upload_type_parameter'
    upload_request_parameters:
      type: object
      properties:
        upload_preset:
          type: string
          description: |
            (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.
    binary_upload_request:
      type: object
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - $ref: '#/components/schemas/upload_parameters'
        - $ref: '#/components/schemas/upload_request_parameters'
        - type: object
          properties:
            file:
              type: string
              format: binary
              description: |
                The actual data (byte array buffer).
      required:
        - file
    upload_request:
      type: object
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - $ref: '#/components/schemas/upload_parameters'
        - $ref: '#/components/schemas/upload_request_parameters'
        - type: object
          properties:
            file:
              type: string
              pattern: ^https?:\/\/|^s3:\/\/|^gcs:\/\/|^ftp:\/\/|^(data:[^;]*;base64,)|^file:\/\/
              description: |
                One of the following:
                - The remote HTTP or HTTPS URL address of an existing file.
                - The Data URI (Base64 encoded), max ~60 MB (62,910,000 chars).
                - The FTP address of an existing file.
                - Local file path starting with file://.
      required:
        - file
    version_id:
      type: string
      pattern: ^([0-9a-f]{32})+$
      description: Hexadecimal version ID; length is a positive multiple of 32 (typically 32 or 64).
    asset_id:
      type: string
      pattern: ^[0-9a-f]{32}$
      description: A 32-character hexadecimal asset ID.
    tags_response:
      type:
        - array
        - 'null'
      items:
        type: string
      description: Tag names assigned to the asset.
    context_full_response:
      type:
        - object
        - 'null'
      description: Contextual metadata grouped by kind. Custom user context appears under the 'custom' key. Other context kinds may also appear as additional keys.
      properties:
        custom:
          type: object
          additionalProperties:
            type: string
          description: User-defined contextual metadata as key-value pairs.
      additionalProperties:
        type: object
        additionalProperties:
          type: string
    faces_response:
      type:
        - array
        - 'null'
      description: Detected face coordinate rectangles [x, y, width, height].
      items:
        type: array
        items:
          type: integer
    coordinates_response:
      type:
        - object
        - 'null'
      description: Coordinate data for faces and custom regions.
      properties:
        faces:
          type: array
          description: Detected face coordinate rectangles [x, y, width, height].
          items:
            type: array
            items:
              type: integer
        custom:
          type: array
          description: Custom coordinate rectangles [x, y, width, height].
          items:
            type: array
            items:
              type: number
    upload_response:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: The URL of the uploaded file.
        secure_url:
          type: string
          format: uri
          description: The secure URL of the uploaded file.
        public_id:
          type: string
          description: The public ID of the uploaded file.
        version:
          type: integer
          description: The version of the uploaded file.
        version_id:
          $ref: '#/components/schemas/version_id'
        signature:
          type: string
          description: The signature of the uploaded file.
        width:
          type: integer
          description: The width of the uploaded file.
        height:
          type: integer
          description: The height of the uploaded file.
        asset_id:
          $ref: '#/components/schemas/asset_id'
        format:
          type: string
          description: The format of the uploaded file.
        resource_type:
          type: string
          description: The type of resource that was uploaded.
        created_at:
          type: string
          format: date-time
          description: The date and time the file was uploaded.
        tags:
          $ref: '#/components/schemas/tags_response'
          description: The tags of the uploaded file.
        context:
          $ref: '#/components/schemas/context_full_response'
        metadata:
          type: object
          additionalProperties: true
          description: Structured metadata associated with the uploaded file.
        pages:
          type: integer
          description: The number of pages in the uploaded file.
        bytes:
          type: integer
          description: The size of the uploaded file in bytes.
        type:
          type: string
          description: The type of the uploaded file.
        etag:
          type: string
          description: The ETag of the uploaded file.
        placeholder:
          type: boolean
          description: Whether the uploaded file is a placeholder.
        original_filename:
          type: string
          description: The original filename of the uploaded file.
        image_metadata:
          type: object
          description: The image metadata of the uploaded file.
        illustration_score:
          type: number
          description: The illustration score of the uploaded file.
        semi_transparent:
          type: boolean
          description: Whether the uploaded file is semi-transparent.
        grayscale:
          type: boolean
          description: Whether the uploaded file is grayscale.
        faces:
          $ref: '#/components/schemas/faces_response'
        coordinates:
          $ref: '#/components/schemas/coordinates_response'
        eager:
          type: array
          items:
            type: object
            properties:
              transformation:
                type: string
              width:
                type: integer
              height:
                type: integer
              bytes:
                type: integer
              format:
                type: string
              url:
                type: string
              secure_url:
                type: string
        asset_folder:
          type:
            - string
            - 'null'
          description: The asset folder where the file is stored.
        display_name:
          type: string
          description: The display name of the uploaded file.
        api_key:
          type: string
          description: The API key used to upload the file.
      example:
        asset_id: 3515c6000a548515f1134043f9785c2f
        public_id: gotjephlnz2jgiu20zni
        version: 1719307544
        version_id: 7d2cc533bee9ff39f7da7414b61fce7e
        signature: d0b1009e3271a942836c25756ce3e04d205bf754
        width: 1920
        height: 1441
        format: jpg
        resource_type: image
        created_at: '2024-06-25T09:25:44Z'
        tags: []
        pages: 1
        bytes: 896838
        type: upload
        etag: 2a2df1d2d2c3b675521e866599273083
        placeholder: false
        url: http://res.cloudinary.com/cld-docs/image/upload/v1719307544/gotjephlnz2jgiu20zni.jpg
        secure_url: https://res.cloudinary.com/cld-docs/image/upload/v1719307544/gotjephlnz2jgiu20zni.jpg
        asset_folder: ''
        display_name: gotjephlnz2jgiu20zni
        image_metadata:
          JFIFVersion: '1.01'
          ResolutionUnit: None
          XResolution: '1'
          YResolution: '1'
          Colorspace: RGB
          DPI: '0'
        illustration_score: 0
        semi_transparent: false
        grayscale: false
        original_filename: sample
        eager:
          - transformation: c_pad,h_300,w_400
            width: 400
            height: 300
            bytes: 26775
            format: jpg
            url: http://res.cloudinary.com/cld-docs/image/upload/c_pad,h_300,w_400/v1719307544/gotjephlnz2jgiu20zni.jpg
            secure_url: https://res.cloudinary.com/cld-docs/image/upload/c_pad,h_300,w_400/v1719307544/gotjephlnz2jgiu20zni.jpg
        api_key: '614335564976464'
    resource_type:
      type: string
      enum:
        - image
        - video
        - raw
      description: The type of resource.
    async_upload_response:
      type: object
      description: Response returned when an upload is processed asynchronously (async=true)
      required:
        - status
        - batch_id
        - type
      properties:
        status:
          type: string
          enum:
            - pending
          description: The status of the asynchronous upload. Will be 'pending' for async uploads.
        resource_type:
          $ref: '#/components/schemas/resource_type'
          description: The type of resource being uploaded. This field may be omitted if resource_type is not known at the time of the call.
        type:
          $ref: '#/components/schemas/upload_delivery_type'
          default: upload
          description: The delivery type of the asset. Defaults to 'upload'.
        public_id:
          type: string
          description: The public ID assigned to the upload. May be omitted if it will be auto-generated.
        batch_id:
          type: string
          description: A unique identifier for the asynchronous upload job.
        requester_ip:
          type: string
          description: The IP address of the requester. This is only included if a product environment has requester_ip tracking enabled.
      example:
        status: pending
        resource_type: image
        type: upload
        public_id: sample_image
        batch_id: 9c2f5a46b3a6c4d9e8f7g0h1i2j3k4l5
    html_redirect:
      type: string
      description: HTML redirect response
      example: <html><body>You are being <a href="http://example.cloudinary.com?bytes=5243000&amp;done=false&amp;kind=upload&amp;resource_type=image">redirected</a>.</body></html>
    api_error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
          required:
            - message
      required:
        - error
    non_final_chunk_upload_response:
      type: object
      description: |
        Status information returned for in-progress chunked uploads.
        Note that fields that are not yet determined or not known at the time of the call are omitted from the response.
      required:
        - done
        - bytes
      properties:
        done:
          type: boolean
          description: Whether the upload is complete. Will be false for all but the last chunk.
        bytes:
          type: integer
          description: The total number of bytes uploaded so far.
        kind:
          $ref: '#/components/schemas/upload_delivery_type'
          description: The delivery type of the asset. Defaults to 'upload'.
        resource_type:
          type: string
          description: The type of resource being uploaded (e.g., "image", "video", "raw"). May be omitted in early chunks when using auto detection.
        public_id:
          type: string
          description: The public ID assigned to the upload. May be omitted in early chunks if it will be auto-generated upon completion.
      example:
        done: false
        bytes: 1000000
        kind: upload
        resource_type: image
        public_id: sample_image
    rename_request:
      description: The rename request parameters.
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - type: object
          properties:
            from_public_id:
              type: string
              description: The public ID of the asset to rename.
            to_public_id:
              type: string
              description: The new public ID for the asset.
            type:
              description: The current delivery type of the asset.
              allOf:
                - $ref: '#/components/schemas/upload_delivery_type'
            to_type:
              description: The target delivery type for the renamed asset. If omitted, the delivery type remains unchanged.
              allOf:
                - $ref: '#/components/schemas/upload_delivery_type'
            overwrite:
              type: boolean
              description: Whether to overwrite the target asset if it already exists. Default is false.
              default: false
            invalidate:
              type: boolean
              description: Whether to invalidate CDN cache copies of the renamed asset. Default is false.
              default: false
            context:
              type: boolean
              description: Whether to include contextual metadata in the response. Default is false.
              default: false
            metadata:
              type: boolean
              description: Whether to include structured metadata in the response. Default is false.
              default: false
            notification_url:
              type: string
              format: uri
              description: URL to notify when the operation is complete.
          required:
            - from_public_id
            - to_public_id
    fetch_delivery_type:
      type: string
      enum:
        - fetch
        - url2png
      description: Fetch-based delivery types for assets retrieved from remote URLs.
    social_delivery_type:
      type: string
      enum:
        - facebook
        - twitter
        - twitter_name
        - instagram
        - instagram_name
        - gravatar
        - youtube
        - hulu
        - vimeo
        - animoto
        - dailymotion
        - worldstarhiphop
      description: Delivery types for assets fetched from third-party platforms.
    generated_delivery_type:
      type: string
      enum:
        - multi
        - sprite
        - text
        - list
      description: Delivery types for assets generated by Cloudinary operations.
    delivery_type_all:
      anyOf:
        - $ref: '#/components/schemas/managed_delivery_type'
        - $ref: '#/components/schemas/asset_delivery_type'
        - $ref: '#/components/schemas/fetch_delivery_type'
        - $ref: '#/components/schemas/social_delivery_type'
        - $ref: '#/components/schemas/generated_delivery_type'
        - type: string
          enum:
            - media_optimization
      description: All supported delivery types.
    destroy_request:
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - type: object
          required:
            - public_id
          properties:
            public_id:
              type: string
              description: The public ID of the asset to destroy.
            type:
              $ref: '#/components/schemas/delivery_type_all'
            invalidate:
              type: boolean
              default: false
              description: Whether to invalidate CDN cached copies of the asset.
            notification_url:
              type: string
              format: uri
              description: URL to receive a notification when the operation is complete.
    destroy_response:
      type: object
      properties:
        result:
          type: string
          enum:
            - ok
            - not found
          description: Result of the deletion operation.
    explode_request:
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - type: object
          properties:
            public_id:
              type: string
              description: The public ID of the PDF or animated image to generate from.
            format:
              type: string
              description: 'The format for the generated derived images. Default: png'
            transformation:
              type: string
              description: The transformation to apply. Must contain exactly one pg_all transformation parameter.
            notification_url:
              type: string
              format: uri
              description: The webhook URL to notify when the operation is complete.
            type:
              $ref: '#/components/schemas/managed_delivery_type'
              description: 'The delivery type of the asset. Default: upload'
          required:
            - public_id
            - transformation
    explode_response:
      type: object
      properties:
        status:
          type: string
          enum:
            - processing
          description: The status of the explode operation.
        batch_id:
          type: string
          description: The ID of the batch operation.
    explicit_delivery_type:
      anyOf:
        - $ref: '#/components/schemas/managed_delivery_type'
        - $ref: '#/components/schemas/asset_delivery_type'
        - $ref: '#/components/schemas/fetch_delivery_type'
        - $ref: '#/components/schemas/social_delivery_type'
      description: Delivery types accepted by the explicit operation.
    explicit_request:
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - $ref: '#/components/schemas/upload_common_parameters'
        - type: object
          properties:
            public_id:
              type: string
              description: The public ID of the existing asset to apply operations on.
            type:
              $ref: '#/components/schemas/explicit_delivery_type'
          required:
            - public_id
        - type: object
          properties:
            overwrite:
              type: boolean
              description: |
                When applying eager for already existing video transformations, this setting indicates whether to force the existing derived video resources to be regenerated. Default for videos: false.
                Note: When specifying existing eager transformations for images, corresponding derived images are always regenerated.
            quality_override:
              description: Override the quality setting for this asset.
              oneOf:
                - type: string
                - type: integer
    public_ids_param:
      type: array
      items:
        type: string
      maxItems: 1000
      description: 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.
      example:
        - sample
        - product_image
        - banner_2023
    asset_metadata_common_parameters:
      type: object
      description: Fields common to every bulk metadata-management operation.
      properties:
        public_ids:
          $ref: '#/components/schemas/public_ids_param'
        type:
          allOf:
            - $ref: '#/components/schemas/delivery_type_all'
          description: The delivery type of the assets to operate on. Defaults to `upload`.
      required:
        - public_ids
    tags_update_request:
      description: A tag command plus the assets it applies to.
      allOf:
        - $ref: '#/components/schemas/asset_metadata_common_parameters'
        - type: object
          properties:
            command:
              type: string
              enum:
                - add
                - remove
                - replace
                - remove_all
              description: |-
                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.
            tags:
              type: array
              items:
                type: string
              description: The tag names to apply. Required for `add`, `remove`, and `replace`; ignored for `remove_all`. A tag name must not contain a comma.
              example:
                - animal
                - dog
          required:
            - command
    public_ids_response:
      type: object
      description: The result of a bulk operation addressed by public ID.
      properties:
        public_ids:
          type: array
          items:
            type: string
          description: The public IDs the operation was actually applied to. Shorter than the requested list when assets were missing, unauthorized, or beyond the 1000-asset limit.
        unauthorized:
          type: array
          items:
            type: string
          description: The public IDs the caller lacks update permission for. Present only when at least one requested asset was unauthorized.
    context_update_request:
      description: A contextual-metadata command plus the assets it applies to.
      allOf:
        - $ref: '#/components/schemas/asset_metadata_common_parameters'
        - type: object
          properties:
            command:
              type: string
              enum:
                - add
                - remove_all
              description: |-
                The contextual-metadata operation to apply.

                - `add` merges the given key-value pairs into each asset's existing context. Keys
                  already present are overwritten; keys not mentioned are left intact. `context`
                  is required.
                - `remove_all` clears all contextual metadata. The `context` field is ignored.
            context:
              allOf:
                - $ref: '#/components/schemas/context_param'
              description: |-
                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.
          required:
            - command
    metadata_update_request:
      description: Structured metadata values plus the assets they apply to.
      allOf:
        - $ref: '#/components/schemas/asset_metadata_common_parameters'
        - type: object
          properties:
            metadata:
              $ref: '#/components/schemas/structured_metadata_param'
            clear_invalid:
              type: boolean
              description: 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.
          required:
            - metadata
    archive_resource_type:
      type: string
      enum:
        - image
        - video
        - raw
        - all
      description: The type of resources to include in the archive. "image" for images, "video" for videos, "raw" for non-media files, or "all" for mixed types.
    generate_archive_request:
      description: The archive generation parameters.
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - type: object
          properties:
            public_ids:
              type: array
              items:
                type: string
              maxItems: 1000
              description: The list of public IDs to include in the archive.
            tags:
              type: array
              items:
                type: string
              maxItems: 20
              description: Tags to filter which assets to include in the archive. Assets matching any of the specified tags are included.
            prefixes:
              type: array
              items:
                type: string
              maxItems: 20
              description: Select all assets where the public ID starts with this prefix.
            type:
              $ref: '#/components/schemas/delivery_type_all'
            transformations:
              type: string
              description: The transformations to apply to the assets before including them in the archive (separated by "|").
            mode:
              type: string
              enum:
                - download
                - create
                - create_and_download
              default: create
              description: |
                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
            target_format:
              type: string
              enum:
                - zip
                - tgz
              default: zip
              description: The format of the generated archive.
            target_public_id:
              type: string
              description: The public ID to assign to the generated archive, or the filename of the downloaded archive file.
            target_asset_folder:
              type: string
              description: The folder in your product environment where the generated archive should be stored.
            flatten_folders:
              type: boolean
              description: Whether to flatten all files to be in the root of the archive file.
              default: false
            flatten_transformations:
              type: boolean
              description: Whether to flatten the folder structure of the derived assets.
              default: false
            skip_transformation_name:
              type: boolean
              description: Whether to skip adding the transformation details to the file names in the archive.
              default: false
            allow_missing:
              type: boolean
              description: Whether to allow missing assets in the archive. If false, the operation will fail if any asset is not found.
              default: false
            expires_at:
              type: integer
              format: int64
              description: ("download" mode only) Unix timestamp indicating when the generated archive URL should expire.
            use_original_filename:
              type: boolean
              description: Whether to use the original filenames of the assets in the archive instead of public IDs (when available).
              default: false
            async:
              type: boolean
              description: ("create" mode only), specifies whether to generate the archive asynchronously.
              default: false
            notification_url:
              type: string
              format: uri
              description: ("create" mode only), specifies the URL to notify when the archive generation is complete.
            target_tags:
              type: array
              items:
                type: string
              description: A list of tag names to assign to the generated archive.
              example:
                - animal
                - dog
            keep_derived:
              type: boolean
              description: Whether to keep the derived assets used for generating the archive.
              default: false
            fully_qualified_public_ids:
              type: array
              items:
                type: string
              description: A list of fully qualified public IDs (resource_type/type/public_id) to include in the archive.
            search_expression:
              type: string
              description: A search expression to select assets to include in the archive.
            target_filename:
              type: string
              description: The filename for the downloaded archive file. Extension must match target_format (zip or tgz).
            asset_folders:
              anyOf:
                - type: array
                  items:
                    type: string
                  maxItems: 20
                - type: string
              description: 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.
    generate_archive_response:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/asset_id'
        public_id:
          type: string
          description: The public ID of the generated archive.
        version:
          type: integer
          description: The version number of the generated archive.
        version_id:
          $ref: '#/components/schemas/version_id'
        signature:
          type: string
          description: The API signature for the generated archive.
        resource_type:
          type: string
          description: The type of resource. Always "raw" for generated archives.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the archive was generated.
        tags:
          $ref: '#/components/schemas/tags_response'
          description: The tags assigned to the generated archive.
        bytes:
          type: integer
          description: The size of the generated archive in bytes.
        type:
          type: string
          description: The resource type of the generated archive.
        etag:
          type: string
          description: The ETag of the generated archive.
        placeholder:
          type: boolean
          description: Whether the generated archive is a placeholder.
        url:
          type: string
          description: The HTTP URL for downloading the generated archive.
        secure_url:
          type: string
          description: The HTTPS URL for downloading the generated archive.
        folder:
          type: string
          description: The folder where the archive is stored (only for product environments with Dynamic Folders disabled).
          deprecated: true
          x-speakeasy-deprecation-message: |
            If Dynamic folders mode is enabled on your product environment, this parameter is deprecated, and it's recommended to use the asset_folder parameter.
        resource_count:
          type: integer
          description: The number of unique resources included in the archive.
        file_count:
          type: integer
          description: The total number of files in the archive.
        asset_folder:
          type: string
          description: The folder in your product environment where the archive is stored.
        display_name:
          type: string
          description: The display name of the generated archive.
        missing_public_ids:
          type: array
          items:
            type: string
          description: The list of public IDs that were requested but not found.
        empty_tags:
          type: array
          items:
            type: string
          description: The list of tags that were requested but returned no results.
        empty_prefixes:
          type: array
          items:
            type: string
          description: The list of prefixes that were requested but returned no results.
    destroy_by_asset_id_request:
      type: object
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - type: object
          required:
            - asset_id
          properties:
            asset_id:
              $ref: '#/components/schemas/asset_id'
            invalidate:
              type: boolean
              description: Whether to invalidate CDN cache. Default is false.
            notification_url:
              type: string
              format: uri
              description: URL to receive completion notification.
            callback:
              type: string
              format: uri
              description: URL for redirect after operation completion.
    destroy_by_asset_id_response:
      type: object
      properties:
        result:
          type: string
          enum:
            - ok
            - not found
          description: The result of the deletion operation.
      required:
        - result
    text_request:
      type: object
      properties:
        text:
          type: string
          description: The text string to generate an image for.
        public_id:
          type: string
          description: The identifier that is used for accessing the generated image. If not specified, a unique identifier is generated.
        font_family:
          type: string
          description: The name of the font family.
        font_size:
          type: integer
          description: Font size in points.
          default: 12
        font_color:
          type: string
          description: Name or RGB representation of the font's color (e.g., red or
          default: black
        text_align:
          type: string
          description: Text alignment.
          enum:
            - left
            - center
            - right
            - justify
        font_weight:
          type: string
          description: Whether to use a normal or bold font.
          default: normal
          enum:
            - normal
            - bold
        font_style:
          type: string
          description: Whether to use a normal or italic font.
          default: normal
          enum:
            - normal
            - italic
        background:
          type: string
          description: Name or RGB representation of the background color (e.g., red or
          default: transparent
        opacity:
          type: integer
          description: Text opacity value between 0 (invisible) and 100.
          default: 100
          minimum: 0
          maximum: 100
        text_decoration:
          type: string
          description: Text decoration style.
          default: none
          enum:
            - none
            - underline
        line_spacing:
          type: integer
          description: The spacing between lines of text in pixels.
      required:
        - text
    text_response:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/asset_id'
        public_id:
          type: string
          description: The public identifier of the asset.
        version:
          type: integer
          description: The version number of the asset.
        version_id:
          $ref: '#/components/schemas/version_id'
        signature:
          type: string
          description: The signature for the asset.
        width:
          type: integer
          description: The width of the generated image in pixels.
        height:
          type: integer
          description: The height of the generated image in pixels.
        format:
          type: string
          description: The format of the generated image.
        resource_type:
          type: string
          description: The type of resource (image).
        created_at:
          type: string
          format: date-time
          description: The creation timestamp.
        tags:
          $ref: '#/components/schemas/tags_response'
          description: Array of tags assigned to the asset.
        pages:
          type: integer
          description: Number of pages in the asset.
        bytes:
          type: integer
          description: Size of the asset in bytes.
        type:
          type: string
          description: The storage type of the asset.
        etag:
          type: string
          description: The ETag of the asset.
        placeholder:
          type: boolean
          description: Whether the asset is a placeholder.
        url:
          type: string
          description: The HTTP URL for accessing the asset.
        secure_url:
          type: string
          description: The HTTPS URL for accessing the asset.
        display_name:
          type: string
          description: The display name of the asset.
        access_control:
          $ref: '#/components/schemas/access_control'
        regions:
          type: array
          items:
            type: object
          description: Region information for the asset.
        moderation:
          type: object
          description: Moderation information for the asset.
        info:
          type: object
          description: Additional information about the asset.
    concat_request:
      description: Parameters for concatenating remote video segments into a single MP4 asset.
      allOf:
        - $ref: '#/components/schemas/signature_parameters'
        - $ref: '#/components/schemas/upload_common_parameters'
        - type: object
          required:
            - urls
          properties:
            urls:
              type: array
              items:
                type: string
                format: uri
              minItems: 1
              maxItems: 256
              description: Ordered list of HTTP(S) URLs of the video segments to concatenate.
    concat_response:
      type: object
      description: Response returned when a concat job is accepted.
      required:
        - status
        - unique_upload_id
      properties:
        status:
          type: string
          enum:
            - processing
          description: The status of the concat job. Always 'processing'.
        unique_upload_id:
          type: string
          description: Identifier shared by all chunked-upload parts produced for this concat job (sent as the `X-Unique-Upload-Id` header on each `/video/upload_chunked` request).
        public_id:
          type: string
          description: The public ID assigned to the concatenated asset, if one was supplied in the request.
        resource_type:
          type: string
          enum:
            - video
          description: Always 'video' — concat produces an MP4.
      example:
        status: processing
        unique_upload_id: 2fd4e1c67a2d28fce
        public_id: my_combined_video
        resource_type: video
    resource_types_response:
      type: object
      properties:
        resource_types:
          type: array
          description: The list of available resource types.
          items:
            type: string
            enum:
              - image
              - raw
              - video
            x-enum-descriptions:
              - Image files (jpg, png, gif, etc.).
              - Raw files (documents, text files, etc.).
              - Video files (mp4, webm, etc.).
          example:
            - image
            - raw
            - video
    direction_enum:
      type: string
      enum:
        - asc
        - desc
      description: Sort direction.
    resource_fields_enum:
      type: string
      enum:
        - public_id
        - asset_id
        - asset_folder
        - folder
        - display_name
        - format
        - version
        - resource_type
        - type
        - created_at
        - bytes
        - width
        - height
        - backup
        - access_control
        - access_mode
        - url
        - secure_url
        - tags
        - context
        - metadata
        - moderation_kind
        - moderation_status
        - placeholder
        - regions
        - is_audio
      description: Valid field names for selective resource responses.
    info:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/asset_id'
        public_id:
          type: string
        asset_folder:
          type: string
        display_name:
          type: string
        folder:
          type: string
          x-speakeasy-deprecation-message: Use asset_folder instead with folder decoupling.
        filename:
          type: string
        format:
          type: string
        version:
          type: integer
        resource_type:
          type: string
        type:
          $ref: '#/components/schemas/delivery_type_all'
        created_at:
          type: string
          format: date-time
        uploaded_at:
          type: string
          format: date-time
        bytes:
          type: integer
        backup_bytes:
          type: integer
        width:
          type:
            - integer
            - 'null'
        height:
          type:
            - integer
            - 'null'
        aspect_ratio:
          type:
            - number
            - 'null'
        pixels:
          type:
            - integer
            - 'null'
        tags:
          allOf:
            - $ref: '#/components/schemas/tags_response'
          description: Included if 'tags=true' parameter is used.
        context:
          allOf:
            - $ref: '#/components/schemas/context_full_response'
          description: Included if 'context=true' parameter is used.
        metadata:
          type: object
          additionalProperties: true
        moderation_kind:
          type: string
          description: The type of moderation applied to the asset.
          example: manual
        moderation_status:
          type: string
          description: The current status of the moderation process for the asset.
          example: pending
        moderation:
          type: array
          description: Included if 'moderations=true' parameter is used.
          items:
            type: object
            properties:
              kind:
                type: string
              status:
                type: string
              updated_at:
                type: string
                format: date-time
        backup:
          type: boolean
        url:
          type: string
          format: uri
        secure_url:
          type: string
          format: uri
        status:
          type: string
        access_control:
          anyOf:
            - $ref: '#/components/schemas/access_control'
            - type: 'null'
        etag:
          type: string
        animated:
          type:
            - boolean
            - 'null'
          description: Whether the asset is animated (e.g., GIF, animated WebP). Null for non-animated assets.
        duration:
          type:
            - number
            - 'null'
          description: Duration in seconds for video/audio assets. Null for images.
        resource_subtype:
          type:
            - string
            - 'null'
          description: The subtype of the resource (e.g., for video). Null when not applicable.
        substatus:
          type:
            - string
            - 'null'
          description: The substatus of the resource. Null when not set.
        related_assets:
          type:
            - array
            - 'null'
          description: Related assets linked to this resource. Null when none linked.
          items:
            type: object
        last_updated:
          type:
            - object
            - 'null'
          properties:
            access_control_updated_at:
              type: string
              format: date-time
            context_updated_at:
              type: string
              format: date-time
            metadata_updated_at:
              type: string
              format: date-time
            public_id_updated_at:
              type: string
              format: date-time
            tags_updated_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
        next_cursor:
          type: string
          description: Cursor for paginating derived assets.
        derived:
          type: array
          items:
            type: object
            properties:
              transformation:
                type: string
              format:
                type: string
              bytes:
                type: integer
              id:
                type: string
              url:
                type: string
                format: uri
              secure_url:
                type: string
                format: uri
        faces:
          allOf:
            - $ref: '#/components/schemas/faces_response'
          description: Detected face rectangles. Included if 'faces=true' parameter is used.
        coordinates:
          allOf:
            - $ref: '#/components/schemas/coordinates_response'
          description: Face and custom coordinate data. Included if 'coordinates=true' parameter is used.
        illustration_score:
          type: number
        semi_transparent:
          type: boolean
        grayscale:
          type: boolean
        colors:
          type: array
          items:
            type: array
        predominant:
          type: object
          additionalProperties:
            type: array
            items:
              type: array
        versions:
          type: array
          items:
            type: object
            properties:
              version_id:
                $ref: '#/components/schemas/version_id'
              version:
                type: string
              format:
                type:
                  - string
                  - 'null'
              size:
                type: integer
              time:
                type: string
                format: date-time
              restorable:
                type: boolean
        info:
          type: object
          description: Additional asset information (visual search, recognized people, etc.)
        derivatives:
          type:
            - array
            - 'null'
          description: Included if 'derived=true' parameter is used. Null when no derivatives exist.
          items:
            type: object
            properties:
              id:
                type: string
                description: The unique identifier of the derived resource.
                example: 5a73fd588cb301206c0a5c5c6ad796b3
              transformation:
                type: string
                description: The transformation string that was applied.
                example: w_300,h_100/
              transformation_signature:
                type: string
                description: The unique signature of the transformation.
                example: 658a49d8-2944-37db-9825-1ddface10c7b
              secure_url:
                type: string
                format: uri
                description: The secure URL for accessing the derived resource.
                example: https://res.cloudinary.com/demo/image/upload/w_300,h_100/sample
    list_response:
      type: object
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/info'
        next_cursor:
          type:
            - string
            - 'null'
        total_count:
          type: integer
    restore_request:
      type: object
      required:
        - asset_ids
      properties:
        asset_ids:
          type: array
          items:
            $ref: '#/components/schemas/asset_id'
          description: The unique and immutable asset IDs of backed up assets to restore.
          maxItems: 100
          example:
            - 2262b0b5eb88f1fd7724e29b0e57d730
            - d23c0526e6feca2c343e40c2fce5231a
        versions:
          type: array
          items:
            type: string
          description: If you specify versions, the number of versions in the array must exactly match the number of asset_ids.
          example:
            - c3fe4be5921eb89acd9af738c892f654
            - d214063097a43d1d1293db61a397f60f
        notification_url:
          type: string
          format: uri
          description: The URL that will receive notification when restore is complete.
          example: https://example.com/webhook
    restore_response:
      type: object
      additionalProperties:
        oneOf:
          - $ref: '#/components/schemas/info'
          - type: object
            properties:
              error:
                type: string
                enum:
                  - no_backup
                  - failed
                  - unauthorized
                description: The error message if restore failed for a specific asset.
    DeleteResourceByPublicIdsRequest:
      description: The delete request specifying which resources to delete.
      type: object
      properties:
        public_ids:
          type: array
          items:
            type: string
          description: A list of public IDs of the resources to delete.
        prefix:
          type: string
          description: Delete all assets, including derived assets, where the public ID starts with the specified prefix (up to a maximum of 1000 original resources).
        all:
          type: boolean
          description: Delete all assets (of the relevant resource_type and type), including derived assets (up to a maximum of 1000 original resources).
        resource_type:
          allOf:
            - $ref: '#/components/schemas/resource_type'
            - default: image
          description: 'The type of asset. Relevant as a parameter only when using the SDKs (the resource_type is included in the endpoint URL when using the REST API). Note: use video for all video and audio assets, such as .mp3. Default: image.'
        keep_original:
          type: boolean
          default: false
          description: 'Whether to delete only the derived assets. Default: false.'
        invalidate:
          type: boolean
          default: false
          description: 'Whether to also invalidate the copies of the resource on the CDN. It usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN. Default: false.'
        next_cursor:
          type: string
          description: (Only when deleting by prefix or all) When a deletion request has more than 1000 resources to delete, the response includes the partial boolean parameter set to true, as well as a next_cursor value. You can then specify this returned next_cursor value as a parameter of the following deletion request.
        transformations:
          type: string
          description: Only the derived assets matching this hash of transformation parameters will be deleted. You can include multiple transformations separated by a pipe character (|).
      oneOf:
        - required:
            - public_ids
        - required:
            - prefix
        - required:
            - all
    ResourceUpdateRequest:
      description: The resource properties to update.
      type: object
      properties:
        display_name:
          type: string
          description: The display name of the resource.
          example: My Product Image
        unique_display_name:
          type: boolean
          description: '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'
          default: false
        asset_folder:
          type: string
          description: The folder where the asset should be placed.
          example: products/summer
        tags:
          $ref: '#/components/schemas/tags_param'
        context:
          $ref: '#/components/schemas/context_param'
        metadata:
          $ref: '#/components/schemas/structured_metadata_param'
        clear_invalid:
          type: boolean
          description: 'Whether to clear invalid metadata fields. If false, invalid fields will be preserved. Default: false'
          default: false
        face_coordinates:
          type: string
          description: Face coordinates as comma-separated values, with multiple faces separated by pipes.
          pattern: ^(\d+,\d+,\d+,\d+)(\|\d+,\d+,\d+,\d+)*$
          example: 10,20,150,130|213,345,82,61
        custom_coordinates:
          type: string
          description: Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.
          pattern: ^(\d+,\d+,\d+,\d+)(\|\d+,\d+,\d+,\d+)*$
          example: 10,20,150,130|213,345,82,61
        regions:
          type: string
          description: 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.
          example: '{"face": [[100, 200], [300, 400]], "body": [[50, 60], [70, 80], [90, 100]]}'
        quality_override:
          type: string
          description: Quality override value that will override any automatic quality transformations.
          examples:
            - 80:420
            - auto:best
        moderation_status:
          type: string
          enum:
            - approved
            - rejected
          description: The moderation status of the resource.
        auto_tagging:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence threshold for auto-tagging.
        detection:
          type: string
          description: The type of detection to perform on the resource.
          examples:
            - captioning
            - coco_v2
            - watermark-detection
        ocr:
          type: string
          description: The type of OCR to perform on the resource. Set to adv_ocr, optionally with options (e.g., adv_ocr:document).
          example: adv_ocr
        raw_convert:
          type: string
          description: The conversion to apply for raw files (e.g., aspose, google_speech, extract_text).
          example: google_speech
        categorization:
          type: string
          description: The type of categorization to perform on the resource. Optionally append a language code suffix (e.g., google_tagging:fr).
          example: google_tagging
        visual_search:
          type: boolean
          description: 'Whether to index the resource with visual search. If true, the resource will be indexed for visual search capabilities. Default: false'
        background_removal:
          type: string
          description: The background removal provider to use for the resource. Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).
          example: cloudinary_ai
        access_control:
          $ref: '#/components/schemas/access_control'
      additionalProperties: false
    tags_list_response:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
        next_cursor:
          type:
            - string
            - 'null'
    delete_backup_versions_request:
      type: object
      properties:
        version_ids:
          type: array
          items:
            type: string
          description: The list of version IDs to delete from backup.
          example:
            - 5552aa57e67445552a3cdc1110a0115
            - 383e22a57167445552a3cdc16f0a0c85
      required:
        - version_ids
    delete_backup_versions_response:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/asset_id'
        deleted_version_ids:
          type: array
          items:
            $ref: '#/components/schemas/version_id'
          description: The list of version IDs that were successfully deleted.
      required:
        - asset_id
        - deleted_version_ids
    backup_version_failure:
      type: object
      properties:
        version_id:
          $ref: '#/components/schemas/version_id'
          description: The version ID that failed to delete.
        error:
          type: string
          description: The error message explaining the failure.
    delete_backup_versions_partial_response:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/asset_id'
        deleted_version_ids:
          type: array
          items:
            $ref: '#/components/schemas/version_id'
          description: The list of version IDs that were successfully deleted.
        failures:
          type: array
          items:
            $ref: '#/components/schemas/backup_version_failure'
          description: The list of version IDs that failed to delete with error messages.
      required:
        - asset_id
        - deleted_version_ids
    usage_response:
      type: object
      properties:
        plan:
          type: string
          description: The current plan name
        last_updated:
          type: string
          format: date
          description: When the usage data was last updated
        date_requested:
          type: string
          format: date-time
          description: The date for which usage was requested
        transformations:
          type: object
          properties:
            usage:
              type: integer
              description: Number of transformations used
        objects:
          type: object
          properties:
            usage:
              type: integer
              description: Number of objects used
            limit:
              type: integer
              description: Object limit for the plan
            used_percent:
              type: number
              format: float
              description: Percentage of object limit used
        bandwidth:
          type: object
          properties:
            usage:
              type: integer
              description: Bandwidth used in bytes
            limit:
              type: integer
              description: Bandwidth limit for the plan
            used_percent:
              type: number
              format: float
              description: Percentage of bandwidth limit used
        storage:
          type: object
          properties:
            usage:
              type: integer
              description: Storage used in bytes
            limit:
              type: integer
              description: Storage limit for the plan
            used_percent:
              type: number
              format: float
              description: Percentage of storage limit used
        impressions:
          type: object
          properties:
            usage:
              type: integer
              description: Number of impressions used
        seconds_delivered:
          type: object
          properties:
            usage:
              type: integer
              description: Number of seconds delivered
        resources:
          type: integer
          description: Number of resources stored
        derived_resources:
          type: integer
          description: Number of derived resources
        requests:
          type: integer
          description: Number of requests made
        media_limits:
          type: object
          description: Upload size and pixel limits
          properties:
            image_max_size_bytes:
              type: integer
              description: Maximum size for images in bytes
            video_max_size_bytes:
              type: integer
              description: Maximum size for videos in bytes
            raw_max_size_bytes:
              type: integer
              description: Maximum size for raw files in bytes
            image_max_px:
              type: integer
              description: Maximum pixels for images
            asset_max_total_px:
              type: integer
              description: Maximum total pixels for assets
    video_view:
      type: object
      properties:
        video_public_id:
          type: string
          description: The full public ID of the video.
        video_duration:
          type:
            - number
            - 'null'
          description: The duration in seconds of the video.
        video_transformation:
          type:
            - string
            - 'null'
          description: The transformation applied to the video.
        video_extension:
          type:
            - string
            - 'null'
          description: The file extension of the video.
        viewer_application_name:
          type:
            - string
            - 'null'
          description: The application used to view the video.
        viewer_location_country_code:
          type:
            - string
            - 'null'
          description: The 2-digit ISO country code of the viewer location.
        viewer_os_identifier:
          type:
            - string
            - 'null'
          description: The full identifier for the viewer's operating system.
        view_watch_time:
          type:
            - number
            - 'null'
          description: The length of time the video was viewed.
        view_ended_at:
          type: string
          format: date-time
          description: The date when the video view ended.
    video_views_response:
      type: object
      properties:
        request_id:
          type: string
          description: Unique identifier for the request.
        next_cursor:
          type: string
          description: Cursor value for pagination.
        data:
          type: array
          items:
            $ref: '#/components/schemas/video_view'
    relate_assets_by_asset_id_request:
      description: The asset relation request.
      type: object
      required:
        - assets_to_relate
      properties:
        assets_to_relate:
          type: array
          description: Relates the asset to all the assets specified in this array of up to 10 assets, specified by their asset IDs.
          items:
            $ref: '#/components/schemas/asset_id'
          maxItems: 10
          example:
            - fd19f6964b9d377b7ac39752f03d7596
            - b7dcc099f53ea9b2e9eb602634fc0fc7
    asset_relation_info:
      type: object
      properties:
        message:
          type: string
          example: success
          description: The message indicating the result of the operation.
        code:
          type: string
          enum:
            - rejected_ids
            - invalid_ids
            - internal_error_ids
            - non_existing_ids
            - invalid_relate_to_self_id
            - already_exists_ids
            - relation_does_not_exist_ids
            - success_ids
          example: success_ids
          description: The code indicating the result of the operation.
        asset:
          type: string
          example: fd19f6964b9d377b7ac39752f03d7596
          description: The identifier of the asset, either asset ID or public ID path.
        status:
          type: integer
          example: 200
          description: The HTTP status code indicating the result of the operation.
    asset_relations_response:
      type: object
      properties:
        failed:
          type: array
          items:
            $ref: '#/components/schemas/asset_relation_info'
        success:
          type: array
          items:
            $ref: '#/components/schemas/asset_relation_info'
      example:
        failed: []
        success:
          - message: success
            code: success_ids
            asset: fd19f6964b9d377b7ac39752f03d7596
            status: 200
          - message: success
            code: success_ids
            asset: b7dcc099f53ea9b2e9eb602634fc0fc7
            status: 200
    unrelate_assets_by_asset_id_request:
      description: The asset unrelation request.
      type: object
      required:
        - assets_to_unrelate
      properties:
        assets_to_unrelate:
          type: array
          description: Unrelates the asset from all the assets specified in this array of assets, specified by their asset IDs.
          items:
            $ref: '#/components/schemas/asset_id'
          example:
            - fd19f6964b9d377b7ac39752f03d7596
            - b7dcc099f53ea9b2e9eb602634fc0fc7
    asset_relations_delete_response:
      type: object
      properties:
        failed:
          type: array
          items:
            $ref: '#/components/schemas/asset_relation_info'
        success:
          type: array
          items:
            $ref: '#/components/schemas/asset_relation_info'
      example:
        failed: []
        success:
          - message: success
            code: success_ids
            asset: fd19f6964b9d377b7ac39752f03d7596
            status: 200
          - message: success
            code: success_ids
            asset: b7dcc099f53ea9b2e9eb602634fc0fc7
            status: 200
    relate_assets_by_public_id_request:
      description: The asset relation request.
      type: object
      required:
        - assets_to_relate
      properties:
        assets_to_relate:
          type: array
          description: Relates the asset to all the other assets specified in this array of up to 10 assets, specified as resource_type/type/public_id.
          items:
            type: string
          maxItems: 10
          example:
            - raw/upload/dog_subtitles.srt
            - image/authenticated/dog_license
    unrelate_assets_by_public_id_request:
      description: The asset unrelation request.
      type: object
      required:
        - assets_to_unrelate
      properties:
        assets_to_unrelate:
          type: array
          description: Unrelates the asset from all the assets specified in this array of assets, specified as resource_type/type/public_id.
          items:
            type: string
          example:
            - raw/upload/dog_subtitles.srt
            - image/authenticated/dog_license
    folder:
      type: object
      properties:
        name:
          type: string
          description: The name of the folder.
        path:
          type: string
          description: The full path of the folder.
        external_id:
          type: string
          description: The unique identifier for the folder.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the folder was created.
      required:
        - name
        - path
        - external_id
      example:
        name: a
        path: folder/a
        external_id: abcdefg1234567890
    folders_list_response:
      type: object
      properties:
        folders:
          type: array
          description: The root folders in the product environment.
          items:
            $ref: '#/components/schemas/folder'
        next_cursor:
          type:
            - string
            - 'null'
          description: A cursor for pagination. Always null for root folders.
        total_count:
          type: integer
          description: The total number of root folders.
      required:
        - folders
        - next_cursor
        - total_count
      example:
        folders:
          - name: a
            path: folder/a
            external_id: abcdefg1234567890
          - name: b
            path: folder/b
            external_id: hijklmn0987654321
        next_cursor:
        total_count: 2
    move_folder_request:
      description: The folder move/rename request.
      type: object
      properties:
        to_folder:
          type: string
          description: The new path for the folder.
          example: product1/test1
      required:
        - to_folder
    folder_name_path:
      type: object
      properties:
        name:
          type: string
          description: The name of the folder.
        path:
          type: string
          description: The full path of the folder.
      required:
        - name
        - path
    move_folder_response:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/folder_name_path'
          example:
            name: test
            path: product/test
        to:
          $ref: '#/components/schemas/folder_name_path'
          example:
            name: test1
            path: product1/test1
      required:
        - from
        - to
    create_folder_response:
      allOf:
        - $ref: '#/components/schemas/folder'
        - type: object
          properties:
            success:
              type: boolean
              description: Whether the operation was successful.
              example: true
    delete_folder_response:
      type: object
      properties:
        deleted:
          type: array
          description: List of deleted folder paths.
          items:
            type: string
          example:
            - product/test
      required:
        - deleted
    search_sort_pair:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/direction_enum'
      minProperties: 1
      maxProperties: 1
      description: A single field-to-direction mapping. The object must contain exactly one key with value 'asc' or 'desc'.
    search_sort_by:
      type: array
      items:
        $ref: '#/components/schemas/search_sort_pair'
      description: |
        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"}].
      example:
        - created_at: desc
        - public_id: asc
    folders_search_response:
      type: object
      properties:
        total_count:
          type: integer
          description: The total number of folders matching the search.
        time:
          type: integer
          description: The time taken to execute the search (ms).
        next_cursor:
          type:
            - string
            - 'null'
          description: A cursor for pagination.
        folders:
          type: array
          items:
            $ref: '#/components/schemas/folder'
          description: The folders matching the search.
      required:
        - total_count
        - time
        - folders
      example:
        total_count: 14
        time: 1136
        next_cursor: 0a37f8c9f65e79c1cbe782d47987ed108d9f9e0dad4b0666adbf4eac9a634191996204a0ef84ce7b3e0e
        folders:
          - name: 1_folder_param
            path: my_parent/1_folder_param
            external_id: c7c08f8ecf093353d669d2ea3123967c7
          - name: a_folder_param
            path: my_parent/a_folder_param
            external_id: c7c08b736592482c1125ba5d689ab8779
    folder_search_request:
      type: object
      properties:
        expression:
          type: string
          description: The (Lucene-like) string expression specifying the search query.
        sort_by:
          $ref: '#/components/schemas/search_sort_by'
        max_results:
          type: integer
          maximum: 500
          default: 50
          description: Maximum number of folders to return (max 500, default 50).
        next_cursor:
          type: string
          description: When more results are available, use the next_cursor value from the previous response.
    principal_type:
      type: string
      enum:
        - user
        - group
        - apiKey
      description: The type of principal.
    folder_role:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the role.
          example: cld::role::folder::viewer
        name:
          type: string
          description: The human-readable name of the role.
          example: Manager
        description:
          type: string
          description: A summary of the permissions granted by this role.
          example: Editor permissions, plus delete, share, and full download access.
        inherited:
          type: boolean
          description: Indicates whether this role is inherited from an ancestor folder. If false, it's assigned directly to the requested folder.
          example: false
      required:
        - id
        - name
        - description
        - inherited
    folder_role_assignment:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/principal_type'
          example: user
        id:
          type: string
          description: The unique identifier of the principal. For `apiKey`, provide the API key value.
          example: cec735fd65b7d541f35d9f661d130f
        folder_id:
          type: string
          description: The ID of the folder where this role assignment was defined, either the requested folder or one of its ancestor folders.
          example: cd7e9d690a014c68ae8b58f08e090cb03a
        roles:
          type: array
          description: The roles assigned to this principal for this folder.
          items:
            $ref: '#/components/schemas/folder_role'
      required:
        - type
        - id
        - folder_id
        - roles
    permitted_role:
      type: object
      properties:
        id:
          type: string
          description: The role identifier.
          example: cld::role::folder::manager
        name:
          type: string
          description: The human-readable name of the role.
          example: Manager
        description:
          type: string
          description: A description of the role's permissions.
          example: Editor permissions, plus delete, share, and full download access.
      required:
        - id
        - name
        - description
    folder_roles_response:
      type: object
      properties:
        shared_with:
          type: array
          description: An array of principals (users, groups, or API keys) with their role assignments on this folder, including roles inherited from ancestor folders.
          items:
            $ref: '#/components/schemas/folder_role_assignment'
        permitted_roles:
          type: array
          description: The roles the authenticated user can assign on this folder. Users can assign only roles at or below their own permission level for this folder. Returned only when `include_assignable_roles` is true.
          items:
            $ref: '#/components/schemas/permitted_role'
      example:
        shared_with:
          - type: user
            id: cec735fd65b7d541f35d9f661d130f
            folder_id: cd7e9d690a014c68ae8b58f08e090cb03a
            roles:
              - id: cld::role::folder::viewer
                description: View and download public assets.
                name: Viewer
                inherited: false
        permitted_roles:
          - id: cld::role::folder::viewer
            name: Viewer
            description: View and download public assets.
          - id: cld::role::folder::contributor
            name: Contributor
            description: Viewer permissions, plus add assets and create subfolders.
    assign_folder_roles_request:
      type: object
      properties:
        principal:
          type: object
          description: The user, group, or API key whose role assignments are being modified.
          properties:
            type:
              $ref: '#/components/schemas/principal_type'
              example: apiKey
            id:
              type: string
              description: The unique identifier of the principal. For `apiKey`, provide the API key value.
              example: '799451857115779'
          required:
            - type
            - id
        operation:
          type: string
          enum:
            - add
            - remove
          description: The operation to perform on the principal’s role assignments. `add` grants the specified roles; `remove` revokes them.
          example: add
        roles:
          type: array
          description: The role IDs to add or remove.
          items:
            type: string
          maxItems: 10
          example:
            - cld::role::folder::viewer
      required:
        - principal
        - operation
        - roles
      example:
        principal:
          id: '799451857115779'
          type: apiKey
        operation: add
        roles:
          - cld::role::folder::contributor
    success_response:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
          example: true
      required:
        - success
    folder_rename_request:
      type: object
      description: The source and destination folder paths.
      properties:
        path:
          type: string
          description: The full path of the folder to rename or move.
          example: product/test
        to_path:
          type: string
          description: The new full path for the folder.
          example: product/test_renamed
        resources_limit:
          type: integer
          description: The maximum number of assets that may be moved by the rename. Assets beyond this limit cause the rename to be rejected.
          example: 100000
        resources_size_limit:
          type: integer
          description: The maximum total size, in bytes, of the assets that may be moved by the rename.
          example: 1099511627776
        max_derived:
          type: integer
          description: The maximum number of derived assets that may be moved by the rename.
          example: 1000000
      required:
        - path
        - to_path
    folder_rename_response:
      type: object
      description: The result of renaming or moving a folder.
      properties:
        folder_deleted:
          type: boolean
          description: Whether the source folder was deleted after the move.
        moved:
          type: integer
          description: The number of assets successfully moved.
        rejected:
          type: integer
          description: The number of assets rejected during the move.
        failed:
          type: integer
          description: The number of assets that failed to move.
    folder_by_id_request:
      type: object
      description: The identifier of the folder to retrieve.
      properties:
        id:
          type: string
          description: The immutable identifier of the folder to retrieve.
          example: cd7e9d690a014c68ae8b58f08e090cb03a
      required:
        - id
    folder_detail_response:
      description: |
        The details of a folder. Returns the standard folder fields plus aggregation and ancestor
        fields when available.
      allOf:
        - $ref: '#/components/schemas/folder'
        - type: object
          properties:
            resource_count:
              type: integer
              description: The number of assets directly within the folder.
            total_bytes:
              type: number
              description: The total size, in bytes, of the assets within the folder.
            last_uploaded_at:
              type:
                - integer
                - 'null'
              description: The Unix timestamp of the most recent upload into the folder.
            ancestors:
              type: array
              description: The ancestor folders of this folder, ordered from root to parent.
              items:
                $ref: '#/components/schemas/folder'
          additionalProperties: true
    folder_by_path_request:
      type: object
      description: The path of the folder to retrieve.
      properties:
        path:
          type: string
          description: The full path of the folder to retrieve. Use an empty string for the root folder.
          example: product/test
        case_sensitive:
          type: boolean
          description: Whether to match the folder path case-sensitively. If false, the path is matched case-insensitively.
      required:
        - path
    folder_descendants_request:
      type: object
      description: The parent folder identifier and optional descendant filter.
      properties:
        id:
          type: string
          description: The immutable identifier of the parent folder whose descendants are returned.
          example: cd7e9d690a014c68ae8b58f08e090cb03a
        filter_ids:
          type: array
          description: A list of folder identifiers to restrict the returned descendants to.
          items:
            type: string
        inclusive:
          type: boolean
          description: Whether to include the parent folder itself in the results. If false, only descendants are returned.
      required:
        - id
    folder_descendants_response:
      type: object
      description: The descendant folders of a folder.
      properties:
        folders:
          type: array
          description: The descendant folders.
          items:
            $ref: '#/components/schemas/folder_detail_response'
      required:
        - folders
    DerivedDestroyRequest:
      type: object
      description: Request parameters for deleting derived resources
      properties:
        derived_resource_ids:
          type: array
          items:
            type: string
          description: Array of derived resource IDs to delete specific derived resources
          example:
            - 1234567890abcdef
            - fedcba0987654321
        invalidate:
          type: boolean
          description: Whether to invalidate the CDN cache for the deleted resources
          example: true
      required:
        - derived_resource_ids
    DerivedDestroyResponse:
      type: object
      description: Response for derived resource deletion
      properties:
        deleted:
          type: object
          additionalProperties:
            type: string
            enum:
              - deleted
              - not_found
          description: Map of derived resource IDs to deletion status
          example:
            1234567890abcdef: deleted
            fedcba0987654321: not_found
        unauthorized:
          type: array
          items:
            type: string
          description: Array of derived resource IDs that were not authorized to be deleted
        invalidation:
          type: object
          properties:
            took:
              type: number
              description: Time taken for CDN invalidation in seconds
              example: 25
            urls:
              type: array
              items:
                type: string
              description: Array of URLs that were invalidated
              example:
                - /image/upload/w_100/sample
                - /image/upload/w_200/sample
    invalidate_by_urls_request:
      type: object
      description: The set of delivery URLs whose derived assets should be invalidated.
      properties:
        urls:
          type: array
          description: The delivery URLs whose cached derived assets should be invalidated.
          items:
            type: string
          example:
            - https://res.cloudinary.com/demo/image/upload/w_100/sample.jpg
        skip_reporting:
          type: boolean
          description: Whether to skip recording this invalidation against the product environment usage. If false, the invalidation is counted towards usage. Default is false.
      required:
        - urls
    invalidate_by_urls_response:
      type: object
      description: The result of invalidating derived assets by delivery URLs.
      properties:
        cdn_invalidated:
          type: boolean
          description: Whether the assets were invalidated directly on the CDN.
        took:
          type: number
          description: The time the invalidation took, in seconds.
        urls:
          type: array
          description: The delivery URLs that were invalidated.
          items:
            type: string
        unauthorized_urls:
          type: array
          description: The delivery URLs that were skipped because the caller lacked update permission.
          items:
            type: string
    resource_get_by_body_request:
      type: object
      description: The identifying attributes of the asset to retrieve.
      properties:
        public_id:
          type: string
          description: The public ID of the asset to retrieve.
          example: sample
        resource_type:
          allOf:
            - $ref: '#/components/schemas/resource_type'
          description: The type of the asset (image, video, or raw).
          example: image
        kind:
          allOf:
            - $ref: '#/components/schemas/managed_delivery_type'
          description: The delivery type of the asset.
          example: upload
        with_elastic:
          type: boolean
          description: Whether to source the asset details from the search index. If false, the details are read directly from the canonical store. Default is true.
        derived:
          type: boolean
          description: Whether to include the derived assets of this asset in the response. Default is true.
        versions:
          type: boolean
          description: Whether to include the backup versions of this asset in the response. Default is false.
      required:
        - public_id
        - resource_type
        - kind
      additionalProperties: true
    resource_internal_response:
      description: |
        The details of a single asset. Returns the standard asset fields, plus additional
        internal fields when accessed over the internal transport.
      allOf:
        - $ref: '#/components/schemas/info'
        - type: object
          additionalProperties: true
    admin_context_operation:
      type: object
      description: A single internal contextual-metadata operation.
      properties:
        name:
          type: string
          description: The context key to operate on.
        value:
          type: array
          description: The value(s) to apply for the context key.
          items:
            type: string
        type:
          type: string
          description: The value type of the context entry.
        op:
          type: string
          description: The operation to apply to the context key (for example, "+" to add or "-" to remove).
      required:
        - name
    resource_update_by_body_request:
      type: object
      description: |
        The asset identifiers plus the attributes to update. The identifying fields (public_id,
        resource_type, kind) are required; the remaining update fields are optional. Additional
        fields accepted by the asset update API are permitted.
      properties:
        public_id:
          type: string
          description: The public ID of the asset to update.
          example: sample
        resource_type:
          allOf:
            - $ref: '#/components/schemas/resource_type'
          description: The type of the asset (image, video, or raw).
          example: image
        kind:
          allOf:
            - $ref: '#/components/schemas/managed_delivery_type'
          description: The delivery type of the asset.
          example: upload
        tags:
          type: array
          description: The list of tags to assign to the asset, replacing any existing tags.
          items:
            type: string
        context:
          type: object
          additionalProperties: true
          description: The key-value pairs of contextual metadata to assign to the asset.
        metadata:
          type: object
          additionalProperties: true
          description: The structured metadata field values to assign to the asset.
        asset_folder:
          type: string
          description: The asset folder to move the asset into.
        display_name:
          type: string
          description: The display name to assign to the asset.
        moderation_status:
          type: string
          enum:
            - pending
            - approved
            - rejected
          description: The moderation status to set on the asset.
        admin_context:
          type: array
          description: |
            Internal-only contextual metadata operations applied with add/remove semantics. Each
            entry names a context key, the value(s) to apply, the value type, and the operation.
          items:
            $ref: '#/components/schemas/admin_context_operation'
        response_type:
          type: string
          description: The shape of the asset representation to return (for example, "public").
        skip_permission_check:
          type: boolean
          description: Whether to skip permission enforcement for the update. Internal use only. Default is false.
      required:
        - public_id
        - resource_type
        - kind
      additionalProperties: true
    resources_by_container_id_response:
      type: object
      description: A page of assets contained in a folder, with pagination metadata.
      properties:
        resources:
          type: array
          description: The assets contained in the folder.
          items:
            $ref: '#/components/schemas/resource_internal_response'
        total_count:
          type: integer
          description: The total number of assets in the folder.
        next_cursor:
          type: string
          description: A cursor for retrieving the next page of results, when more results are available.
      required:
        - resources
    eval_request:
      type: object
      description: |
        The eval expression and the upload parameters to evaluate it against. The `eval` field holds
        the dynamic expression; any other upload parameters may be supplied alongside it.
      properties:
        eval:
          type: string
          description: The dynamic eval expression to evaluate against the upload parameters.
          example: upload_options.quality_analysis = resource_info.quality_score * 100
        public_id:
          type: string
          description: The public ID of the asset the eval expression applies to.
      required:
        - eval
      additionalProperties: true
    eval_response:
      type: object
      description: The upload parameters resulting from evaluating the eval expression.
      additionalProperties: true
    search_parameters:
      type: object
      description: Common parameters for resource search operations.
      properties:
        expression:
          type: string
          description: |
            The Lucene-like search expression. Supports token match (`field:value`), exact match (`field=value`), trailing `*` for prefix match, ranges (`[a TO b]`, `{a TO b}`), and comparisons (`>`, `<`, `>=`, `<=`). Combine terms with uppercase `AND`, `OR`, `NOT`, or `+`/`-`, and group with parentheses. Wrap values containing reserved characters (spaces, colons, etc.) in double quotes. See the [search expressions guide](https://cloudinary.com/documentation/search_expressions.md) for the full syntax and supported fields.
          example: resource_type:image AND tags:kitten
          examples:
            - tags:shirt AND uploaded_at>1d
            - resource_type:image AND bytes>1000000 AND (format:png OR format:jpg)
            - folder:products AND context.category:electronics
            - tags:"service:mantels" AND -tags:discontinued
        sort_by:
          $ref: '#/components/schemas/search_sort_by'
        max_results:
          type: integer
          minimum: 0
          maximum: 500
          description: |
            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.
          example: 30
        next_cursor:
          type: string
          description: The cursor value to get the next page of results. Available when a previous search returned more results than max_results.
        aggregate:
          description: |
            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.
          oneOf:
            - type: array
              items:
                type: string
                enum:
                  - format
                  - resource_type
                  - type
              description: The fields to aggregate results by. Simple aggregation by field name.
              example:
                - format
                - resource_type
            - type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - bytes
                      - image_pixels
                      - video_pixels
                      - duration
                  ranges:
                    type: array
                    description: |
                      One or more ranges for the numeric field. Each range must include a `key` label and at least one of `from` / `to`.
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          minLength: 1
                          maxLength: 20
                          pattern: ^[a-zA-Z0-9_-]+$
                          description: A label for the bucket, returned in the aggregation response. 1–20 chars, alphanumeric plus `-` and `_`.
                          example: small
                        from:
                          type: number
                          description: Start of the range (inclusive). At least one of `from` / `to` is required.
                        to:
                          type: number
                          description: End of the range (exclusive). At least one of `from` / `to` is required.
                      required:
                        - key
                required:
                  - type
                  - ranges
              description: Range-based aggregations for numeric fields
              example:
                - type: bytes
                  ranges:
                    - key: small
                      from: 0
                      to: 10000
                    - key: medium
                      from: 10000
                      to: 100000
        with_field:
          type: array
          items:
            type: string
            enum:
              - context
              - tags
              - image_metadata
              - image_analysis
              - metadata
              - quality_analysis
              - accessibility_analysis
            x-enum-descriptions:
              - Includes the `context` key-value pairs attached to each asset.
              - Includes the list of `tags` attached to each asset.
              - Includes embedded metadata extracted from the asset file (EXIF, IPTC, XMP under `image_metadata`). Tier 2 feature.
              - Includes analysis results such as `colors`, `face_count`, `illustration_score`, and `grayscale` under `image_analysis`. Tier 2 feature.
              - Includes values of structured metadata fields under `metadata`. Tier 2 feature.
              - Includes `quality_analysis.*` scores for assets analyzed at upload time.
              - Includes `accessibility_analysis.*` scores for assets analyzed at upload time.
          description: |
            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.
          example:
            - tags
            - context
        fields:
          type: string
          description: |
            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.
          example: tags,context,metadata
    context_response:
      type:
        - object
        - 'null'
      additionalProperties:
        type: string
      description: Contextual metadata as flat key-value pairs.
    search_response:
      type: object
      description: The response object returned by search operations.
      properties:
        total_count:
          type: integer
          description: The total number of resources matching the search criteria.
          example: 42
        time:
          type: integer
          description: The time taken to execute the search query in milliseconds.
          example: 42
        resources:
          type: array
          description: The list of resources matching the search criteria. Can be empty if no results found.
          items:
            type: object
            description: Resource fields that can be returned. All fields are optional and can be filtered using the fields parameter.
            properties:
              asset_id:
                type: string
                description: The unique identifier of the asset.
                example: 09169cf604b03521789d1b3b8cca53d1
              public_id:
                type: string
                description: The public identifier that is used to build the URL.
                example: blue_sweater
              asset_folder:
                type: string
                description: The folder where the asset is stored.
                example: Clothing Sale
              filename:
                type: string
                description: The original filename of the asset.
                example: blue_sweater
              display_name:
                type: string
                description: The display name of the asset.
                example: blue_sweater
              format:
                type:
                  - string
                  - 'null'
                description: The format of the asset. Null for raw assets, which have no format.
                example: jpg
              version:
                type: integer
                description: The version number of the asset.
                example: 1719316754
              resource_type:
                type: string
                description: The type of resource.
                enum:
                  - image
                  - video
                  - raw
                example: image
              type:
                $ref: '#/components/schemas/delivery_type_all'
              created_at:
                type: string
                format: date-time
                description: The timestamp when the asset was created.
                example: '2024-06-25T11:59:14+00:00'
              uploaded_at:
                type: string
                format: date-time
                description: The timestamp when the asset was uploaded.
                example: '2024-06-25T11:59:14+00:00'
              bytes:
                type: integer
                description: The size of the asset in bytes.
                example: 71063
              backup_bytes:
                type: integer
                description: The size of the backup asset in bytes.
                example: 71063
              width:
                type:
                  - integer
                  - 'null'
                description: The width of the asset in pixels. Null for non-visual assets (e.g. raw, audio).
                example: 4800
              height:
                type:
                  - integer
                  - 'null'
                description: The height of the asset in pixels. Null for non-visual assets (e.g. raw, audio).
                example: 6400
              aspect_ratio:
                type:
                  - number
                  - 'null'
                format: float
                description: The aspect ratio of the asset (width/height). Null for non-visual assets (e.g. raw, audio).
                example: 0.75
              pixels:
                type:
                  - integer
                  - 'null'
                description: The total number of pixels in the asset. Null for non-visual assets (e.g. raw, audio).
                example: 307200
              url:
                type: string
                format: uri
                description: The HTTP URL for accessing the asset.
                example: http://res.cloudinary.com/demo/image/upload/v1719316754/blue_sweater.jpg
              secure_url:
                type: string
                format: uri
                description: The HTTPS URL for accessing the asset.
                example: https://res.cloudinary.com/demo/image/upload/v1719316754/blue_sweater.jpg
              status:
                type: string
                description: The current status of the asset.
                enum:
                  - active
                  - inactive
                  - deleted
                  - pending
                example: active
              access_mode:
                type:
                  - string
                  - 'null'
                description: The access mode of the asset. Null when not explicitly set.
                enum:
                  - public
                  - authenticated
                  - 
                example: public
              access_control:
                anyOf:
                  - $ref: '#/components/schemas/access_control'
                  - type: 'null'
                description: The access control settings for the asset.
                example:
              etag:
                type: string
                description: The ETag of the asset.
                example: 7242da7b353e7da2c3eb8c006165b385
              created_by:
                type:
                  - object
                  - 'null'
                description: Information about who created the asset.
                properties:
                  access_key:
                    type: string
                    description: The access key of the user who created the asset.
                    example: '614335564976464'
              uploaded_by:
                type:
                  - object
                  - 'null'
                description: Information about who uploaded the asset.
                properties:
                  access_key:
                    type: string
                    description: The access key of the user who uploaded the asset.
                    example: '614335564976464'
              context:
                allOf:
                  - $ref: '#/components/schemas/context_response'
                description: Custom context metadata associated with the asset.
              tags:
                allOf:
                  - $ref: '#/components/schemas/tags_response'
                description: Tags associated with the asset.
              image_metadata:
                type:
                  - object
                  - 'null'
                description: Technical metadata extracted from the image.
              image_analysis:
                type:
                  - object
                  - 'null'
                description: Results of image analysis.
              metadata:
                type:
                  - object
                  - 'null'
                description: Structured metadata associated with the asset.
              quality_analysis:
                type:
                  - object
                  - 'null'
                description: Results of quality analysis.
              accessibility_analysis:
                type:
                  - object
                  - 'null'
                description: Results of accessibility analysis.
        next_cursor:
          type:
            - string
            - 'null'
          description: A cursor for pagination. Only included when there are more results available.
          example: e4d03a236b27e306e56719f74d05cdef
        aggregations:
          type: object
          description: Aggregation results when the aggregate parameter is used in the request. Only included when aggregations are requested.
          properties:
            values:
              type: array
              description: Array of aggregation values when using simple aggregation (e.g., by format, resource_type, etc.)
              items:
                type: object
                properties:
                  value:
                    type: string
                    description: The value being aggregated
                    example: jpg
                  count:
                    type: integer
                    description: The count of resources with this value
                    example: 42
            ranges:
              type: array
              description: Array of range-based aggregation results when using range aggregation (e.g., bytes, width, height, etc.)
              items:
                type: object
                properties:
                  from:
                    type: number
                    description: Start of the range (inclusive)
                    example: 0
                  to:
                    type: number
                    description: End of the range (exclusive)
                    example: 1048576
                  count:
                    type: integer
                    description: The count of resources within this range
                    example: 17
    visual_search_parameters:
      description: Parameters for visual search operations
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - image_url
          properties:
            image_url:
              type: string
              format: uri
              description: The URL of an image to use as the source for finding visually similar images
              example: https://res.cloudinary.com/demo/image/upload/sample.jpg
            threshold:
              type: number
              minimum: 0
              maximum: 1
              description: The minimum similarity score (between 0 and 1.0) that a resource must have to be included in the response
              example: 0.8
        - type: object
          additionalProperties: false
          required:
            - image_asset_id
          properties:
            image_asset_id:
              type: string
              description: The asset ID of an existing image to use as the source for finding visually similar images
              example: 09169cf604b03521789d1b3b8cca53d1
            threshold:
              type: number
              minimum: 0
              maximum: 1
              description: The minimum similarity score (between 0 and 1.0) that a resource must have to be included in the response
              example: 0.8
        - type: object
          additionalProperties: false
          required:
            - text
          properties:
            text:
              type: string
              description: A textual description to find visually similar images
              example: shirts
            threshold:
              type: number
              minimum: 0
              maximum: 1
              description: The minimum similarity score (between 0 and 1.0) that a resource must have to be included in the response
              example: 0.8
    initial_backup_status_enum:
      type: string
      enum:
        - pending
        - active
        - completed
        - failed
      description: The current status of the initial backup operation.
    initial_backup_summary:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the initial backup operation.
          example: abc123def456
        status:
          $ref: '#/components/schemas/initial_backup_status_enum'
        created_at:
          type: string
          format: date-time
          description: The date and time when the initial backup operation was created.
          example: '2024-05-07T10:00:00Z'
      required:
        - id
        - status
        - created_at
    initial_backup_list_response:
      type: object
      properties:
        initial_backups:
          type: array
          items:
            $ref: '#/components/schemas/initial_backup_summary'
          description: The list of initial backup operations.
        next_cursor:
          type: string
          description: Cursor for the next page of results. Present only when more results are available.
      required:
        - initial_backups
    initial_backup_create_request:
      type: object
      properties:
        email:
          type: string
          format: email
          description: An optional email address to notify when the initial backup completes.
          example: user@example.com
    initial_backup_create_response:
      type: object
      properties:
        ok:
          type: boolean
          description: Indicates that the initial backup was queued successfully.
          example: true
      required:
        - ok
    initial_backup_progress_response:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/initial_backup_status_enum'
        start_time:
          type: string
          format: date-time
          description: The date and time when the initial backup operation started.
          example: '2024-05-07T10:00:00Z'
        completion_time:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when the initial backup operation completed. Null while the operation is still running.
          example: '2024-05-07T11:00:00Z'
        processed_assets_count:
          type:
            - integer
            - 'null'
          description: The number of assets processed so far. Null when progress cannot be determined.
          example: 42
        reason:
          type: string
          enum:
            - elasticsearch_not_enabled
            - no_results_from_search
            - no_assets_were_processed
          description: A reason code explaining why progress is unavailable. Present only when processed_assets_count is null.
          example: elasticsearch_not_enabled
      required:
        - status
        - start_time
    person_status:
      type: string
      description: The status of a person.
      enum:
        - active
        - hidden
    thumbnail:
      type: object
      description: The thumbnail image for a person.
      properties:
        asset_id:
          type: string
          description: The external ID of the asset used for the thumbnail.
          example: 2262b0b5eb88f1fd7724e29b0e57d730
        bounding_box:
          type: array
          description: The bounding box coordinates [x, y, width, height] of the face in the asset.
          items:
            type: integer
          minItems: 4
          maxItems: 4
          example:
            - 10
            - 20
            - 100
            - 150
        url:
          type: string
          format: uri
          description: The secure URL of the thumbnail asset.
          example: https://res.cloudinary.com/demo/image/upload/v1234567890/sample.jpg
        resource_type:
          type: string
          description: The resource type of the asset.
          example: image
        type:
          type: string
          description: The kind/type of the asset.
          example: upload
        public_id:
          type: string
          description: The public ID of the asset.
          example: sample
        version:
          type: integer
          description: The version number of the asset.
          example: 1234567890
    person_details:
      type: object
      description: Detailed information about a recognized person.
      properties:
        id:
          type: string
          description: The unique identifier of the person.
          example: a1b2c3d4e5f6
        name:
          type: string
          description: The display name of the person, or null if not named.
          example: Jane Doe
        status:
          $ref: '#/components/schemas/person_status'
          example: active
        thumbnail:
          $ref: '#/components/schemas/thumbnail'
        created_at:
          type: string
          format: date-time
          description: The date and time when the person was first detected.
          example: '2025-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: The date and time when the person was last updated.
          example: '2025-01-20T14:45:00Z'
    people_list_response:
      type: object
      properties:
        people:
          type: array
          description: A list of recognized person objects.
          items:
            $ref: '#/components/schemas/person_details'
        next_cursor:
          type: string
          description: The cursor to use for the next page of results.
    person_response:
      type: object
      properties:
        person:
          $ref: '#/components/schemas/person_details'
    update_person_request:
      type: object
      properties:
        name:
          type: string
          description: The display name for the person. Maximum 255 characters.
          maxLength: 255
          example: Jane Doe
        status:
          $ref: '#/components/schemas/person_status'
        thumbnail_asset_id:
          type: string
          description: The external ID of an asset containing this person's face to use as the thumbnail.
          example: 2262b0b5eb88f1fd7724e29b0e57d730
    update_person_response:
      type: object
      properties:
        person_id:
          type: string
          description: The unique identifier of the person.
          example: f10f893da5a1586dca6764b22514aa0d25e6b867baffc4fb43a2318a25d8e5b2
        name:
          type: string
          description: The display name of the person.
          example: Jane Doe
        status:
          $ref: '#/components/schemas/person_status'
    people_inspection_group:
      type: object
      description: The items to inspect for a type and the actions to check against them.
      properties:
        items:
          type: object
          additionalProperties: true
          description: A map of caller-supplied cache keys to the person identifier to inspect.
        actions:
          type: object
          additionalProperties: true
          description: A map of action names to optional action context to inspect.
      required:
        - items
        - actions
    people_inspection_targets:
      type: object
      description: A map of inspectable types to the items and actions to inspect.
      properties:
        Person:
          $ref: '#/components/schemas/people_inspection_group'
      additionalProperties: true
    people_inspect_request:
      type: object
      description: The people and actions to inspect.
      properties:
        inspections:
          $ref: '#/components/schemas/people_inspection_targets'
      required:
        - inspections
    people_inspect_response:
      type: object
      description: The permission inspection results.
      properties:
        message:
          type: string
          description: A status message for the inspection request.
          example: ok
        inspections:
          type: object
          additionalProperties: true
          description: A map of inspected type to per-item, per-action permission results (true if permitted).
      required:
        - inspections
    GenerateImageRequest:
      type: object
      description: |
        Parameters for an image-generation request. Only `prompt` is required;
        all other fields fall back to documented defaults.
      required:
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 16384
          description: The text description of the image to generate.
          examples:
            - A photorealistic sunset over a mountain lake
        model:
          $ref: "#/components/schemas/ModelSelection"
        image_size:
          $ref: "#/components/schemas/ImageSize"
        format:
          $ref: "#/components/schemas/ImageFormat"
        target:
          $ref: "#/components/schemas/Target"
        seed:
          $ref: "#/components/schemas/Seed"
        async:
          $ref: "#/components/schemas/Async"
        notification_url:
          $ref: "#/components/schemas/NotificationUrl"
    ImageFormat:
      type: string
      enum:
        - jpeg
        - png
        - webp
      description: |
        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).
      examples:
        - png
    Seed:
      type:
        - integer
        - "null"
      minimum: 0
      description: |
        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.
      examples:
        - 42
    Async:
      type: boolean
      default: false
      description: |
        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.
    NotificationUrl:
      type: string
      format: uri
      description: The webhook URL to notify when the generation is complete. Only relevant when `async` is set to true.
      examples:
        - https://path.to/webhook
    ImageToImageRequest:
      type: object
      description: |
        Parameters for an image-to-image (reference-guided) request. Both
        `prompt` (the edit instruction) and `reference_images` are required; all
        other fields fall back to the same defaults as `text_to_image`.
      required:
        - prompt
        - reference_images
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 16384
          description: The text instruction describing the desired edit / output.
          examples:
            - Place the product from [1] on a marble kitchen counter, soft morning light
        reference_images:
          type: array
          minItems: 1
          maxItems: 4
          description: |
            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.
          items:
            $ref: "#/components/schemas/ReferenceImage"
        model:
          $ref: "#/components/schemas/ModelSelection"
        image_size:
          $ref: "#/components/schemas/ImageSize"
        format:
          $ref: "#/components/schemas/ImageFormat"
        target:
          $ref: "#/components/schemas/Target"
        seed:
          $ref: "#/components/schemas/Seed"
        async:
          $ref: "#/components/schemas/Async"
        notification_url:
          $ref: "#/components/schemas/NotificationUrl"
    ReferenceImage:
      description: |
        A single reference image, in **one** of two mutually exclusive forms
        determined by `source_type`:
          * `ManagedAssetReference`: a managed asset in the caller's product
            environment, by `asset_id` (read permission is checked).
          * `UrlReference`: an external image by HTTPS `url`.
      oneOf:
        - $ref: "#/components/schemas/ManagedAssetReference"
        - $ref: "#/components/schemas/UrlReference"
      discriminator:
        propertyName: source_type
        mapping:
          managed_asset: "#/components/schemas/ManagedAssetReference"
          url: "#/components/schemas/UrlReference"
    ManagedAssetReference:
      type: object
      title: ManagedAssetReference
      description: |
        A reference to a managed asset in the caller's product environment, by
        asset ID.
      additionalProperties: false
      required:
        - source_type
        - asset_id
      properties:
        source_type:
          type: string
          description: Discriminator identifying this as a managed-asset reference.
          enum:
            - managed_asset
        asset_id:
          type: string
          description: Cloudinary asset ID of the reference image. READ permission is enforced.
          examples:
            - 0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a
    UrlReference:
      type: object
      title: UrlReference
      description: A reference to an external image by HTTPS URL.
      additionalProperties: false
      required:
        - source_type
        - url
      properties:
        source_type:
          type: string
          description: Discriminator identifying this as an external-URL reference.
          enum:
            - url
        url:
          type: string
          format: uri
          description: HTTPS URL of the reference image.
          examples:
            - https://example.com/product.png
    ModelSelection:
      description: |
        Selects the model, in one of three mutually exclusive forms (omit to use
        the global default):
          * `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`).
      oneOf:
        - $ref: "#/components/schemas/ModelByFamily"
        - $ref: "#/components/schemas/ModelById"
        - $ref: "#/components/schemas/ModelAuto"
    ModelByFamily:
      type: object
      title: ModelByFamily
      description: |
        Select a model by family and quality tier; a missing `tier` defaults to
        `standard`.
      additionalProperties: false
      required:
        - family
      properties:
        family:
          type: string
          enum:
            - flux
            - recraft
            - gpt-image
            - nano-banana
            - ideogram
          description: >
            Model family:

            * `flux`: Photorealistic images (FLUX.2 Klein 9B / FLUX.2 Pro).

            * `recraft`: Vector and illustration (Recraft V3 / Recraft V4).

            * `gpt-image`: Campaign and marketing images (GPT Image 1 Mini / GPT
            Image 2).

            * `nano-banana`: General purpose generation (Nano Banana 1 / Nano
            Banana 2).

            * `ideogram`: Realism, text rendering, and artistic generation
            (Ideogram V4).
          examples:
            - flux
        tier:
          type: string
          enum:
            - standard
            - premium
          description: Quality tier within the family. Defaults to `standard` when omitted.
          examples:
            - premium
    ModelById:
      type: object
      title: ModelById
      description: Pin an exact model by ID, bypassing family/tier.
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          enum:
            - nano-banana-1
            - nano-banana-2
            - nano-banana-2-lite
            - flux-2-klein-9b
            - flux-2-pro
            - flux-2-flash
            - recraft-v3
            - recraft-v4
            - gpt-image-1-mini
            - gpt-image-2
            - gpt-image-2.5-flare
            - gpt-image-2.5-sunburst
            - muse-image
            - mai-image-2.5
            - mai-image-2.5-pro
            - seedream-5-pro
            - grok-imagine-image
            - recraft-v4.1-utility
            - recraft-v4.1-utility-pro
            - seedream-5-lite
            - grok-imagine-image-2.0-low
            - qwen-image-3
            - ideogram-v4-base
            - ideogram-v4-turbo
            - nano-banana-1-edit
            - nano-banana-2-edit
            - nano-banana-2-lite-edit
            - flux-2-klein-9b-edit
            - flux-2-pro-edit
            - flux-2-flash-edit
            - recraft-v3-edit
            - gpt-image-1-mini-edit
            - gpt-image-2-edit
            - gpt-image-2.5-flare-edit
            - gpt-image-2.5-sunburst-edit
            - muse-image-edit
            - mai-image-2.5-edit
            - mai-image-2.5-pro-edit
            - seedream-5-pro-edit
            - grok-imagine-image-edit
            - seedream-5-lite-edit
            - grok-imagine-image-2.0-low-edit
            - qwen-image-3-edit
          description: |
            Exact model identifier; overrides family/tier when provided. The
            `-edit` models accept reference images and are selectable only on
            `image_to_image`; the others only on `text_to_image`.
          examples:
            - flux-2-pro
    ModelAuto:
      type: object
      title: ModelAuto
      description: |
        Let the service choose the model for this request. The response reports
        the resolved model in `data.assets[].model`, as for the other forms; on
        `image_to_image` it is always an edit model.
      additionalProperties: false
      required:
        - mode
      properties:
        mode:
          type: string
          enum:
            - auto
          description: The only valid value; selects automatic model selection.
          examples:
            - auto
        preference:
          type: string
          enum:
            - balanced
            - quality
            - economy
            - balanced_fast
            - quality_fast
            - economy_fast
          default: balanced
          description: >
            What the choice optimizes for:

            * `balanced` (default): quality and cost weighted equally.

            * `quality`: quality only; cost isn't weighed.

            * `economy`: cost first, quality second.

            * `balanced_fast`, `quality_fast`, `economy_fast`: as above, but
            also
              favor faster generation, and never pick a model that typically
              takes longer than 30 seconds.
          examples:
            - quality
    ImageSize:
      description: |
        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.
      oneOf:
        - $ref: "#/components/schemas/DimensionsImageSize"
        - $ref: "#/components/schemas/DeclarativeImageSize"
    DimensionsImageSize:
      type: object
      title: DimensionsImageSize
      description: Exact output dimensions in pixels. Both `width` and `height` are required together.
      additionalProperties: false
      required:
        - width
        - height
      properties:
        width:
          type: integer
          minimum: 64
          maximum: 4096
          description: Output width in pixels.
          examples:
            - 1280
        height:
          type: integer
          minimum: 64
          maximum: 4096
          description: Output height in pixels.
          examples:
            - 720
    DeclarativeImageSize:
      type: object
      title: DeclarativeImageSize
      description: |
        Declarative output size — an aspect ratio plus an optional resolution
        tier, resolved server-side to the nearest size the model supports.
      additionalProperties: false
      required:
        - aspect_ratio
      properties:
        aspect_ratio:
          type: string
          description: |
            Output aspect ratio, width-to-height. Limited to the core ratios
            every model supports natively.
          enum:
            - 1:1
            - 16:9
            - 9:16
            - 4:3
            - 3:4
          examples:
            - 16:9
        resolution:
          type: string
          description: |
            Output resolution tier, measured on the longest edge. Defaults to
            `1K` when omitted.
            * `0.5K`: ~512 px
            * `1K`: ~1024 px
            * `2K`: ~2048 px
            * `4K`: ~4096 px
          enum:
            - 0.5K
            - 1K
            - 2K
            - 4K
          examples:
            - 2K
    Target:
      description: |
        Where to store the generated output, determined by `target_type`.
        Optional; defaults to a `managed_asset` target when omitted.
      oneOf:
        - $ref: "#/components/schemas/ManagedAssetTarget"
        - $ref: "#/components/schemas/TemporaryTarget"
      discriminator:
        propertyName: target_type
        mapping:
          managed_asset: "#/components/schemas/ManagedAssetTarget"
          temporary: "#/components/schemas/TemporaryTarget"
    ManagedAssetTarget:
      type: object
      description: Store the output as a permanent managed asset in your Cloudinary product environment (the default).
      additionalProperties: false
      required:
        - target_type
      properties:
        target_type:
          type: string
          description: Discriminator identifying this as a managed-asset target.
          enum:
            - managed_asset
        public_id:
          type: string
          description: Public ID to store the asset under. Auto-assigned when omitted.
          examples:
            - my-public-id
        upload_preset:
          type: string
          description: Upload preset to apply. Uses the product environment's default when omitted.
          examples:
            - some-preset
    TemporaryTarget:
      type: object
      description: Store the output as a short-lived asset on the upload service.
      additionalProperties: false
      required:
        - target_type
      properties:
        target_type:
          type: string
          description: Discriminator identifying this as a temporary target.
          enum:
            - temporary
    Storage:
      description: |
        Where a generated asset is stored — mirrors the request `target`,
        determined by `storage_type`. `secure_url` is always present.
      oneOf:
        - $ref: "#/components/schemas/ManagedAssetStorage"
        - $ref: "#/components/schemas/TemporaryStorage"
      discriminator:
        propertyName: storage_type
        mapping:
          managed_asset: "#/components/schemas/ManagedAssetStorage"
          temporary: "#/components/schemas/TemporaryStorage"
    ManagedAssetStorage:
      type: object
      description: |
        A generated asset stored as a permanent managed asset. Reference it in
        other Cloudinary APIs by `asset_id`, or by the
        `resource_type` / `type` / `public_id` triple.
      additionalProperties: false
      required:
        - storage_type
        - secure_url
        - public_id
        - resource_type
        - type
        - version
      properties:
        storage_type:
          type: string
          description: Discriminator identifying this as managed-asset storage.
          enum:
            - managed_asset
        secure_url:
          type: string
          format: uri
          description: The URL to fetch the generated asset.
          examples:
            - https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png
        asset_id:
          type: string
          description: Cloudinary asset ID — a stable, globally-unique reference to the asset.
          examples:
            - 0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a
        public_id:
          type: string
          description: Public ID of the stored asset.
          examples:
            - my-public-id
        resource_type:
          type: string
          description: Cloudinary resource type of the stored asset.
          enum:
            - image
            - video
            - raw
          examples:
            - image
        type:
          type: string
          description: Cloudinary delivery type of the stored asset (e.g. `upload`, `private`, `authenticated`).
          examples:
            - upload
        version:
          type: integer
          format: int64
          description: Version of the stored asset.
    TemporaryStorage:
      type: object
      description: A generated asset stored as a short-lived asset on the upload service.
      additionalProperties: false
      required:
        - storage_type
        - secure_url
        - expires_at
      properties:
        storage_type:
          type: string
          description: Discriminator identifying this as temporary storage.
          enum:
            - temporary
        secure_url:
          type: string
          format: uri
          description: The URL to fetch the generated asset.
          examples:
            - https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream
        expires_at:
          type: string
          format: date-time
          description: Time in UTC when secure_url stops being valid.
          examples:
            - 2026-06-25T12:50:26Z
    GenerateImageResult:
      type: object
      description: Successful synchronous image-generation response.
      required:
        - request_id
      properties:
        data:
          $ref: "#/components/schemas/GeneratedAssets"
        limits:
          $ref: "#/components/schemas/Limits"
        notices:
          $ref: "#/components/schemas/Notices"
        request_id:
          type: string
          description: Unique identifier for this request, for correlation and support.
          examples:
            - 17c3b70c5096df0e77e838323abb7029
    GeneratedAssets:
      type: object
      description: Wrapper holding the array of generated assets.
      required:
        - assets
      properties:
        assets:
          type: array
          description: The generated assets. Currently a single asset is returned.
          items:
            $ref: "#/components/schemas/GeneratedAsset"
    GeneratedAsset:
      type: object
      description: |
        A generated asset: where it is stored (`storage`) plus its media
        metadata. The media fields are populated once the task completes; an
        in-progress asset carries only `storage`.
      required:
        - storage
      properties:
        storage:
          $ref: "#/components/schemas/Storage"
        format:
          type: string
          enum:
            - png
            - jpeg
            - webp
          description: The image format of the stored asset.
          examples:
            - png
        width:
          type: integer
          description: The width of the generated image in pixels; zero if the model doesn't provide dimensions.
          examples:
            - 1024
        height:
          type: integer
          description: The height of the generated image in pixels; zero if the model doesn't provide dimensions.
          examples:
            - 768
        bytes:
          type: integer
          format: int64
          description: The size of the generated image in bytes.
          examples:
            - 2048576
        model:
          $ref: "#/components/schemas/Model"
        seed:
          type:
            - integer
            - "null"
          description: >
            The seed used for generation. Echoes input or returns the
            model-generated seed.

            Null when the model doesn't support seeds.
          examples:
            - 42
        created_at:
          type: string
          format: date-time
          description: The timestamp when the image was generated.
          examples:
            - 2026-04-21T14:30:00Z
    Model:
      type: object
      description: Identifies the model that produced a generation result.
      required:
        - family
        - tier
        - id
      properties:
        family:
          type: string
          description: |
            The family this model belongs to. `none` when the model is not part
            of any family.

            A family holds exactly two tiers (`standard` and `premium`), so the
            family/tier taxonomy names only part of the roster. The remaining
            models are selected by `id` alone and are not part of any family,
            which is reported as `none` rather than as a family the model does
            not belong to. This describes the model, not how it was selected: a
            model that belongs to a family reports it whether it was chosen by
            `family` and `tier` or pinned by `id`.

            Not an enum: new families are added over time, so treat any value
            as possible.
          examples:
            - flux
        tier:
          type: string
          description: |
            The quality tier this model holds within its family. `none` when
            the model is not part of any family. See `family`.
          examples:
            - premium
        id:
          type: string
          description: |
            The exact model identifier used for generation. Always a concrete
            model, and the reliable field to key on: unlike `family` and
            `tier`, it is never `none`.
          examples:
            - flux-2-pro
    TaskStatus:
      type: string
      description: |
        The status of an async generation task.
        * `pending`: accepted and queued, not yet started.
        * `processing`: generation is in progress.
        * `completed`: generation finished; `result` is populated.
        * `failed`: generation did not complete successfully.
      enum:
        - pending
        - processing
        - completed
        - failed
    Task:
      type: object
      description: |
        An async generation task. Returned when a generation is accepted (202)
        and from GET /tasks/{task_id} as it progresses. The `result` is filled
        in once `status` is `completed`.
      required:
        - task_id
        - status
      properties:
        task_id:
          type: string
          description: Identifier for the async generation task. Use it to poll `GET /generate/{cloud_name}/tasks/{task_id}`.
          examples:
            - 053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
        status:
          $ref: "#/components/schemas/TaskStatus"
        result:
          type:
            - object
            - "null"
          allOf:
            - $ref: "#/components/schemas/GeneratedAssets"
          description: |
            The generated assets. Populated once `status` is `completed`.
        limits:
          $ref: "#/components/schemas/Limits"
    TaskResponse:
      type: object
      description: |
        Envelope for an async generation task — returned by the accepted (202)
        response and by GET /tasks/{task_id}.
      required:
        - request_id
      properties:
        data:
          $ref: "#/components/schemas/Task"
        notices:
          $ref: "#/components/schemas/Notices"
        request_id:
          type: string
          description: Unique identifier for this request, for correlation and support.
          examples:
            - 17c3b70c5096df0e77e838323abb7029
      examples:
        - data:
            task_id: 053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
            status: pending
          request_id: 17c3b70c5096df0e77e838323abb7029
    ErrorResponse:
      type: object
      description: Wrapper for error responses; includes the error object and a request_id for correlation.
      required:
        - error
        - request_id
      properties:
        error:
          $ref: "#/components/schemas/Error"
        notices:
          $ref: "#/components/schemas/Notices"
        request_id:
          type: string
          description: Unique identifier for this request, for correlation and support.
          examples:
            - 17c3b70c5096df0e77e838323abb7029
    Error:
      type: object
      description: Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.
      properties:
        category:
          $ref: "#/components/schemas/ErrorCategory"
        code:
          type: string
          description: Stable, machine-readable error code for programmatic handling.
          examples:
            - MG_00001
        message:
          type: string
          description: Human-readable description of what went wrong.
          examples:
            - missing parameters
        details:
          type: object
          description: Additional structured context about the error, when available.
          examples:
            - parameters:
                - prompt
      examples:
        - category: user_error
          code: MG_00001
          message: missing parameters
          details:
            parameters:
              - param1
              - param2
    ErrorCategory:
      type: string
      description: >
        Coarse classification of an error, primarily used by clients to decide
        whether to retry.

        * `user_error`: the request was invalid; do not retry without changes.

        * `auth_error`: authentication or authorization failed.

        * `server_error`: an unexpected server-side error; retrying may succeed.

        * `rate_limit_error`: quota or rate limit exceeded; retry later.
      enum:
        - user_error
        - auth_error
        - server_error
        - rate_limit_error
    Notices:
      type: array
      x-experimental: true
      description: |
        Tips and guidance attached to the response to help you get the most
        out of the generation. Each entry is plain text you can show to a
        user or act on as-is. Omitted when there is nothing to add.
      items:
        $ref: "#/components/schemas/Notice"
      examples:
        -   - severity: warning
              text: "You've used 40 of your 50 Image Generation credits. 10 remain. Tell the user the balance is nearly spent, do not estimate how many images it covers, and show them: https://console.cloudinary.com/app/image/generation/plans"
    Notice:
      type: object
      required:
        - severity
        - text
      properties:
        severity:
          type: string
          description: >
            How much weight to give the message.

            * `info`: for awareness; nothing to do.

            * `warning`: worth relaying to the user before continuing.

            * `blocking`: the request was not served; the text says what
            unblocks it.
          enum:
            - info
            - warning
            - blocking
        text:
          type: string
          description: The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.
          examples:
            - This model does not output webp; the image was stored as png. Deliver it with f_auto or f_webp to get webp.
    Limits:
      type: object
      description: Rate limit information for the account's add-on quotas.
      properties:
        addons_quota:
          type: array
          description: Per-add-on quota usage for this account.
          items:
            $ref: "#/components/schemas/AddonQuota"
          examples:
            -   - type: image_generation
                  used_by_request: 1
                  remaining: 48
                  limit: 50
    AddonQuota:
      type: object
      description: Quota usage for a single add-on.
      required:
        - type
        - used_by_request
        - remaining
        - limit
      properties:
        type:
          $ref: "#/components/schemas/Feature"
        used_by_request:
          type:
            - integer
            - "null"
          description: Number of generations consumed by this request.
        remaining:
          type:
            - integer
            - "null"
          description: Generations remaining in the current period.
        limit:
          type:
            - integer
            - "null"
          description: Maximum generations allowed per period.
    Feature:
      type: string
      description: The add-on a quota applies to.
      enum:
        - image_generation
  requestBodies:
    upload_request_body:
      description: The file to upload and associated parameters.
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/binary_upload_request'
        application/json:
          schema:
            $ref: '#/components/schemas/upload_request'
  examples:
    RestoreResourcesFullRestoreExample:
      summary: Successful restore of multiple assets
      value:
        2262b0b5eb88f1fd7724e29b0e57d730:
          asset_id: 2262b0b5eb88f1fd7724e29b0e57d730
          public_id: sample
          format: jpg
          version: 1750590339
          version_id: da744ebcc95851cbbcecaef52e2246f5
          resource_type: image
          type: upload
          created_at: '2017-08-04T12:33:24Z'
          bytes: 120253
          width: 864
          height: 576
          tags: []
          placeholder: false
          asset_folder: ''
        d23c0526e6feca2c343e40c2fce5231a:
          asset_id: d23c0526e6feca2c343e40c2fce5231a
          public_id: coffee
          format: jpg
          version: 1750590339
          version_id: da744ebcc95851cbbcecaef52e2246f5
          resource_type: image
          type: upload
          created_at: '2017-08-04T12:35:25Z'
          bytes: 85641
          width: 640
          height: 480
          tags: []
          placeholder: false
          asset_folder: ''
    RestoreResourcesPartialRestoreExample:
      summary: Mixed results with successful and failed restores
      value:
        2262b0b5eb88f1fd7724e29b0e57d730:
          asset_id: 2262b0b5eb88f1fd7724e29b0e57d730
          public_id: sample
          format: jpg
          version: 1750590339
          version_id: da744ebcc95851cbbcecaef52e2246f5
          resource_type: image
          type: upload
          created_at: '2017-08-04T12:33:24Z'
          bytes: 120253
          width: 864
          height: 576
          tags: []
          placeholder: false
          asset_folder: ''
        d23c0526e6feca2c343e40c2fce5231a:
          error: no_backup
        invalid_asset_id:
          error: failed
    RestoreResourcesFailedRestoreExample:
      summary: Failed to restore all assets
      value:
        d23c0526e6feca2c343e40c2fce5231a:
          error: no_backup
        f45e7890abc123def456:
          error: unauthorized
    ListResourcesResponseExample:
      summary: List resources response example
      value:
        resources:
          - asset_id: 03a5b92135161439031d3834c04bc31b
            public_id: sample
            format: jpg
            version: 1719304854
            resource_type: image
            type: upload
            created_at: '2021-06-25T08:40:54+00:00'
            bytes: 120253
            width: 864
            height: 576
            asset_folder: ''
            display_name: sample
            url: http://res.cloudinary.com/demo/image/upload/v1719304854/sample.jpg
            secure_url: https://res.cloudinary.com/demo/image/upload/v1719304854/sample.jpg
        next_cursor: e4c19d14efae368a0b1b856e2b7c9d625bd9be6c
        total_count: 1
    DeleteResourcesResponseExample:
      summary: Delete resources response example
      value:
        deleted:
          image1: deleted
          image2: deleted
        partial: false
    GetResourceResponseExample:
      summary: Get resource by asset ID response example
      value:
        asset_id: 03a5b92135161439031d3834c04bc31b
        public_id: sample
        format: jpg
        version: 1719304854
        resource_type: image
        type: upload
        created_at: '2021-06-25T08:40:54Z'
        bytes: 120253
        width: 864
        height: 576
        asset_folder: ''
        display_name: sample
        url: http://res.cloudinary.com/cld-docs/image/upload/v1719304854/sample.jpg
        secure_url: https://res.cloudinary.com/cld-docs/image/upload/v1719304854/sample.jpg
        tags:
          - flower
          - plant
          - nature
        context:
          custom:
            alt: sample flower
            caption: beautiful flower
        metadata:
          approval_status_0: status_new
          categories_0:
            - cat_mens_clothes
            - cat_shirts
            - qzaihnfnasrzba0qrdpr
          owner_0: Adam Adams
          product_id_0: 12345
          publish_date_0: '2022-02-17'
        last_updated:
          access_control_updated_at: '2022-10-13T03:49:21Z'
          context_updated_at: '2022-11-10T06:05:21Z'
          metadata_updated_at: '2022-10-14T06:40:13Z'
          public_id_updated_at: '2022-12-11T05:41:21Z'
          tags_updated_at: '2022-12-14T06:09:21Z'
          updated_at: '2022-12-14T06:09:21Z'
        next_cursor: 041a39fc10971b9eabd4993470f6bfaf
        derived:
          - transformation: c_fill,w_100,h_100
            format: jpg
            bytes: 7112
            id: 8267a869b62a93a59248f35d7f124c1f
            url: http://res.cloudinary.com/cld-docs/image/upload/c_fill,w_100,h_100/v1312461204/sample.jpg
            secure_url: https://res.cloudinary.com/cld-docs/image/upload/c_fill,w_100,h_100/v1312461204/sample.jpg
          - transformation: w_230,h_168,c_fit
            format: jpg
            bytes: 19173
            id: 383e22a57167445552a3cdc16f0a0c85
            url: http://res.cloudinary.com/cld-docs/image/upload/w_230,h_168,c_fit/v1312461204/sample.jpg
            secure_url: https://res.cloudinary.com/cld-docs/image/upload/w_230,h_168,c_fit/v1312461204/sample.jpg
        etag: 619dfd2901577eb4259f91a2c0e43dac
        faces:
          -   - 98
              - 74
              - 61
              - 83
          -   - 140
              - 130
              - 52
              - 71
        illustration_score: 0
        semi_transparent: false
        grayscale: false
        colors:
          -   - '#162E02'
              - 6.7
          -   - '#385B0C'
              - 6.3
          -   - '#F3285C'
              - 5
          -   - '#B3CB6E'
              - 5
          -   - '#688F1C'
              - 4.4
          -   - '#324D07'
              - 4.4
          -   - '#8EAA34'
              - 4.3
          -   - '#4F6D0D'
              - 4.2
          -   - '#789446'
              - 4.1
          -   - '#DF1327'
              - 3.9
          -   - '#A10B12'
              - 3.7
          -   - '#273804'
              - 3.4
          -   - '#0D1802'
              - 3.4
          -   - '#D5E191'
              - 3.2
          -   - '#646E20'
              - 3.1
          -   - '#94AF4D'
              - 2.9
          -   - '#FB54A9'
              - 2.8
          -   - '#48570B'
              - 2.7
          -   - '#ACC655'
              - 2.7
          -   - '#FCA2D9'
              - 2.7
          -   - '#63110A'
              - 2.6
          -   - '#E9B327'
              - 2.2
          -   - '#6D644D'
              - 2.1
          -   - '#6D8D12'
              - 2
          -   - '#8F9F27'
              - 1.9
          -   - '#C3573E'
              - 1.8
          -   - '#CFD76E'
              - 1.6
          -   - '#A0B058'
              - 1.6
          -   - '#FCD0E9'
              - 1.6
          -   - '#728F2D'
              - 1.4
          -   - '#F958A1'
              - 1.4
          -   - '#D1B694'
              - 1
        predominant:
          google:
            -   - yellow
                - 52.9
            -   - pink
                - 13.5
            -   - red
                - 12
            -   - black
                - 10.1
            -   - green
                - 6.3
        versions:
          - version_id: d214063097a43d1d1293db61a397f60f
            version: '1312461204'
            format: jpg
            size: 109669
            time: '2021-08-04T12:33:24+00:00'
            restorable: false
    UpdateResourceResponseExample:
      summary: Update resource response example
      value:
        asset_id: bc71d3cedb739ed931be3706e94c413a
        public_id: qdi8r768kj5tticu8keh
        format: jpg
        version: 1747134921
        resource_type: image
        type: upload
        created_at: '2025-05-13T11:15:21Z'
        bytes: 206960
        width: 400
        height: 300
        asset_folder: ''
        display_name: qdi8r768kj5tticu8keh
        url: http://res.cloudinary.com/cloud-name/image/upload/v1747134921/qdi8r768kj5tticu8keh.jpg
        secure_url: https://res.cloudinary.com/cloud-name/image/upload/v1747134921/qdi8r768kj5tticu8keh.jpg
        moderation_kind: manual
        moderation_status: approved
        moderation:
          - kind: manual
            status: approved
            updated_at: '2025-05-13T11:15:22Z'
    GenerateImageBasicExample:
      summary: Basic image generation
      description: Minimal request — only a prompt; falls back to the default model.
      value:
        prompt: A man with a hat
    GenerateImageDeclarativeSizeExample:
      summary: Declarative size (aspect ratio + resolution)
      description: |
        Portable size selection — the service resolves aspect_ratio + resolution
        to the nearest dimensions the chosen model supports.
      value:
        prompt: A photorealistic sunset over a mountain lake
        model:
          family: flux
          tier: premium
        image_size:
          aspect_ratio: 16:9
          resolution: 2K
        target:
          target_type: managed_asset
          public_id: my-public-id
          upload_preset: some-preset
        seed: 42
    GenerateImageDimensionsSizeExample:
      summary: Dimensions size (explicit pixels)
      description: Pixel-precise size selection via width + height.
      value:
        prompt: A photorealistic sunset over a mountain lake
        model:
          id: flux-2-pro
        image_size:
          width: 1280
          height: 720
        target:
          target_type: temporary
        seed: 42
    GenerateImageAsyncExample:
      summary: Async image generation
      description: |
        Request the generation be performed asynchronously. The API responds
        202 with a task_id; the caller polls /tasks/{task_id} or waits for
        the webhook.
      value:
        prompt: A futuristic city skyline at night
        model:
          family: gpt-image
          tier: premium
        async: true
        notification_url: https://path.to/webhook
    GenerateImageAutoModelExample:
      summary: Automatic model selection
      description: |
        Let the service choose the model for the prompt; `preference` says what
        the choice optimizes for (default `balanced`). The response echoes the
        model that was actually used.
      value:
        prompt: A photorealistic sunset over a mountain lake
        model:
          mode: auto
          preference: quality
        image_size:
          aspect_ratio: 16:9
          resolution: 2K
        target:
          target_type: temporary
        seed: 42
    ImageToImageBasicExample:
      summary: Basic image-to-image edit
      description: |
        Minimal request: an edit instruction and one reference image by HTTPS
        URL; falls back to the default edit model.
      value:
        prompt: Place the product from [1] on a marble kitchen counter, soft morning light
        reference_images:
          - source_type: url
            url: https://example.com/product.png
    ImageToImageFamilyModelExample:
      summary: Edit model by family and tier
      description: >
        Select the edit model by family (+ optional tier); the family resolves
        to

        that family's edit model, here `nano-banana-2-edit`.
      value:
        prompt: Restyle [1] as a watercolor painting, keep the composition
        reference_images:
          - source_type: managed_asset
            asset_id: 0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a
        model:
          family: nano-banana
          tier: premium
        image_size:
          aspect_ratio: 4:3
          resolution: 1K
        target:
          target_type: temporary
        seed: 42
    ImageToImageExplicitModelExample:
      summary: Edit model by ID
      description: |
        Pin one exact edit model by ID. Only `-edit` models are selectable on
        this endpoint.
      value:
        prompt: Replace the background of [1] with a bright studio backdrop
        reference_images:
          - source_type: url
            url: https://example.com/product.png
        model:
          id: flux-2-pro-edit
        image_size:
          width: 1280
          height: 720
        target:
          target_type: managed_asset
          public_id: my-public-id
          upload_preset: some-preset
        seed: 42
    ImageToImageAutoModelExample:
      summary: Automatic edit-model selection
      description: >
        Let the service choose the edit model for the reference images and the

        instruction; the resolved model in the response is always an `-edit`
        model.
      value:
        prompt: Make it look like a watercolor painting, keep the composition
        reference_images:
          - source_type: url
            url: https://example.com/photo.jpg
        model:
          mode: auto
        image_size:
          aspect_ratio: 4:3
          resolution: 1K
    GenerateImageSuccessExample:
      summary: Successful synchronous generation
      description: The 200 response body returned for a completed sync generation.
      value:
        data:
          assets:
            - storage:
                storage_type: temporary
                secure_url: https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/image.png
                expires_at: 2026-06-25T12:50:26Z
              format: png
              width: 1024
              height: 768
              bytes: 2048576
              model:
                family: flux
                tier: premium
                id: flux-2-pro
              seed: 42
              created_at: 2026-04-21T14:30:00Z
        limits:
          addons_quota:
            - type: image_generation
              used_by_request: 1
              remaining: 48
              limit: 50
        request_id: 17c3b70c5096df0e77e838323abb7029
    GenerateImageManagedAssetSuccessExample:
      summary: Successful synchronous generation (managed asset target)
      description: The 200 response body when the request targeted a managed asset.
      value:
        data:
          assets:
            - storage:
                storage_type: managed_asset
                secure_url: https://res.cloudinary.com/demo/image/upload/v1750000000/my-public-id.png
                asset_id: 0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a
                public_id: my-public-id
                resource_type: image
                type: upload
                version: 1750000000
              format: png
              width: 1024
              height: 768
              bytes: 2048576
              model:
                family: flux
                tier: premium
                id: flux-2-pro
              seed: 42
              created_at: 2026-04-21T14:30:00Z
        limits:
          addons_quota:
            - type: image_generation
              used_by_request: 1
              remaining: 48
              limit: 50
        request_id: 17c3b70c5096df0e77e838323abb7029
    GenerateTaskCompletedExample:
      summary: Completed task (GET /tasks/{task_id})
      description: A completed async task — the asset is fully populated (storage + media).
      value:
        data:
          task_id: 053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
          status: completed
          result:
            assets:
              - storage:
                  storage_type: temporary
                  secure_url: https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream
                  expires_at: 2026-06-25T12:50:26Z
                format: png
                width: 1024
                height: 768
                bytes: 2048576
                model:
                  family: flux
                  tier: premium
                  id: flux-2-pro
                seed: 42
                created_at: 2026-04-21T14:30:00Z
        request_id: 17c3b70c5096df0e77e838323abb7029
    RateLimitedExample:
      summary: 429 rate-limited response
      description: Returned when the account has exhausted its generation quota for the period.
      value:
        error:
          category: rate_limit_error
          code: MG_00429
          message: Daily generation limit exceeded. Limit resets at 2026-04-22T00:00:00Z
        limits:
          addons_quota:
            - type: image_generation
              used_by_request: 1
              remaining: 0
              limit: 50
        request_id: 17c3b70c5096df0e77e838323abb7029
  responses:
    GenerationAcceptedResponse:
      description: Generation accepted.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TaskResponse"
    BadRequestResponse:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    UnauthorizedResponse:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFoundResponse:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimitedResponse:
      description: Rate limited.
      content:
        application/json:
          schema:
            type: object
            title: RateLimitedResponse
            required:
              - error
              - request_id
            properties:
              error:
                $ref: "#/components/schemas/Error"
              limits:
                $ref: "#/components/schemas/Limits"
              notices:
                $ref: "#/components/schemas/Notices"
              request_id:
                type: string
                description: Unique identifier for this request, for correlation and support.
                examples:
                  - 17c3b70c5096df0e77e838323abb7029
          examples:
            RateLimited:
              $ref: "#/components/examples/RateLimitedExample"
    InternalServerErrorResponse:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ModelUnavailableResponse:
      description: Model unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ForbiddenResponse:
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    UnprocessableEntityResponse:
      description: Unprocessable entity.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
x-speakeasy-globals:
  parameters: []