Documentation Index

Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt

Use this file to discover all available pages before exploring further.

v1.5.0OAS 3.0.3

Image Generation API

Download OpenAPI Document

Use the Image Generation API to generate images from text prompts and reference images, using various AI models.

The API supports Basic Authentication using your Cloudinary API Key and API Secret, which can be found on the API Keys page of your Cloudinary Console.

Key Features:

  • Unified API: A single interface for generating images across multiple best-in-class AI models.
  • Text-to-image: Generate images from a text prompt.
  • Image-to-image: Generate images guided by one or more reference images and a text prompt.
  • Cloudinary Integration: Generated images are automatically available for delivery, transformation, and optimization through Cloudinary's platform.
  • Future-proof: Adopt new state-of-the-art models as they become available, without rebuilding your integration.

Model Families (model.family / model.tier):

  • 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).

These families are the selection matrix, not the full roster: each family offers a standard and a premium tier. Many models are available only by model.id and belong to no family — see the model.id enum for the complete list.

The Image Generation API requires the Cloudinary Image Generation add-on.

Learn more

Generation

Generate images from text prompts using AI models.

Generate an image from a text prompt

Create any image from a text description with AI: photos, illustrations, logos, icons, product shots, banners, ads, social posts, concept art, mockups, and images with readable text. One call gives you the best image models — Nano Banana, GPT Image, FLUX, Ideogram, Recraft and more. Leave out model and a strong default is used.

Storage is optional. Get the image at a temporary link without saving anything to your account, or keep it in your Media Library, ready to deliver, transform and optimize.

What you get back. Each image comes with its URL, size, format and the model that made it, either in the response or, for longer jobs, from a background task you can check or be notified about. Each generation uses Image Generation credits.

To edit, restyle or combine existing images, use image-to-image (generate-image-from-images) instead.

Path parameters

  • cloud_name stringRequired

    The cloud name of your Cloudinary product environment.

    example "demo"

Body Required application/json

A JSON object containing the generation request parameters.

GenerateImageRequest

Parameters for an image-generation request. Only prompt is required; all other fields fall back to documented defaults.

  • prompt stringRequired

    The text description of the image to generate.

    min length 1max length 16384example "A photorealistic sunset over a mountain lake"
  • model one of

    Selects the model, in one of three mutually exclusive forms (omit to use the default: nano-banana-2, or nano-banana-2-edit for image-to-image):

    • ModelByFamily: family (+ optional tier); the stable-over-time selector.
    • ModelById: an explicit id, pinning one exact model.
    • ModelAuto: mode: auto, letting the service choose the model for the request (+ optional preference).
    ShowHide child attributes of model
    One of
    ModelByFamily

    Select a model by family and quality tier; a missing tier defaults to standard.

    • family stringRequired

      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).
      example "flux"
      enum "flux" "recraft" "gpt-image" "nano-banana" "ideogram"
    • tier string

      Quality tier within the family. Defaults to standard when omitted.

      example "premium"
      enum "standard" "premium"
    ModelById

    Pin an exact model by ID, bypassing family/tier.

    • id stringRequired

      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.

      example "flux-2-pro"
      enum "nano-banana-1" "nano-banana-2" "nano-banana-2-lite" "flux-2-klein-9b" "flux-2-pro" "flux-2-flash" "flux-3" "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" "flux-3-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"
    ModelAuto

    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.

    • mode stringRequired

      The only valid value; selects automatic model selection.

      example "auto"
      enum "auto"
    • preference string

      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.
      default "balanced"example "quality"
      enum "balanced" "quality" "economy" "balanced_fast" "quality_fast" "economy_fast"
  • image_size one of

    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.

    ShowHide child attributes of image_size
    One of
    DimensionsImageSize

    Exact output dimensions in pixels. Both width and height are required together.

    • width integerRequired

      Output width in pixels.

      min 64max 4096example 1280
    • height integerRequired

      Output height in pixels.

      min 64max 4096example 720
    DeclarativeImageSize

    Declarative output size — an aspect ratio plus an optional resolution tier, resolved server-side to the nearest size the model supports.

    • aspect_ratio stringRequired

      Output aspect ratio, width-to-height. Limited to the core ratios every model supports natively.

      example "16:9"
      enum "1:1" "16:9" "9:16" "4:3" "3:4"
    • resolution string

      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
      example "2K"
      enum "0.5K" "1K" "2K" "4K"
  • format string

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

    example "png"
    enum "jpeg" "png" "webp"
  • target one of

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

    ShowHide child attributes of target
    One of (discriminator target_type)
    ManagedAssetTarget target_type: managed_asset

    Store the output as a permanent managed asset in your Cloudinary product environment (the default).

    • target_type stringRequired

      Discriminator identifying this as a managed-asset target.

      example "managed_asset"
      enum "managed_asset"
    • public_id string

      Public ID to store the asset under. Auto-assigned when omitted.

      example "my-public-id"
    • upload_preset string

      Upload preset to apply. Uses the product environment's default when omitted.

      example "some-preset"
    TemporaryTarget target_type: temporary

    Return the image at a short-lived URL (valid until expires_at) without saving it to the user's Cloudinary account.

    • target_type stringRequired

      Discriminator identifying this as a temporary target.

      example "temporary"
      enum "temporary"
  • seed integernullable

    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.

    min 0example 42
  • async boolean

    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.

    default falseexample false
  • notification_url string

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

    format uri URIexample "https://path.to/webhook"

Responses

200 Image generated successfully (synchronous).
application/json
GenerateImageResult

Successful synchronous image-generation response.

  • data GeneratedAssets

    Wrapper holding the array of generated assets.

    ShowHide child attributes of data
    • assets GeneratedAsset[]Required

      The generated assets. Currently a single asset is returned.

      ShowHide child attributes of assets
      Items GeneratedAsset

      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.

      • storage one ofRequired

        Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

        ShowHide child attributes of storage
        One of (discriminator storage_type)
        ManagedAssetStorage storage_type: managed_asset

        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.

        • storage_type stringRequired

          Discriminator identifying this as managed-asset storage.

          example "managed_asset"
          enum "managed_asset"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
        • asset_id string

          Cloudinary asset ID — a stable, globally-unique reference to the asset.

          example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
        • public_id stringRequired

          Public ID of the stored asset.

          example "my-public-id"
        • resource_type stringRequired

          Cloudinary resource type of the stored asset.

          example "image"
          enum "image" "video" "raw"
        • type stringRequired

          Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

          example "upload"
        • version integerRequired

          Version of the stored asset.

          format int64 Signed 64-bit integerexample 1750000000
        TemporaryStorage storage_type: temporary

        A generated asset stored as a short-lived asset on the upload service.

        • storage_type stringRequired

          Discriminator identifying this as temporary storage.

          example "temporary"
          enum "temporary"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
        • expires_at stringRequired

          Time in UTC when secure_url stops being valid.

          format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
      • format string

        The image format of the stored asset.

        example "png"
        enum "png" "jpeg" "webp"
      • width integer

        The width of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 1024
      • height integer

        The height of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 768
      • bytes integer

        The size of the generated image in bytes.

        format int64 Signed 64-bit integerexample 2048576
      • model Model

        Identifies the model that produced a generation result.

        ShowHide child attributes of model
        • family stringRequired

          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.

          example "flux"
        • tier stringRequired

          The quality tier this model holds within its family. none when the model is not part of any family. See family.

          example "premium"
        • id stringRequired

          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.

          example "flux-2-pro"
      • seed integernullable

        The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

        example 42
      • created_at string

        The timestamp when the image was generated.

        format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
202 Generation accepted.
application/json
TaskResponse

