Cloudinary API
Cloudinary DocsGet API keys
HomeAPI ReferenceSDKsContext Plugin
Generation

Generate an image from a text prompt

POST
/v2/generate/{cloud_name}/text_to_image

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.

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 generation request parameters.

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

prompt*string

The text description of the image to generate.

Length1 <= length <= 16384
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

curl -X POST "https://example.com/v2/generate/demo/text_to_image" \  -H "Content-Type: application/json" \  -d '{    "prompt": "A man with a hat"  }'

The 200 response body returned for a completed sync generation.

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

Inspect the caller's permitted actions on people POST

Returns, for each requested person and action, whether the authenticated caller is permitted to perform that action.

Edit or combine images with a text prompt POST

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.