Cloudinary API
Cloudinary DocsGet API keys
HomeAPI ReferenceSDKsContext Plugin
Generation

Edit or combine images with a text prompt

POST
/v2/generate/{cloud_name}/image_to_image

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.

Authorization

AuthorizationBasic <token>

Basic authentication using Cloudinary API Key and API Secret.

In: header

Path Parameters

cloud_name*string

The cloud name of your Cloudinary product environment.

Request Body

application/json

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

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*string

The text instruction describing the desired edit / output.

Length1 <= length <= 16384
reference_images*array<|>

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.

Items1 <= items <= 4
model?||

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

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.

format?ImageFormat

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

Value in

  • "jpeg"
  • "png"
  • "webp"
target?|

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.

seed?|

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.

Range0 <= value
async?Async

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.

Defaultfalse
notification_url?NotificationUrl

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

Formaturi

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/generate/demo/image_to_image" \  -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"      }    ]  }'

The 200 response body for an image-to-image request; the model is always an edit model.

{  "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"}

Generate an image from a text prompt POST

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.

Check the status and result of a generation task GET

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.