Envelope for an async generation task — returned by the accepted (202) response and by GET /tasks/{task_id}.

  • data Task

    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.

    ShowHide child attributes of data
    • task_id stringRequired

      Identifier for the async generation task. Use it to poll GET /generate/{cloud_name}/tasks/{task_id}.

      example "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb"
    • status stringRequired

      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.
      example "completed"
      enum "pending" "processing" "completed" "failed"
    • result objectnullable

      The generated assets. Populated once status is completed.

      ShowHide child attributes of result
      • assets GeneratedAsset[]Required

        The generated assets. Currently a single asset is returned.

        ShowHide child attributes of assets
        Items GeneratedAsset

        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.

        • storage one ofRequired

          Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

          ShowHide child attributes of storage
          One of (discriminator storage_type)
          ManagedAssetStorage storage_type: managed_asset

          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.

          • storage_type stringRequired

            Discriminator identifying this as managed-asset storage.

            example "managed_asset"
            enum "managed_asset"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
          • asset_id string

            Cloudinary asset ID — a stable, globally-unique reference to the asset.

            example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
          • public_id stringRequired

            Public ID of the stored asset.

            example "my-public-id"
          • resource_type stringRequired

            Cloudinary resource type of the stored asset.

            example "image"
            enum "image" "video" "raw"
          • type stringRequired

            Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

            example "upload"
          • version integerRequired

            Version of the stored asset.

            format int64 Signed 64-bit integerexample 1750000000
          TemporaryStorage storage_type: temporary

          A generated asset stored as a short-lived asset on the upload service.

          • storage_type stringRequired

            Discriminator identifying this as temporary storage.

            example "temporary"
            enum "temporary"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
          • expires_at stringRequired

            Time in UTC when secure_url stops being valid.

            format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
        • format string

          The image format of the stored asset.

          example "png"
          enum "png" "jpeg" "webp"
        • width integer

          The width of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 1024
        • height integer

          The height of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 768
        • bytes integer

          The size of the generated image in bytes.

          format int64 Signed 64-bit integerexample 2048576
        • model Model

          Identifies the model that produced a generation result.

          ShowHide child attributes of model
          • family stringRequired

            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.

            example "flux"
          • tier stringRequired

            The quality tier this model holds within its family. none when the model is not part of any family. See family.

            example "premium"
          • id stringRequired

            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.

            example "flux-2-pro"
        • seed integernullable

          The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

          example 42
        • created_at string

          The timestamp when the image was generated.

          format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
    • limits Limits

      Rate limit information for the account's add-on quotas.

      ShowHide child attributes of limits
      • addons_quota AddonQuota[]

        Per-add-on quota usage for this account.

        ShowHide child attributes of addons_quota
        Items AddonQuota

        Credit usage for a single add-on.

        • type stringRequired

          The add-on a quota applies to.

          example "image_generation"
          enum "image_generation"
        • used_by_request integerRequirednullable

          Credits used by this request; 0 when no image was generated.

          example 1
        • remaining integerRequirednullable

          Credits remaining in the current period.

          example 48
        • limit integerRequirednullable

          Credits available per period.

          example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
400 Bad request.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
401 Unauthorized.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
422 The model rejected the input. A content check flagged the prompt or a reference image, a reference URL could not be downloaded, or the model could not produce an image for this prompt. Rephrase the prompt or pass the reference image another way, then retry.

The model rejected the input. A content check flagged the prompt or a reference image, a reference URL could not be downloaded, or the model could not produce an image for this prompt. Rephrase the prompt or pass the reference image another way, then retry.

application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
429 Rate limited.
application/json
object

Error returned when the account is out of Image Generation credits, with the current quota.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
500 Internal server error.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
502 Model unavailable.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
POST/generate/{cloud_name}/text_to_image
curl -X POST 'https://api.cloudinary.com/v2/generate/CLOUD_NAME/text_to_image' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": "A man with a hat"
}'
Response
{
  "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"
}

Edit or combine images with a text prompt

Edit, restyle or combine existing images with AI, guided by a text prompt: replace a background, add or remove objects, apply a style, make on-brand variants, keep a character or product consistent across scenes, virtual try-on, or extend an image. Pass up to 4 reference images, each a public HTTPS url or an asset_id from the user's Cloudinary account, and refer to them in the prompt as [1], [2], …. For a local file, upload it first and reference it by its asset_id. Leave out model and a strong default edit model is used; only edit-capable models are accepted.

Storage is optional. Get the image at a temporary link without saving anything to your account, or keep it in your Media Library.

What you get back. Each image comes with its URL, size, format and the model that made it, either in the response or, for longer jobs, from a background task you can check or be notified about. Each generation uses Image Generation credits.

Path parameters

  • cloud_name stringRequired

    The cloud name of your Cloudinary product environment.

    example "demo"

Body Required application/json

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

ImageToImageRequest

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.

  • prompt stringRequired

    The text instruction describing the desired edit / output.

    min length 1max length 16384example "Place the product from [1] on a marble kitchen counter, soft morning light"
  • reference_images (one of)[]Required

    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.

    min items 1max items 4
    ShowHide child attributes of reference_images
    Items one of

    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.
    One of (discriminator source_type)
    ManagedAssetReference source_type: managed_asset

    A reference to a managed asset in the caller's product environment, by asset ID.

    • source_type stringRequired

      Discriminator identifying this as a managed-asset reference.

      example "managed_asset"
      enum "managed_asset"
    • asset_id stringRequired

      Cloudinary asset ID of the reference image. READ permission is enforced.

      example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
    UrlReference source_type: url

    A reference to an external image by HTTPS URL.

    • source_type stringRequired

      Discriminator identifying this as an external-URL reference.

      example "url"
      enum "url"
    • url stringRequired

      Public HTTPS URL of the reference image.

      format uri URIexample "https://example.com/product.png"
  • model one of

    Selects the model, in one of three mutually exclusive forms (omit to use the default: nano-banana-2, or nano-banana-2-edit for image-to-image):

    • ModelByFamily: family (+ optional tier); the stable-over-time selector.
    • ModelById: an explicit id, pinning one exact model.
    • ModelAuto: mode: auto, letting the service choose the model for the request (+ optional preference).
    ShowHide child attributes of model
    One of
    ModelByFamily

    Select a model by family and quality tier; a missing tier defaults to standard.

    • family stringRequired

      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).
      example "flux"
      enum "flux" "recraft" "gpt-image" "nano-banana" "ideogram"
    • tier string

      Quality tier within the family. Defaults to standard when omitted.

      example "premium"
      enum "standard" "premium"
    ModelById

    Pin an exact model by ID, bypassing family/tier.

    • id stringRequired

      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.

      example "flux-2-pro"
      enum "nano-banana-1" "nano-banana-2" "nano-banana-2-lite" "flux-2-klein-9b" "flux-2-pro" "flux-2-flash" "flux-3" "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" "flux-3-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"
    ModelAuto

    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.

    • mode stringRequired

      The only valid value; selects automatic model selection.

      example "auto"
      enum "auto"
    • preference string

      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.
      default "balanced"example "quality"
      enum "balanced" "quality" "economy" "balanced_fast" "quality_fast" "economy_fast"
  • image_size one of

    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.

    ShowHide child attributes of image_size
    One of
    DimensionsImageSize

    Exact output dimensions in pixels. Both width and height are required together.

    • width integerRequired

      Output width in pixels.

      min 64max 4096example 1280
    • height integerRequired

      Output height in pixels.

      min 64max 4096example 720
    DeclarativeImageSize

    Declarative output size — an aspect ratio plus an optional resolution tier, resolved server-side to the nearest size the model supports.

    • aspect_ratio stringRequired

      Output aspect ratio, width-to-height. Limited to the core ratios every model supports natively.

      example "16:9"
      enum "1:1" "16:9" "9:16" "4:3" "3:4"
    • resolution string

      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
      example "2K"
      enum "0.5K" "1K" "2K" "4K"
  • format string

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

    example "png"
    enum "jpeg" "png" "webp"
  • target one of

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

    ShowHide child attributes of target
    One of (discriminator target_type)
    ManagedAssetTarget target_type: managed_asset

    Store the output as a permanent managed asset in your Cloudinary product environment (the default).

    • target_type stringRequired

      Discriminator identifying this as a managed-asset target.

      example "managed_asset"
      enum "managed_asset"
    • public_id string

      Public ID to store the asset under. Auto-assigned when omitted.

      example "my-public-id"
    • upload_preset string

      Upload preset to apply. Uses the product environment's default when omitted.

      example "some-preset"
    TemporaryTarget target_type: temporary

    Return the image at a short-lived URL (valid until expires_at) without saving it to the user's Cloudinary account.

    • target_type stringRequired

      Discriminator identifying this as a temporary target.

      example "temporary"
      enum "temporary"
  • seed integernullable

    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.

    min 0example 42
  • async boolean

    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.

    default falseexample false
  • notification_url string

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

    format uri URIexample "https://path.to/webhook"

