Cloudinary Image Generation

Cloudinary Image Generation lets you generate images from text prompts 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 from the Image Generation add-on page 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.

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 in the What do you want to create? field.
3. Select a Model from the drop-down list.
4. Optionally, expand Advanced Settings to configure aspect ratio, resolution, output format, and more.
5. Click Generate.

The Preview panel displays the generated image. The Code panel on the right shows the equivalent API call in cURL, Python, Node.js, or Java so you can reproduce the result programmatically.

Images generated via the Console are automatically saved to your Media Library.

Generating images via the API

Use the Image Generation API to generate images from text prompts programmatically 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.

API examples

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. Set target.target_type to managed_asset to store the result permanently 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:

You can 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:

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 (32:9). Instead of generating three separate AI image, which would consume extra quota and 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 at a 16:9 aspect ratio 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 reusable water bottle 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:water_bottle), resizing it and centering it over the AI-generated background on the fly:

Dynamic Localization & Ad Personalization

A travel platform wants to show personalized banners to users depending on where they are 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:

Instead of paying for multiple image generations per language, you 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):

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.

A free monthly credit allotment is included with all Cloudinary accounts. 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.