Cloudinary Image Generation

Cloudinary Image Generation lets you generate images from a text prompt, optionally guided by one or more reference images, using a unified API that supports multiple best-in-class AI model families. Generated images are automatically available in your Cloudinary product environment for delivery, transformation, and optimization.

You can generate images in two ways: through the Cloudinary Console or through the API.

Getting started

Before you can use the Cloudinary Image Generation add-on:

• You must have a Cloudinary account. If you don't already have one, you can sign up for a free account.

• Register for the add-on: make sure you're logged in to your account and then go to the Image Generation add-on page. For more information about add-on registrations, see Registering for add-ons.

When you generate your first image through the Cloudinary Console, you're automatically subscribed to the free plan. To increase your usage quota, upgrade your plan in the Cloudinary Console.

Supported models

The Image Generation API supports the following model families. You can select a model by family and tier (for the latest stable model in that family), or pin an exact model by ID.

When you omit the model parameter, the API uses nano-banana at the standard tier.

Models for generating images from reference images

When generating images from reference images you need to specify edit-capable models (by family, tier, or model ID).

Generating images via the Console

You can generate images directly from the Cloudinary Console without writing any code.

1. In the Cloudinary Console, go to Image > Image Generation.
   
   

2. Enter a text description of the image you want to create and click Generate with AI. This takes you to the Image Generation preview page where you can choose the model and specific settings.

3. Select a Model from the drop-down list.

4. Optionally, expand Advanced Settings to configure aspect ratio and resolution.

5. Click Generate with AI to generate the image.

The Preview panel displays the generated image. The Code panel on the right shows the equivalent API call in cURL so you can reproduce the result programmatically.

Images generated via the Console are automatically saved to your Media Library and you can copy the URL of the image ready for optimized delivery.

Generating images via the API

Use the Image Generation API to generate images programmatically from a text prompt, optionally guided by reference images, and integrate them directly into your workflows.

For the full API reference, see the Image Generation API reference.

API authentication

The Image Generation API uses HTTP Basic Authentication. Pass your API Key as the username and your API Secret as the password, either in the URL or in the -u flag:

You can find your Cloud name, API Key, and API Secret on the API Keys page of the Cloudinary Console.

Generate an image and save it in your product environment

The simplest possible request requires only a prompt. The API uses the default nano-banana (standard) model and default image dimensions, and stores the result as a permanent asset in your product environment, where it's immediately available for delivery, transformation, and optimization.

The response includes a permanent secure_url and the asset_id, public_id, and other managed asset fields you can use in other Cloudinary APIs.

The generated image:

Control the stored asset with target

Include a target object to control how and where the generated asset is stored. Set target.target_type to managed_asset (the default) and optionally specify a public_id to control where the asset is stored, and an upload_preset to apply additional configuration (learn about upload presets):

Generate an image with a specific model family and size

Select a model family and quality tier, and use the declarative aspect_ratio and resolution parameters to specify output size. The API resolves the closest dimensions the selected model supports.

The generated image:

Specify an exact model and use pixel dimensions

Use model.id to specify an exact model version, and use width and height for precise pixel control.

The generated image:

Generate a temporary image

Set target.target_type to temporary to generate a short-lived image that expires after a fixed period. This is useful for previewing or evaluating prompts before committing quota to a permanent asset, for example, to iterate on a prompt before saving the result.

The response includes a secure_url that's valid until the expires_at time. To save the image permanently, resubmit the request with target.target_type set to managed_asset.

Generate an image asynchronously

For long-running generations, set async to true. The API returns immediately with a 202 response containing a task_id. You can poll the task endpoint or use a webhook to receive the result.

Response (202 Accepted):

Check the status of an async generation

Poll the task endpoint using the task_id returned in the async response.

When the task is complete, the response includes the full asset with storage and media metadata.

The generated image:

Generate an image from reference images

Use the image_to_image endpoint to generate an image guided by a prompt and one or more reference images. This supports use cases such as restyling, on-brand variants, character consistency, virtual try-on, and edit/extend.

Both prompt and reference_images are required. All other parameters (model, image_size, format, target, seed, async, notification_url) behave the same as for the text_to_image endpoint. Note that this endpoint accepts only edit-capable models.

Reference images are 1-indexed and you can address them positionally in the prompt as [1], [2], and so on. The platform accepts up to 4 reference images, though a specific model may accept fewer (for example, Recraft accepts 1) — exceeding the selected model's capacity returns a 400. Each reference image is provided in one of two ways, set via source_type:

• url: an external HTTPS URL.
• managed_asset: a stored asset in your product environment, by asset_id (read permission is checked).

By URL:

By managed asset ID:

The response has the same structure as for the text_to_image endpoint, including the stored asset's secure_url and managed asset fields.

The generated image:

Automatic tags and metadata

When you generate an image via the Console or the API, Cloudinary automatically applies the following to the asset:

• Tag: text-to-image or image-to-image
• Contextual metadata:
  • model_id: the model used to generate the image (for example, recraft-v4)
  • prompt: the text prompt used for generation
  • seed: the seed value used (or 0 if you didn't specify one)

This makes it straightforward to find, filter, and manage generated images alongside your other assets in the Media Library.

Use case examples

Omnichannel social media campaigns

A marketing team wants to generate a high-end visual for a global campaign and distribute it across Instagram (1:1), TikTok (9:16), and use it as a web banner on their website (16:9). Instead of generating three separate AI images, which would result in inconsistent visuals, they generate one high-resolution image and use Cloudinary to crop it dynamically.

This request uses a high-tier photorealistic model (flux / premium). It instructs the server to output a high-resolution 4K image and permanently stores it under a specific public_id.

Here's an example API call for the demo product environment:

Once generated, you can immediately serve various crops out-of-the-box using Cloudinary's dynamic URL transformations:

• Instagram Grid (1:1 Square, Smart Cropped):

  

• TikTok/Stories (9:16 Vertical, Smart Cropped):

  

• Web Banner (32:9 Horizontal, Smart Cropped):

  

Dynamic e-commerce product backdrops

An online retail brand wants to show their products in various seasonal settings (e.g., a Coke can on a sunny beach, then on a snowy mountain). Instead of setting up costly photoshoots, they generate the backdrop using AI and layer the transparent product PNG directly on top.

This request generates a reusable background asset. Lock down the generation with a seed to ensure consistency if we ever need to re-run it.

Here's an example API call for the demo product environment:

This URL takes the generated beach backdrop image and overlays an existing asset (l_products:can_coke), removing its background, adding drop shadow, and centering it over the AI-generated background on the fly:

Dynamic localization and ad personalization

A travel platform wants to show personalized banners to users depending on where they're booking a trip, complete with localized text rendered on the fly.

This request uses the text-centric model family ideogram to craft a composition perfectly balanced for text placement.

Here's an example API call for the demo product environment:

To maintain campaign consistency, generate the graphic once and dynamically burn text layers (l_text:) into the empty space:

• English version:

  

• Italian version:

  

Brand-aligned vector merchandise

An enterprise wants to allow users to customize internal company swag.

This call leverages the exact model identifier format to specify recraft-v4 directly, ensuring high-fidelity vector/illustration graphics.

Here's an example API call for the demo product environment:

This URL removes the background of the sticker (e_background_removal), before layering it directly onto a pre-existing t-shirt merchandise image (swag:tshirt_mockup):

Efficient catalog photography with a reusable model

An online fashion retailer wants to shoot their catalog without booking a new photoshoot for every product. Instead, they photograph a single model once and reuse that same reference photo to generate on-model shots for each new garment, cutting studio time and cost.

This request uses the image_to_image endpoint with two reference images: the reusable model photo ([1]) and a product shot of the garment ([2]). It uses an edit-capable model (nano-banana / premium) to composite them into a single realistic result. To generate the next product in the catalog, swap in a new garment reference and keep the same model reference.

Here's an example API call for the demo product environment:

The reference images — the model ([1]) and the jacket ([2]):

Model Jacket

The generated composite is stored as a managed asset like any other generation, so you can immediately deliver, transform, or optimize it with Cloudinary's standard delivery URLs. Repeat the request with a different garment reference and the same model reference to produce the rest of the catalog, without rebooking the model or studio:

Plans and quota

Image Generation uses a credit-based billing model. One credit is approximately one US cent, and each generation consumes a variable number of credits depending on the model and output quality. Higher resolution outputs consume more credits.

All Cloudinary accounts include a free monthly credit allotment. When you exhaust your free credits, you must upgrade to a paid Image Generation plan to continue generating images. Paid plans are available independently of your Cloudinary account plan. You can be on a free Cloudinary account and still subscribe to a paid Image Generation plan.

On a paid plan, generation continues on a pay-as-you-go basis once your plan credits are used up. You can view available plans, subscribe, and monitor remaining credits on the Image Generation add-on page in the Cloudinary Console.

For details about prorated billing, mid-cycle upgrades, and downgrade behavior, see Add-on units and billing.