Responses

200 Image generated successfully (synchronous).
application/json
GenerateImageResult

Successful synchronous image-generation response.

  • data GeneratedAssets

    Wrapper holding the array of generated assets.

    ShowHide child attributes of data
    • assets GeneratedAsset[]Required

      The generated assets. Currently a single asset is returned.

      ShowHide child attributes of assets
      Items GeneratedAsset

      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.

      • storage one ofRequired

        Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

        ShowHide child attributes of storage
        One of (discriminator storage_type)
        ManagedAssetStorage storage_type: managed_asset

        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.

        • storage_type stringRequired

          Discriminator identifying this as managed-asset storage.

          example "managed_asset"
          enum "managed_asset"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
        • asset_id string

          Cloudinary asset ID — a stable, globally-unique reference to the asset.

          example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
        • public_id stringRequired

          Public ID of the stored asset.

          example "my-public-id"
        • resource_type stringRequired

          Cloudinary resource type of the stored asset.

          example "image"
          enum "image" "video" "raw"
        • type stringRequired

          Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

          example "upload"
        • version integerRequired

          Version of the stored asset.

          format int64 Signed 64-bit integerexample 1750000000
        TemporaryStorage storage_type: temporary

        A generated asset stored as a short-lived asset on the upload service.

        • storage_type stringRequired

          Discriminator identifying this as temporary storage.

          example "temporary"
          enum "temporary"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
        • expires_at stringRequired

          Time in UTC when secure_url stops being valid.

          format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
      • format string

        The image format of the stored asset.

        example "png"
        enum "png" "jpeg" "webp"
      • width integer

        The width of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 1024
      • height integer

        The height of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 768
      • bytes integer

        The size of the generated image in bytes.

        format int64 Signed 64-bit integerexample 2048576
      • model Model

        Identifies the model that produced a generation result.

        ShowHide child attributes of model
        • family stringRequired

          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.

          example "flux"
        • tier stringRequired

          The quality tier this model holds within its family. none when the model is not part of any family. See family.

          example "premium"
        • id stringRequired

          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.

          example "flux-2-pro"
      • seed integernullable

        The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

        example 42
      • created_at string

        The timestamp when the image was generated.

        format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
202 Generation accepted.
application/json
TaskResponse

Envelope for an async generation task — returned by the accepted (202) response and by GET /tasks/{task_id}.

  • data Task

    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.

    ShowHide child attributes of data
    • task_id stringRequired

      Identifier for the async generation task. Use it to poll GET /generate/{cloud_name}/tasks/{task_id}.

      example "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb"
    • status stringRequired

      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.
      example "completed"
      enum "pending" "processing" "completed" "failed"
    • result objectnullable

      The generated assets. Populated once status is completed.

      ShowHide child attributes of result
      • assets GeneratedAsset[]Required

        The generated assets. Currently a single asset is returned.

        ShowHide child attributes of assets
        Items GeneratedAsset

        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.

        • storage one ofRequired

          Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

          ShowHide child attributes of storage
          One of (discriminator storage_type)
          ManagedAssetStorage storage_type: managed_asset

          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.

          • storage_type stringRequired

            Discriminator identifying this as managed-asset storage.

            example "managed_asset"
            enum "managed_asset"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
          • asset_id string

            Cloudinary asset ID — a stable, globally-unique reference to the asset.

            example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
          • public_id stringRequired

            Public ID of the stored asset.

            example "my-public-id"
          • resource_type stringRequired

            Cloudinary resource type of the stored asset.

            example "image"
            enum "image" "video" "raw"
          • type stringRequired

            Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

            example "upload"
          • version integerRequired

            Version of the stored asset.

            format int64 Signed 64-bit integerexample 1750000000
          TemporaryStorage storage_type: temporary

          A generated asset stored as a short-lived asset on the upload service.

          • storage_type stringRequired

            Discriminator identifying this as temporary storage.

            example "temporary"
            enum "temporary"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
          • expires_at stringRequired

            Time in UTC when secure_url stops being valid.

            format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
        • format string

          The image format of the stored asset.

          example "png"
          enum "png" "jpeg" "webp"
        • width integer

          The width of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 1024
        • height integer

          The height of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 768
        • bytes integer

          The size of the generated image in bytes.

          format int64 Signed 64-bit integerexample 2048576
        • model Model

          Identifies the model that produced a generation result.

          ShowHide child attributes of model
          • family stringRequired

            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.

            example "flux"
          • tier stringRequired

            The quality tier this model holds within its family. none when the model is not part of any family. See family.

            example "premium"
          • id stringRequired

            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.

            example "flux-2-pro"
        • seed integernullable

          The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

          example 42
        • created_at string

          The timestamp when the image was generated.

          format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
    • limits Limits

      Rate limit information for the account's add-on quotas.

      ShowHide child attributes of limits
      • addons_quota AddonQuota[]

        Per-add-on quota usage for this account.

        ShowHide child attributes of addons_quota
        Items AddonQuota

        Credit usage for a single add-on.

        • type stringRequired

          The add-on a quota applies to.

          example "image_generation"
          enum "image_generation"
        • used_by_request integerRequirednullable

          Credits used by this request; 0 when no image was generated.

          example 1
        • remaining integerRequirednullable

          Credits remaining in the current period.

          example 48
        • limit integerRequirednullable

          Credits available per period.

          example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
400 Bad request.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
401 Unauthorized.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
403 Forbidden.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
404 Not found.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
422 The model rejected the input. A content check flagged the prompt or a reference image, a reference URL could not be downloaded, or the model could not produce an image for this prompt. Rephrase the prompt or pass the reference image another way, then retry.

The model rejected the input. A content check flagged the prompt or a reference image, a reference URL could not be downloaded, or the model could not produce an image for this prompt. Rephrase the prompt or pass the reference image another way, then retry.

application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
429 Rate limited.
application/json
object

Error returned when the account is out of Image Generation credits, with the current quota.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
500 Internal server error.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
502 Model unavailable.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
POST/generate/{cloud_name}/image_to_image
curl -X POST 'https://api.cloudinary.com/v2/generate/CLOUD_NAME/image_to_image' \
  -u 'API_KEY:API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
    }
  ]
}'
Response
{
  "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": "nano-banana",
          "tier": "premium",
          "id": "nano-banana-2-edit"
        },
        "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"
}

Tasks

Query the status of async generation tasks.

Check the status and result of a generation task

Check on an image generation running in the background: whether it is pending, processing, completed or failed, and, once it has completed, the generated images with their URLs, size and format.

Path parameters

  • cloud_name stringRequired

    The cloud name of your Cloudinary product environment.

    example "demo"
  • task_id stringRequired

    The ID of the generation task.

    pattern ^[a-f0-9]{1,256}$example "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb"

Responses

200 Generation task status.
application/json
TaskResponse

Envelope for an async generation task — returned by the accepted (202) response and by GET /tasks/{task_id}.

  • data Task

    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.

    ShowHide child attributes of data
    • task_id stringRequired

      Identifier for the async generation task. Use it to poll GET /generate/{cloud_name}/tasks/{task_id}.

      example "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb"
    • status stringRequired

      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.
      example "completed"
      enum "pending" "processing" "completed" "failed"
    • result objectnullable

      The generated assets. Populated once status is completed.

      ShowHide child attributes of result
      • assets GeneratedAsset[]Required

        The generated assets. Currently a single asset is returned.

        ShowHide child attributes of assets
        Items GeneratedAsset

        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.

        • storage one ofRequired

          Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

          ShowHide child attributes of storage
          One of (discriminator storage_type)
          ManagedAssetStorage storage_type: managed_asset

          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.

          • storage_type stringRequired

            Discriminator identifying this as managed-asset storage.

            example "managed_asset"
            enum "managed_asset"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
          • asset_id string

            Cloudinary asset ID — a stable, globally-unique reference to the asset.

            example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
          • public_id stringRequired

            Public ID of the stored asset.

            example "my-public-id"
          • resource_type stringRequired

            Cloudinary resource type of the stored asset.

            example "image"
            enum "image" "video" "raw"
          • type stringRequired

            Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

            example "upload"
          • version integerRequired

            Version of the stored asset.

            format int64 Signed 64-bit integerexample 1750000000
          TemporaryStorage storage_type: temporary

          A generated asset stored as a short-lived asset on the upload service.

          • storage_type stringRequired

            Discriminator identifying this as temporary storage.

            example "temporary"
            enum "temporary"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
          • expires_at stringRequired

            Time in UTC when secure_url stops being valid.

            format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
        • format string

          The image format of the stored asset.

          example "png"
          enum "png" "jpeg" "webp"
        • width integer

          The width of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 1024
        • height integer

          The height of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 768
        • bytes integer

          The size of the generated image in bytes.

          format int64 Signed 64-bit integerexample 2048576
        • model Model

          Identifies the model that produced a generation result.

          ShowHide child attributes of model
          • family stringRequired

            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.

            example "flux"
          • tier stringRequired

            The quality tier this model holds within its family. none when the model is not part of any family. See family.

            example "premium"
          • id stringRequired

            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.

            example "flux-2-pro"
        • seed integernullable

          The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

          example 42
        • created_at string

          The timestamp when the image was generated.

          format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
    • limits Limits

      Rate limit information for the account's add-on quotas.

      ShowHide child attributes of limits
      • addons_quota AddonQuota[]

        Per-add-on quota usage for this account.

        ShowHide child attributes of addons_quota
        Items AddonQuota

        Credit usage for a single add-on.

        • type stringRequired

          The add-on a quota applies to.

          example "image_generation"
          enum "image_generation"
        • used_by_request integerRequirednullable

          Credits used by this request; 0 when no image was generated.

          example 1
        • remaining integerRequirednullable

          Credits remaining in the current period.

          example 48
        • limit integerRequirednullable

          Credits available per period.

          example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
400 Bad request.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
401 Unauthorized.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
404 Not found.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
429 Rate limited.
application/json
object

Error returned when the account is out of Image Generation credits, with the current quota.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
500 Internal server error.
application/json
ErrorResponse

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"
GET/generate/{cloud_name}/tasks/{task_id}
curl 'https://api.cloudinary.com/v2/generate/CLOUD_NAME/tasks/053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb' \
  -u 'API_KEY:API_SECRET'
Response
{
  "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"
}

Models

GenerateImageRequest

Show schema
object

Parameters for an image-generation request. Only prompt is required; all other fields fall back to documented defaults.

  • prompt stringRequired

    The text description of the image to generate.

    min length 1max length 16384example "A photorealistic sunset over a mountain lake"
  • model one of

    Selects the model, in one of three mutually exclusive forms (omit to use the default: nano-banana-2, or nano-banana-2-edit for image-to-image):

    • ModelByFamily: family (+ optional tier); the stable-over-time selector.
    • ModelById: an explicit id, pinning one exact model.
    • ModelAuto: mode: auto, letting the service choose the model for the request (+ optional preference).
    ShowHide child attributes of model
    One of
    ModelByFamily

    Select a model by family and quality tier; a missing tier defaults to standard.

    • family stringRequired

      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).
      example "flux"
      enum "flux" "recraft" "gpt-image" "nano-banana" "ideogram"
    • tier string

      Quality tier within the family. Defaults to standard when omitted.

      example "premium"
      enum "standard" "premium"
    ModelById

    Pin an exact model by ID, bypassing family/tier.

    • id stringRequired

      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.

      example "flux-2-pro"
      enum "nano-banana-1" "nano-banana-2" "nano-banana-2-lite" "flux-2-klein-9b" "flux-2-pro" "flux-2-flash" "flux-3" "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" "flux-3-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"
    ModelAuto

    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.

    • mode stringRequired

      The only valid value; selects automatic model selection.

      example "auto"
      enum "auto"
    • preference string

      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.
      default "balanced"example "quality"
      enum "balanced" "quality" "economy" "balanced_fast" "quality_fast" "economy_fast"
  • image_size one of

    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.

    ShowHide child attributes of image_size
    One of
    DimensionsImageSize

    Exact output dimensions in pixels. Both width and height are required together.

    • width integerRequired

      Output width in pixels.

      min 64max 4096example 1280
    • height integerRequired

      Output height in pixels.

      min 64max 4096example 720
    DeclarativeImageSize

    Declarative output size — an aspect ratio plus an optional resolution tier, resolved server-side to the nearest size the model supports.

    • aspect_ratio stringRequired

      Output aspect ratio, width-to-height. Limited to the core ratios every model supports natively.

      example "16:9"
      enum "1:1" "16:9" "9:16" "4:3" "3:4"
    • resolution string

      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
      example "2K"
      enum "0.5K" "1K" "2K" "4K"
  • format string

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

    example "png"
    enum "jpeg" "png" "webp"
  • target one of

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

    ShowHide child attributes of target
    One of (discriminator target_type)
    ManagedAssetTarget target_type: managed_asset

    Store the output as a permanent managed asset in your Cloudinary product environment (the default).

    • target_type stringRequired

      Discriminator identifying this as a managed-asset target.

      example "managed_asset"
      enum "managed_asset"
    • public_id string

      Public ID to store the asset under. Auto-assigned when omitted.

      example "my-public-id"
    • upload_preset string

      Upload preset to apply. Uses the product environment's default when omitted.

      example "some-preset"
    TemporaryTarget target_type: temporary

    Return the image at a short-lived URL (valid until expires_at) without saving it to the user's Cloudinary account.

    • target_type stringRequired

      Discriminator identifying this as a temporary target.

      example "temporary"
      enum "temporary"
  • seed integernullable

    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.

    min 0example 42
  • async boolean

    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.

    default falseexample false
  • notification_url string

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

    format uri URIexample "https://path.to/webhook"

ImageFormat

Show schema
string

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

example "png"
enum "jpeg" "png" "webp"

Seed

Show schema
integer

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.

min 0example 42

Async

Show schema
boolean

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.

default falseexample false

NotificationUrl

Show schema
string

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

format uri URIexample "https://path.to/webhook"

ImageToImageRequest

Show schema
object

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.

  • prompt stringRequired

    The text instruction describing the desired edit / output.

    min length 1max length 16384example "Place the product from [1] on a marble kitchen counter, soft morning light"
  • reference_images (one of)[]Required

    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.

    min items 1max items 4
    ShowHide child attributes of reference_images
    Items one of

    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.
    One of (discriminator source_type)
    ManagedAssetReference source_type: managed_asset

    A reference to a managed asset in the caller's product environment, by asset ID.

    • source_type stringRequired

      Discriminator identifying this as a managed-asset reference.

      example "managed_asset"
      enum "managed_asset"
    • asset_id stringRequired

      Cloudinary asset ID of the reference image. READ permission is enforced.

      example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
    UrlReference source_type: url

    A reference to an external image by HTTPS URL.

    • source_type stringRequired

      Discriminator identifying this as an external-URL reference.

      example "url"
      enum "url"
    • url stringRequired

      Public HTTPS URL of the reference image.

      format uri URIexample "https://example.com/product.png"
  • model one of

    Selects the model, in one of three mutually exclusive forms (omit to use the default: nano-banana-2, or nano-banana-2-edit for image-to-image):

    • ModelByFamily: family (+ optional tier); the stable-over-time selector.
    • ModelById: an explicit id, pinning one exact model.
    • ModelAuto: mode: auto, letting the service choose the model for the request (+ optional preference).
    ShowHide child attributes of model
    One of
    ModelByFamily

    Select a model by family and quality tier; a missing tier defaults to standard.

    • family stringRequired

      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).
      example "flux"
      enum "flux" "recraft" "gpt-image" "nano-banana" "ideogram"
    • tier string

      Quality tier within the family. Defaults to standard when omitted.

      example "premium"
      enum "standard" "premium"
    ModelById

    Pin an exact model by ID, bypassing family/tier.

    • id stringRequired

      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.

      example "flux-2-pro"
      enum "nano-banana-1" "nano-banana-2" "nano-banana-2-lite" "flux-2-klein-9b" "flux-2-pro" "flux-2-flash" "flux-3" "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" "flux-3-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"
    ModelAuto

    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.

    • mode stringRequired

      The only valid value; selects automatic model selection.

      example "auto"
      enum "auto"
    • preference string

      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.
      default "balanced"example "quality"
      enum "balanced" "quality" "economy" "balanced_fast" "quality_fast" "economy_fast"
  • image_size one of

    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.

    ShowHide child attributes of image_size
    One of
    DimensionsImageSize

    Exact output dimensions in pixels. Both width and height are required together.

    • width integerRequired

      Output width in pixels.

      min 64max 4096example 1280
    • height integerRequired

      Output height in pixels.

      min 64max 4096example 720
    DeclarativeImageSize

    Declarative output size — an aspect ratio plus an optional resolution tier, resolved server-side to the nearest size the model supports.

    • aspect_ratio stringRequired

      Output aspect ratio, width-to-height. Limited to the core ratios every model supports natively.

      example "16:9"
      enum "1:1" "16:9" "9:16" "4:3" "3:4"
    • resolution string

      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
      example "2K"
      enum "0.5K" "1K" "2K" "4K"
  • format string

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

    example "png"
    enum "jpeg" "png" "webp"
  • target one of

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

    ShowHide child attributes of target
    One of (discriminator target_type)
    ManagedAssetTarget target_type: managed_asset

    Store the output as a permanent managed asset in your Cloudinary product environment (the default).

    • target_type stringRequired

      Discriminator identifying this as a managed-asset target.

      example "managed_asset"
      enum "managed_asset"
    • public_id string

      Public ID to store the asset under. Auto-assigned when omitted.

      example "my-public-id"
    • upload_preset string

      Upload preset to apply. Uses the product environment's default when omitted.

      example "some-preset"
    TemporaryTarget target_type: temporary

    Return the image at a short-lived URL (valid until expires_at) without saving it to the user's Cloudinary account.

    • target_type stringRequired

      Discriminator identifying this as a temporary target.

      example "temporary"
      enum "temporary"
  • seed integernullable

    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.

    min 0example 42
  • async boolean

    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.

    default falseexample false
  • notification_url string

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

    format uri URIexample "https://path.to/webhook"

ReferenceImage

Show schema
one of

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.
One of (discriminator source_type)
ManagedAssetReference source_type: managed_asset

A reference to a managed asset in the caller's product environment, by asset ID.

  • source_type stringRequired

    Discriminator identifying this as a managed-asset reference.

    example "managed_asset"
    enum "managed_asset"
  • asset_id stringRequired

    Cloudinary asset ID of the reference image. READ permission is enforced.

    example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
UrlReference source_type: url

A reference to an external image by HTTPS URL.

  • source_type stringRequired

    Discriminator identifying this as an external-URL reference.

    example "url"
    enum "url"
  • url stringRequired

    Public HTTPS URL of the reference image.

    format uri URIexample "https://example.com/product.png"

ManagedAssetReference

Show schema
object

A reference to a managed asset in the caller's product environment, by asset ID.

  • source_type stringRequired

    Discriminator identifying this as a managed-asset reference.

    example "managed_asset"
    enum "managed_asset"
  • asset_id stringRequired

    Cloudinary asset ID of the reference image. READ permission is enforced.

    example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"

UrlReference

Show schema
object

A reference to an external image by HTTPS URL.

  • source_type stringRequired

    Discriminator identifying this as an external-URL reference.

    example "url"
    enum "url"
  • url stringRequired

    Public HTTPS URL of the reference image.

    format uri URIexample "https://example.com/product.png"

ModelSelection

Show schema
one of

Selects the model, in one of three mutually exclusive forms (omit to use the default: nano-banana-2, or nano-banana-2-edit for image-to-image):

  • ModelByFamily: family (+ optional tier); the stable-over-time selector.
  • ModelById: an explicit id, pinning one exact model.
  • ModelAuto: mode: auto, letting the service choose the model for the request (+ optional preference).
One of
ModelByFamily

Select a model by family and quality tier; a missing tier defaults to standard.

  • family stringRequired

    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).
    example "flux"
    enum "flux" "recraft" "gpt-image" "nano-banana" "ideogram"
  • tier string

    Quality tier within the family. Defaults to standard when omitted.

    example "premium"
    enum "standard" "premium"
ModelById

Pin an exact model by ID, bypassing family/tier.

  • id stringRequired

    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.

    example "flux-2-pro"
    enum "nano-banana-1" "nano-banana-2" "nano-banana-2-lite" "flux-2-klein-9b" "flux-2-pro" "flux-2-flash" "flux-3" "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" "flux-3-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"
ModelAuto

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.

  • mode stringRequired

    The only valid value; selects automatic model selection.

    example "auto"
    enum "auto"
  • preference string

    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.
    default "balanced"example "quality"
    enum "balanced" "quality" "economy" "balanced_fast" "quality_fast" "economy_fast"

ModelByFamily

Show schema
object

Select a model by family and quality tier; a missing tier defaults to standard.

  • family stringRequired

    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).
    example "flux"
    enum "flux" "recraft" "gpt-image" "nano-banana" "ideogram"
  • tier string

    Quality tier within the family. Defaults to standard when omitted.

    example "premium"
    enum "standard" "premium"

ModelById

Show schema
object

Pin an exact model by ID, bypassing family/tier.

  • id stringRequired

    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.

    example "flux-2-pro"
    enum "nano-banana-1" "nano-banana-2" "nano-banana-2-lite" "flux-2-klein-9b" "flux-2-pro" "flux-2-flash" "flux-3" "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" "flux-3-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"

ModelAuto

Show schema
object

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.

  • mode stringRequired

    The only valid value; selects automatic model selection.

    example "auto"
    enum "auto"
  • preference string

    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.
    default "balanced"example "quality"
    enum "balanced" "quality" "economy" "balanced_fast" "quality_fast" "economy_fast"

ImageSize

Show schema
one of

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.

One of
DimensionsImageSize

Exact output dimensions in pixels. Both width and height are required together.

  • width integerRequired

    Output width in pixels.

    min 64max 4096example 1280
  • height integerRequired

    Output height in pixels.

    min 64max 4096example 720
DeclarativeImageSize

Declarative output size — an aspect ratio plus an optional resolution tier, resolved server-side to the nearest size the model supports.

  • aspect_ratio stringRequired

    Output aspect ratio, width-to-height. Limited to the core ratios every model supports natively.

    example "16:9"
    enum "1:1" "16:9" "9:16" "4:3" "3:4"
  • resolution string

    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
    example "2K"
    enum "0.5K" "1K" "2K" "4K"

DimensionsImageSize

Show schema
object

Exact output dimensions in pixels. Both width and height are required together.

  • width integerRequired

    Output width in pixels.

    min 64max 4096example 1280
  • height integerRequired

    Output height in pixels.

    min 64max 4096example 720

DeclarativeImageSize

Show schema
object

Declarative output size — an aspect ratio plus an optional resolution tier, resolved server-side to the nearest size the model supports.

  • aspect_ratio stringRequired

    Output aspect ratio, width-to-height. Limited to the core ratios every model supports natively.

    example "16:9"
    enum "1:1" "16:9" "9:16" "4:3" "3:4"
  • resolution string

    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
    example "2K"
    enum "0.5K" "1K" "2K" "4K"

Target

Show schema
one of

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

One of (discriminator target_type)
ManagedAssetTarget target_type: managed_asset

Store the output as a permanent managed asset in your Cloudinary product environment (the default).

  • target_type stringRequired

    Discriminator identifying this as a managed-asset target.

    example "managed_asset"
    enum "managed_asset"
  • public_id string

    Public ID to store the asset under. Auto-assigned when omitted.

    example "my-public-id"
  • upload_preset string

    Upload preset to apply. Uses the product environment's default when omitted.

    example "some-preset"
TemporaryTarget target_type: temporary

Return the image at a short-lived URL (valid until expires_at) without saving it to the user's Cloudinary account.

  • target_type stringRequired

    Discriminator identifying this as a temporary target.

    example "temporary"
    enum "temporary"

ManagedAssetTarget

Show schema
object

Store the output as a permanent managed asset in your Cloudinary product environment (the default).

  • target_type stringRequired

    Discriminator identifying this as a managed-asset target.

    example "managed_asset"
    enum "managed_asset"
  • public_id string

    Public ID to store the asset under. Auto-assigned when omitted.

    example "my-public-id"
  • upload_preset string

    Upload preset to apply. Uses the product environment's default when omitted.

    example "some-preset"

TemporaryTarget

Show schema
object

Return the image at a short-lived URL (valid until expires_at) without saving it to the user's Cloudinary account.

  • target_type stringRequired

    Discriminator identifying this as a temporary target.

    example "temporary"
    enum "temporary"

Storage

Show schema
one of

Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

One of (discriminator storage_type)
ManagedAssetStorage storage_type: managed_asset

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.

  • storage_type stringRequired

    Discriminator identifying this as managed-asset storage.

    example "managed_asset"
    enum "managed_asset"
  • secure_url stringRequired

    The URL to fetch the generated asset.

    format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
  • asset_id string

    Cloudinary asset ID — a stable, globally-unique reference to the asset.

    example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
  • public_id stringRequired

    Public ID of the stored asset.

    example "my-public-id"
  • resource_type stringRequired

    Cloudinary resource type of the stored asset.

    example "image"
    enum "image" "video" "raw"
  • type stringRequired

    Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

    example "upload"
  • version integerRequired

    Version of the stored asset.

    format int64 Signed 64-bit integerexample 1750000000
TemporaryStorage storage_type: temporary

A generated asset stored as a short-lived asset on the upload service.

  • storage_type stringRequired

    Discriminator identifying this as temporary storage.

    example "temporary"
    enum "temporary"
  • secure_url stringRequired

    The URL to fetch the generated asset.

    format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
  • expires_at stringRequired

    Time in UTC when secure_url stops being valid.

    format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"

ManagedAssetStorage

Show schema
object

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.

  • storage_type stringRequired

    Discriminator identifying this as managed-asset storage.

    example "managed_asset"
    enum "managed_asset"
  • secure_url stringRequired

    The URL to fetch the generated asset.

    format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
  • asset_id string

    Cloudinary asset ID — a stable, globally-unique reference to the asset.

    example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
  • public_id stringRequired

    Public ID of the stored asset.

    example "my-public-id"
  • resource_type stringRequired

    Cloudinary resource type of the stored asset.

    example "image"
    enum "image" "video" "raw"
  • type stringRequired

    Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

    example "upload"
  • version integerRequired

    Version of the stored asset.

    format int64 Signed 64-bit integerexample 1750000000

TemporaryStorage

Show schema
object

A generated asset stored as a short-lived asset on the upload service.

  • storage_type stringRequired

    Discriminator identifying this as temporary storage.

    example "temporary"
    enum "temporary"
  • secure_url stringRequired

    The URL to fetch the generated asset.

    format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
  • expires_at stringRequired

    Time in UTC when secure_url stops being valid.

    format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"

GenerateImageResult

Show schema
object

Successful synchronous image-generation response.

  • data GeneratedAssets

    Wrapper holding the array of generated assets.

    ShowHide child attributes of data
    • assets GeneratedAsset[]Required

      The generated assets. Currently a single asset is returned.

      ShowHide child attributes of assets
      Items GeneratedAsset

      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.

      • storage one ofRequired

        Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

        ShowHide child attributes of storage
        One of (discriminator storage_type)
        ManagedAssetStorage storage_type: managed_asset

        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.

        • storage_type stringRequired

          Discriminator identifying this as managed-asset storage.

          example "managed_asset"
          enum "managed_asset"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
        • asset_id string

          Cloudinary asset ID — a stable, globally-unique reference to the asset.

          example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
        • public_id stringRequired

          Public ID of the stored asset.

          example "my-public-id"
        • resource_type stringRequired

          Cloudinary resource type of the stored asset.

          example "image"
          enum "image" "video" "raw"
        • type stringRequired

          Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

          example "upload"
        • version integerRequired

          Version of the stored asset.

          format int64 Signed 64-bit integerexample 1750000000
        TemporaryStorage storage_type: temporary

        A generated asset stored as a short-lived asset on the upload service.

        • storage_type stringRequired

          Discriminator identifying this as temporary storage.

          example "temporary"
          enum "temporary"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
        • expires_at stringRequired

          Time in UTC when secure_url stops being valid.

          format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
      • format string

        The image format of the stored asset.

        example "png"
        enum "png" "jpeg" "webp"
      • width integer

        The width of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 1024
      • height integer

        The height of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 768
      • bytes integer

        The size of the generated image in bytes.

        format int64 Signed 64-bit integerexample 2048576
      • model Model

        Identifies the model that produced a generation result.

        ShowHide child attributes of model
        • family stringRequired

          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.

          example "flux"
        • tier stringRequired

          The quality tier this model holds within its family. none when the model is not part of any family. See family.

          example "premium"
        • id stringRequired

          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.

          example "flux-2-pro"
      • seed integernullable

        The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

        example 42
      • created_at string

        The timestamp when the image was generated.

        format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"

GeneratedAssets

Show schema
object

Wrapper holding the array of generated assets.

  • assets GeneratedAsset[]Required

    The generated assets. Currently a single asset is returned.

    ShowHide child attributes of assets
    Items GeneratedAsset

    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.

    • storage one ofRequired

      Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

      ShowHide child attributes of storage
      One of (discriminator storage_type)
      ManagedAssetStorage storage_type: managed_asset

      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.

      • storage_type stringRequired

        Discriminator identifying this as managed-asset storage.

        example "managed_asset"
        enum "managed_asset"
      • secure_url stringRequired

        The URL to fetch the generated asset.

        format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
      • asset_id string

        Cloudinary asset ID — a stable, globally-unique reference to the asset.

        example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
      • public_id stringRequired

        Public ID of the stored asset.

        example "my-public-id"
      • resource_type stringRequired

        Cloudinary resource type of the stored asset.

        example "image"
        enum "image" "video" "raw"
      • type stringRequired

        Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

        example "upload"
      • version integerRequired

        Version of the stored asset.

        format int64 Signed 64-bit integerexample 1750000000
      TemporaryStorage storage_type: temporary

      A generated asset stored as a short-lived asset on the upload service.

      • storage_type stringRequired

        Discriminator identifying this as temporary storage.

        example "temporary"
        enum "temporary"
      • secure_url stringRequired

        The URL to fetch the generated asset.

        format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
      • expires_at stringRequired

        Time in UTC when secure_url stops being valid.

        format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
    • format string

      The image format of the stored asset.

      example "png"
      enum "png" "jpeg" "webp"
    • width integer

      The width of the generated image in pixels; zero if the model doesn't provide dimensions.

      example 1024
    • height integer

      The height of the generated image in pixels; zero if the model doesn't provide dimensions.

      example 768
    • bytes integer

      The size of the generated image in bytes.

      format int64 Signed 64-bit integerexample 2048576
    • model Model

      Identifies the model that produced a generation result.

      ShowHide child attributes of model
      • family stringRequired

        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.

        example "flux"
      • tier stringRequired

        The quality tier this model holds within its family. none when the model is not part of any family. See family.

        example "premium"
      • id stringRequired

        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.

        example "flux-2-pro"
    • seed integernullable

      The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

      example 42
    • created_at string

      The timestamp when the image was generated.

      format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"

GeneratedAsset

Show schema
object

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.

  • storage one ofRequired

    Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

    ShowHide child attributes of storage
    One of (discriminator storage_type)
    ManagedAssetStorage storage_type: managed_asset

    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.

    • storage_type stringRequired

      Discriminator identifying this as managed-asset storage.

      example "managed_asset"
      enum "managed_asset"
    • secure_url stringRequired

      The URL to fetch the generated asset.

      format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
    • asset_id string

      Cloudinary asset ID — a stable, globally-unique reference to the asset.

      example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
    • public_id stringRequired

      Public ID of the stored asset.

      example "my-public-id"
    • resource_type stringRequired

      Cloudinary resource type of the stored asset.

      example "image"
      enum "image" "video" "raw"
    • type stringRequired

      Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

      example "upload"
    • version integerRequired

      Version of the stored asset.

      format int64 Signed 64-bit integerexample 1750000000
    TemporaryStorage storage_type: temporary

    A generated asset stored as a short-lived asset on the upload service.

    • storage_type stringRequired

      Discriminator identifying this as temporary storage.

      example "temporary"
      enum "temporary"
    • secure_url stringRequired

      The URL to fetch the generated asset.

      format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
    • expires_at stringRequired

      Time in UTC when secure_url stops being valid.

      format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
  • format string

    The image format of the stored asset.

    example "png"
    enum "png" "jpeg" "webp"
  • width integer

    The width of the generated image in pixels; zero if the model doesn't provide dimensions.

    example 1024
  • height integer

    The height of the generated image in pixels; zero if the model doesn't provide dimensions.

    example 768
  • bytes integer

    The size of the generated image in bytes.

    format int64 Signed 64-bit integerexample 2048576
  • model Model

    Identifies the model that produced a generation result.

    ShowHide child attributes of model
    • family stringRequired

      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.

      example "flux"
    • tier stringRequired

      The quality tier this model holds within its family. none when the model is not part of any family. See family.

      example "premium"
    • id stringRequired

      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.

      example "flux-2-pro"
  • seed integernullable

    The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

    example 42
  • created_at string

    The timestamp when the image was generated.

    format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"

Model

Show schema
object

Identifies the model that produced a generation result.

  • family stringRequired

    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.

    example "flux"
  • tier stringRequired

    The quality tier this model holds within its family. none when the model is not part of any family. See family.

    example "premium"
  • id stringRequired

    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.

    example "flux-2-pro"

TaskStatus

Show schema
string

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.
example "completed"
enum "pending" "processing" "completed" "failed"

Task

Show schema
object

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.

  • task_id stringRequired

    Identifier for the async generation task. Use it to poll GET /generate/{cloud_name}/tasks/{task_id}.

    example "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb"
  • status stringRequired

    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.
    example "completed"
    enum "pending" "processing" "completed" "failed"
  • result objectnullable

    The generated assets. Populated once status is completed.

    ShowHide child attributes of result
    • assets GeneratedAsset[]Required

      The generated assets. Currently a single asset is returned.

      ShowHide child attributes of assets
      Items GeneratedAsset

      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.

      • storage one ofRequired

        Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

        ShowHide child attributes of storage
        One of (discriminator storage_type)
        ManagedAssetStorage storage_type: managed_asset

        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.

        • storage_type stringRequired

          Discriminator identifying this as managed-asset storage.

          example "managed_asset"
          enum "managed_asset"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
        • asset_id string

          Cloudinary asset ID — a stable, globally-unique reference to the asset.

          example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
        • public_id stringRequired

          Public ID of the stored asset.

          example "my-public-id"
        • resource_type stringRequired

          Cloudinary resource type of the stored asset.

          example "image"
          enum "image" "video" "raw"
        • type stringRequired

          Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

          example "upload"
        • version integerRequired

          Version of the stored asset.

          format int64 Signed 64-bit integerexample 1750000000
        TemporaryStorage storage_type: temporary

        A generated asset stored as a short-lived asset on the upload service.

        • storage_type stringRequired

          Discriminator identifying this as temporary storage.

          example "temporary"
          enum "temporary"
        • secure_url stringRequired

          The URL to fetch the generated asset.

          format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
        • expires_at stringRequired

          Time in UTC when secure_url stops being valid.

          format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
      • format string

        The image format of the stored asset.

        example "png"
        enum "png" "jpeg" "webp"
      • width integer

        The width of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 1024
      • height integer

        The height of the generated image in pixels; zero if the model doesn't provide dimensions.

        example 768
      • bytes integer

        The size of the generated image in bytes.

        format int64 Signed 64-bit integerexample 2048576
      • model Model

        Identifies the model that produced a generation result.

        ShowHide child attributes of model
        • family stringRequired

          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.

          example "flux"
        • tier stringRequired

          The quality tier this model holds within its family. none when the model is not part of any family. See family.

          example "premium"
        • id stringRequired

          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.

          example "flux-2-pro"
      • seed integernullable

        The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

        example 42
      • created_at string

        The timestamp when the image was generated.

        format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
  • limits Limits

    Rate limit information for the account's add-on quotas.

    ShowHide child attributes of limits
    • addons_quota AddonQuota[]

      Per-add-on quota usage for this account.

      ShowHide child attributes of addons_quota
      Items AddonQuota

      Credit usage for a single add-on.

      • type stringRequired

        The add-on a quota applies to.

        example "image_generation"
        enum "image_generation"
      • used_by_request integerRequirednullable

        Credits used by this request; 0 when no image was generated.

        example 1
      • remaining integerRequirednullable

        Credits remaining in the current period.

        example 48
      • limit integerRequirednullable

        Credits available per period.

        example 50

TaskResponse

Show schema
object

Envelope for an async generation task — returned by the accepted (202) response and by GET /tasks/{task_id}.

  • data Task

    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.

    ShowHide child attributes of data
    • task_id stringRequired

      Identifier for the async generation task. Use it to poll GET /generate/{cloud_name}/tasks/{task_id}.

      example "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb"
    • status stringRequired

      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.
      example "completed"
      enum "pending" "processing" "completed" "failed"
    • result objectnullable

      The generated assets. Populated once status is completed.

      ShowHide child attributes of result
      • assets GeneratedAsset[]Required

        The generated assets. Currently a single asset is returned.

        ShowHide child attributes of assets
        Items GeneratedAsset

        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.

        • storage one ofRequired

          Where the generated asset is actually stored, determined by storage_type. Usually matches the request target; a managed_asset request falls back to temporary when the caller lacks upload permission. secure_url is always present.

          ShowHide child attributes of storage
          One of (discriminator storage_type)
          ManagedAssetStorage storage_type: managed_asset

          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.

          • storage_type stringRequired

            Discriminator identifying this as managed-asset storage.

            example "managed_asset"
            enum "managed_asset"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://res.cloudinary.com/demo/image/upload/v1/my-public-id.png"
          • asset_id string

            Cloudinary asset ID — a stable, globally-unique reference to the asset.

            example "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a"
          • public_id stringRequired

            Public ID of the stored asset.

            example "my-public-id"
          • resource_type stringRequired

            Cloudinary resource type of the stored asset.

            example "image"
            enum "image" "video" "raw"
          • type stringRequired

            Cloudinary delivery type of the stored asset (e.g. upload, private, authenticated).

            example "upload"
          • version integerRequired

            Version of the stored asset.

            format int64 Signed 64-bit integerexample 1750000000
          TemporaryStorage storage_type: temporary

          A generated asset stored as a short-lived asset on the upload service.

          • storage_type stringRequired

            Discriminator identifying this as temporary storage.

            example "temporary"
            enum "temporary"
          • secure_url stringRequired

            The URL to fetch the generated asset.

            format uri URIexample "https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream"
          • expires_at stringRequired

            Time in UTC when secure_url stops being valid.

            format date-time RFC 3339 date-timeexample "2026-06-25T12:50:26Z"
        • format string

          The image format of the stored asset.

          example "png"
          enum "png" "jpeg" "webp"
        • width integer

          The width of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 1024
        • height integer

          The height of the generated image in pixels; zero if the model doesn't provide dimensions.

          example 768
        • bytes integer

          The size of the generated image in bytes.

          format int64 Signed 64-bit integerexample 2048576
        • model Model

          Identifies the model that produced a generation result.

          ShowHide child attributes of model
          • family stringRequired

            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.

            example "flux"
          • tier stringRequired

            The quality tier this model holds within its family. none when the model is not part of any family. See family.

            example "premium"
          • id stringRequired

            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.

            example "flux-2-pro"
        • seed integernullable

          The seed used for generation. Echoes input or returns the model-generated seed. Null when the model doesn't support seeds.

          example 42
        • created_at string

          The timestamp when the image was generated.

          format date-time RFC 3339 date-timeexample "2026-04-21T14:30:00Z"
    • limits Limits

      Rate limit information for the account's add-on quotas.

      ShowHide child attributes of limits
      • addons_quota AddonQuota[]

        Per-add-on quota usage for this account.

        ShowHide child attributes of addons_quota
        Items AddonQuota

        Credit usage for a single add-on.

        • type stringRequired

          The add-on a quota applies to.

          example "image_generation"
          enum "image_generation"
        • used_by_request integerRequirednullable

          Credits used by this request; 0 when no image was generated.

          example 1
        • remaining integerRequirednullable

          Credits remaining in the current period.

          example 48
        • limit integerRequirednullable

          Credits available per period.

          example 50
  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"

ErrorResponse

Show schema
object

Wrapper for error responses; includes the error object and a request_id for correlation.

  • error ErrorRequired

    Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

    ShowHide child attributes of error
    • category string

      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.
      example "user_error"
      enum "user_error" "auth_error" "server_error" "rate_limit_error"
    • code string

      Stable, machine-readable error code for programmatic handling.

      example "MG_00001"
    • message string

      Human-readable description of what went wrong.

      example "missing parameters"
    • details object

      Additional structured context about the error, when available.

  • notices Notice[]

    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.

    ShowHide child attributes of notices
    Items Notice

    A single tip or piece of guidance, with how much weight to give it.

    • severity stringRequired

      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.
      example "info"
      enum "info" "warning" "blocking"
    • text stringRequired

      The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

      example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"
  • request_id stringRequired

    Unique identifier for this request, for correlation and support.

    example "17c3b70c5096df0e77e838323abb7029"

Error

Show schema
object

Details of an error, including a coarse category for retry logic, a stable error code, and a human-readable message.

  • category string

    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.
    example "user_error"
    enum "user_error" "auth_error" "server_error" "rate_limit_error"
  • code string

    Stable, machine-readable error code for programmatic handling.

    example "MG_00001"
  • message string

    Human-readable description of what went wrong.

    example "missing parameters"
  • details object

    Additional structured context about the error, when available.

ErrorCategory

Show schema
string

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.
example "user_error"
enum "user_error" "auth_error" "server_error" "rate_limit_error"

Notices

Show schema
Notice[]

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 Notice

A single tip or piece of guidance, with how much weight to give it.

  • severity stringRequired

    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.
    example "info"
    enum "info" "warning" "blocking"
  • text stringRequired

    The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

    example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"

Notice

Show schema
object

A single tip or piece of guidance, with how much weight to give it.

  • severity stringRequired

    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.
    example "info"
    enum "info" "warning" "blocking"
  • text stringRequired

    The tip or guidance, in plain text. Show it as-is or follow it; the wording may change between releases.

    example "You've used 25 of your 50 Image Generation credits. No action needed. If this run will keep generating, tell the user their balance is half spent and show them: https://console.cloudinary.com/app/image/generation/plans"

Limits

Show schema
object

Rate limit information for the account's add-on quotas.

  • addons_quota AddonQuota[]

    Per-add-on quota usage for this account.

    ShowHide child attributes of addons_quota
    Items AddonQuota

    Credit usage for a single add-on.

    • type stringRequired

      The add-on a quota applies to.

      example "image_generation"
      enum "image_generation"
    • used_by_request integerRequirednullable

      Credits used by this request; 0 when no image was generated.

      example 1
    • remaining integerRequirednullable

      Credits remaining in the current period.

      example 48
    • limit integerRequirednullable

      Credits available per period.

      example 50

AddonQuota

Show schema
object

Credit usage for a single add-on.

  • type stringRequired

    The add-on a quota applies to.

    example "image_generation"
    enum "image_generation"
  • used_by_request integerRequirednullable

    Credits used by this request; 0 when no image was generated.

    example 1
  • remaining integerRequirednullable

    Credits remaining in the current period.

    example 48
  • limit integerRequirednullable

    Credits available per period.

    example 50

Feature

Show schema
string

The add-on a quota applies to.

example "image_generation"
enum "image_generation"