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.
Image Generation API
Download OpenAPI DocumentUse 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.
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.
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, ornano-banana-2-editfor image-to-image):ModelByFamily:family(+ optionaltier); the stable-over-time selector.ModelById: an explicitid, pinning one exact model.ModelAuto:mode: auto, letting the service choose the model for the request (+ optionalpreference).
ShowHide child attributes of model
One ofModelByFamily
Select a model by family and quality tier; a missing
tierdefaults tostandard.- 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
standardwhen 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
-editmodels accept reference images and are selectable only onimage_to_image; the others only ontext_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; onimage_to_imageit 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:widthandheightin pixels, for precise control.DeclarativeImageSize:aspect_ratio(and an optionalresolutiontier), 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_sizeentirely to use the model's default size.ShowHide child attributes of image_size
One ofDimensionsImageSize
Exact output dimensions in pixels. Both
widthandheightare required together.- width integerRequired
Output width in pixels.
min 64max 4096example1280 - height integerRequired
Output height in pixels.
min 64max 4096example720
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
1Kwhen omitted.0.5K: ~512 px1K: ~1024 px2K: ~2048 px4K: ~4096 px
example"2K"enum"0.5K""1K""2K""4K"
- format string
Desired output image format. Optional; defaults to
pngwhen omitted. Mapped to the closest format the chosen model supports —webpfalls back topngon 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. Usetemporarywhen the user only wants the image: a short-lived URL, nothing saved to their account. Omit it, or usemanaged_asset, to store the image permanently in their Media Library. If the caller lacks upload permission, the image is returned astemporaryinstead, with awarningnotice.ShowHide child attributes of target
One of (discriminatortarget_type)ManagedAssetTarget target_type:
managed_assetStore 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:
temporaryReturn 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-bananaandideogrammodels and byqwen-image-3; silently ignored by the models that don't support it, which reportseedas null in the response.min 0example42 - 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.
defaultfalseexamplefalse - notification_url string
The webhook URL to notify when the generation is complete. Only relevant when
asyncis set to true.formaturiURIexample"https://path.to/webhook"
Responses
200 Image generated successfully (synchronous).
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 GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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
resultis filled in oncestatusiscompleted.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;resultis populated.failed: generation did not complete successfully.
example"completed"enum"pending""processing""completed""failed" - result objectnullable
The generated assets. Populated once
statusiscompleted.ShowHide child attributes of result
- assets GeneratedAsset[]Required
The generated assets. Currently a single asset is returned.
ShowHide child attributes of assets
Items GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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"
/generate/{cloud_name}/text_to_imagecurl -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"
}'{
"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"
}{
"data": {
"assets": [
{
"storage": {
"storage_type": "managed_asset",
"secure_url": "https://res.cloudinary.com/demo/image/upload/v1750000000/my-public-id.png",
"asset_id": "0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a",
"public_id": "my-public-id",
"resource_type": "image",
"type": "upload",
"version": 1750000000
},
"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"
}{
"data": {
"task_id": "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb",
"status": "pending"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00700",
"message": "The prompt was rejected by the content policy and could not be processed."
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "rate_limit_error",
"code": "MG_00602",
"message": "Generation limit exceeded. Upgrade your plan at https://console.cloudinary.com/app/image/generation/plans"
},
"limits": {
"addons_quota": [
{
"type": "image_generation",
"used_by_request": 0,
"remaining": 0,
"limit": 50
}
]
},
"notices": [
{
"severity": "blocking",
"text": "Your Image Generation credits are used up (50 of 50). This request did not generate an image. This is not a rate limit: retrying now returns this same response, and it changes only once credits are added, or the quota renews on plans that renew. Stop and tell the user their credits are finished, show them this link to add credits or review the plan: https://console.cloudinary.com/app/image/generation/plans, and once the balance changes re-run this same request unchanged."
}
],
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "server_error",
"code": "MG_00500",
"message": "internal error"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}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.
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 (byasset_id) or an externalurl. The platform accepts up to 4; a specific model may accept fewer — therecraft-v3-editandmai-imageedit models accept 1, and thegrok-imagineandqwen-imageedit models accept 3. Exceeding the selected model's capacity returns 400.min items 1max items 4ShowHide child attributes of reference_images
Items one ofA single reference image, in one of two mutually exclusive forms determined by
source_type:ManagedAssetReference: a managed asset in the caller's product environment, byasset_id(read permission is checked).UrlReference: an external image by HTTPSurl.
One of (discriminatorsource_type)ManagedAssetReference source_type:
managed_assetA 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:
urlA 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.
formaturiURIexample"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, ornano-banana-2-editfor image-to-image):ModelByFamily:family(+ optionaltier); the stable-over-time selector.ModelById: an explicitid, pinning one exact model.ModelAuto:mode: auto, letting the service choose the model for the request (+ optionalpreference).
ShowHide child attributes of model
One ofModelByFamily
Select a model by family and quality tier; a missing
tierdefaults tostandard.- 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
standardwhen 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
-editmodels accept reference images and are selectable only onimage_to_image; the others only ontext_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; onimage_to_imageit 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:widthandheightin pixels, for precise control.DeclarativeImageSize:aspect_ratio(and an optionalresolutiontier), 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_sizeentirely to use the model's default size.ShowHide child attributes of image_size
One ofDimensionsImageSize
Exact output dimensions in pixels. Both
widthandheightare required together.- width integerRequired
Output width in pixels.
min 64max 4096example1280 - height integerRequired
Output height in pixels.
min 64max 4096example720
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
1Kwhen omitted.0.5K: ~512 px1K: ~1024 px2K: ~2048 px4K: ~4096 px
example"2K"enum"0.5K""1K""2K""4K"
- format string
Desired output image format. Optional; defaults to
pngwhen omitted. Mapped to the closest format the chosen model supports —webpfalls back topngon 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. Usetemporarywhen the user only wants the image: a short-lived URL, nothing saved to their account. Omit it, or usemanaged_asset, to store the image permanently in their Media Library. If the caller lacks upload permission, the image is returned astemporaryinstead, with awarningnotice.ShowHide child attributes of target
One of (discriminatortarget_type)ManagedAssetTarget target_type:
managed_assetStore 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:
temporaryReturn 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-bananaandideogrammodels and byqwen-image-3; silently ignored by the models that don't support it, which reportseedas null in the response.min 0example42 - 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.
defaultfalseexamplefalse - notification_url string
The webhook URL to notify when the generation is complete. Only relevant when
asyncis set to true.formaturiURIexample"https://path.to/webhook"
Responses
200 Image generated successfully (synchronous).
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 GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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
resultis filled in oncestatusiscompleted.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;resultis populated.failed: generation did not complete successfully.
example"completed"enum"pending""processing""completed""failed" - result objectnullable
The generated assets. Populated once
statusiscompleted.ShowHide child attributes of result
- assets GeneratedAsset[]Required
The generated assets. Currently a single asset is returned.
ShowHide child attributes of assets
Items GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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"
/generate/{cloud_name}/image_to_imagecurl -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"
}
]
}'{
"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"
}{
"data": {
"task_id": "053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb",
"status": "pending"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "auth_error",
"code": "MG_00601",
"message": "Account does not have an active subscription for image generation. Subscribe at https://console.cloudinary.com/app/marketplace/details/image_generation"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00704",
"message": "reference asset '0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a' not found"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00015",
"message": "task not found"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00700",
"message": "The prompt was rejected by the content policy and could not be processed."
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "rate_limit_error",
"code": "MG_00602",
"message": "Generation limit exceeded. Upgrade your plan at https://console.cloudinary.com/app/image/generation/plans"
},
"limits": {
"addons_quota": [
{
"type": "image_generation",
"used_by_request": 0,
"remaining": 0,
"limit": 50
}
]
},
"notices": [
{
"severity": "blocking",
"text": "Your Image Generation credits are used up (50 of 50). This request did not generate an image. This is not a rate limit: retrying now returns this same response, and it changes only once credits are added, or the quota renews on plans that renew. Stop and tell the user their credits are finished, show them this link to add credits or review the plan: https://console.cloudinary.com/app/image/generation/plans, and once the balance changes re-run this same request unchanged."
}
],
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "server_error",
"code": "MG_00500",
"message": "internal error"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}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.
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
resultis filled in oncestatusiscompleted.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;resultis populated.failed: generation did not complete successfully.
example"completed"enum"pending""processing""completed""failed" - result objectnullable
The generated assets. Populated once
statusiscompleted.ShowHide child attributes of result
- assets GeneratedAsset[]Required
The generated assets. Currently a single asset is returned.
ShowHide child attributes of assets
Items GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 NoticeA 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.
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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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.
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 NoticeA 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"
/generate/{cloud_name}/tasks/{task_id}curl 'https://api.cloudinary.com/v2/generate/CLOUD_NAME/tasks/053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb' \
-u 'API_KEY:API_SECRET'{
"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"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00001",
"message": "missing parameters",
"details": {
"parameters": [
"prompt"
]
}
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00704",
"message": "reference asset '0d6f8e1c2b3a4d5e6f7a8b9c0d1e2f3a' not found"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "user_error",
"code": "MG_00015",
"message": "task not found"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "rate_limit_error",
"code": "MG_00602",
"message": "Generation limit exceeded. Upgrade your plan at https://console.cloudinary.com/app/image/generation/plans"
},
"limits": {
"addons_quota": [
{
"type": "image_generation",
"used_by_request": 0,
"remaining": 0,
"limit": 50
}
]
},
"notices": [
{
"severity": "blocking",
"text": "Your Image Generation credits are used up (50 of 50). This request did not generate an image. This is not a rate limit: retrying now returns this same response, and it changes only once credits are added, or the quota renews on plans that renew. Stop and tell the user their credits are finished, show them this link to add credits or review the plan: https://console.cloudinary.com/app/image/generation/plans, and once the balance changes re-run this same request unchanged."
}
],
"request_id": "17c3b70c5096df0e77e838323abb7029"
}{
"error": {
"category": "server_error",
"code": "MG_00500",
"message": "internal error"
},
"request_id": "17c3b70c5096df0e77e838323abb7029"
}Models
Show schema
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, ornano-banana-2-editfor image-to-image):ModelByFamily:family(+ optionaltier); the stable-over-time selector.ModelById: an explicitid, pinning one exact model.ModelAuto:mode: auto, letting the service choose the model for the request (+ optionalpreference).
ShowHide child attributes of model
One ofModelByFamily
Select a model by family and quality tier; a missing
tierdefaults tostandard.- 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
standardwhen 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
-editmodels accept reference images and are selectable only onimage_to_image; the others only ontext_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; onimage_to_imageit 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:widthandheightin pixels, for precise control.DeclarativeImageSize:aspect_ratio(and an optionalresolutiontier), 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_sizeentirely to use the model's default size.ShowHide child attributes of image_size
One ofDimensionsImageSize
Exact output dimensions in pixels. Both
widthandheightare required together.- width integerRequired
Output width in pixels.
min 64max 4096example1280 - height integerRequired
Output height in pixels.
min 64max 4096example720
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
1Kwhen omitted.0.5K: ~512 px1K: ~1024 px2K: ~2048 px4K: ~4096 px
example"2K"enum"0.5K""1K""2K""4K"
- format string
Desired output image format. Optional; defaults to
pngwhen omitted. Mapped to the closest format the chosen model supports —webpfalls back topngon 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. Usetemporarywhen the user only wants the image: a short-lived URL, nothing saved to their account. Omit it, or usemanaged_asset, to store the image permanently in their Media Library. If the caller lacks upload permission, the image is returned astemporaryinstead, with awarningnotice.ShowHide child attributes of target
One of (discriminatortarget_type)ManagedAssetTarget target_type:
managed_assetStore 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:
temporaryReturn 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-bananaandideogrammodels and byqwen-image-3; silently ignored by the models that don't support it, which reportseedas null in the response.min 0example42 - 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.
defaultfalseexamplefalse - notification_url string
The webhook URL to notify when the generation is complete. Only relevant when
asyncis set to true.formaturiURIexample"https://path.to/webhook"
Show schema
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).
"png""jpeg" "png" "webp"Show schema
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.
42Show schema
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.
falseexample falseShow schema
The webhook URL to notify when the generation is complete. Only relevant when async is set to true.
uri URIexample "https://path.to/webhook"Show schema
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 (byasset_id) or an externalurl. The platform accepts up to 4; a specific model may accept fewer — therecraft-v3-editandmai-imageedit models accept 1, and thegrok-imagineandqwen-imageedit models accept 3. Exceeding the selected model's capacity returns 400.min items 1max items 4ShowHide child attributes of reference_images
Items one ofA single reference image, in one of two mutually exclusive forms determined by
source_type:ManagedAssetReference: a managed asset in the caller's product environment, byasset_id(read permission is checked).UrlReference: an external image by HTTPSurl.
One of (discriminatorsource_type)ManagedAssetReference source_type:
managed_assetA 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:
urlA 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.
formaturiURIexample"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, ornano-banana-2-editfor image-to-image):ModelByFamily:family(+ optionaltier); the stable-over-time selector.ModelById: an explicitid, pinning one exact model.ModelAuto:mode: auto, letting the service choose the model for the request (+ optionalpreference).
ShowHide child attributes of model
One ofModelByFamily
Select a model by family and quality tier; a missing
tierdefaults tostandard.- 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
standardwhen 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
-editmodels accept reference images and are selectable only onimage_to_image; the others only ontext_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; onimage_to_imageit 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:widthandheightin pixels, for precise control.DeclarativeImageSize:aspect_ratio(and an optionalresolutiontier), 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_sizeentirely to use the model's default size.ShowHide child attributes of image_size
One ofDimensionsImageSize
Exact output dimensions in pixels. Both
widthandheightare required together.- width integerRequired
Output width in pixels.
min 64max 4096example1280 - height integerRequired
Output height in pixels.
min 64max 4096example720
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
1Kwhen omitted.0.5K: ~512 px1K: ~1024 px2K: ~2048 px4K: ~4096 px
example"2K"enum"0.5K""1K""2K""4K"
- format string
Desired output image format. Optional; defaults to
pngwhen omitted. Mapped to the closest format the chosen model supports —webpfalls back topngon 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. Usetemporarywhen the user only wants the image: a short-lived URL, nothing saved to their account. Omit it, or usemanaged_asset, to store the image permanently in their Media Library. If the caller lacks upload permission, the image is returned astemporaryinstead, with awarningnotice.ShowHide child attributes of target
One of (discriminatortarget_type)ManagedAssetTarget target_type:
managed_assetStore 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:
temporaryReturn 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-bananaandideogrammodels and byqwen-image-3; silently ignored by the models that don't support it, which reportseedas null in the response.min 0example42 - 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.
defaultfalseexamplefalse - notification_url string
The webhook URL to notify when the generation is complete. Only relevant when
asyncis set to true.formaturiURIexample"https://path.to/webhook"
Show schema
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, byasset_id(read permission is checked).UrlReference: an external image by HTTPSurl.
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.
formaturiURIexample"https://example.com/product.png"
Show schema
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"
Show schema
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.
formaturiURIexample"https://example.com/product.png"
Show schema
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(+ optionaltier); the stable-over-time selector.ModelById: an explicitid, pinning one exact model.ModelAuto:mode: auto, letting the service choose the model for the request (+ optionalpreference).
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
standardwhen 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
-editmodels accept reference images and are selectable only onimage_to_image; the others only ontext_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"
Show schema
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
standardwhen omitted.example"premium"enum"standard""premium"
Show schema
Pin an exact model by ID, bypassing family/tier.
- id stringRequired
Exact model identifier; overrides family/tier when provided. The
-editmodels accept reference images and are selectable only onimage_to_image; the others only ontext_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"
Show schema
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"
Show schema
Desired output size, given in one of two mutually exclusive forms:
DimensionsImageSize:widthandheightin pixels, for precise control.DeclarativeImageSize:aspect_ratio(and an optionalresolutiontier), 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.
DimensionsImageSize
Exact output dimensions in pixels. Both width and height are required together.
- width integerRequired
Output width in pixels.
min 64max 4096example1280 - height integerRequired
Output height in pixels.
min 64max 4096example720
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
1Kwhen omitted.0.5K: ~512 px1K: ~1024 px2K: ~2048 px4K: ~4096 px
example"2K"enum"0.5K""1K""2K""4K"
Show schema
Exact output dimensions in pixels. Both width and height are required together.
- width integerRequired
Output width in pixels.
min 64max 4096example1280 - height integerRequired
Output height in pixels.
min 64max 4096example720
Show schema
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
1Kwhen omitted.0.5K: ~512 px1K: ~1024 px2K: ~2048 px4K: ~4096 px
example"2K"enum"0.5K""1K""2K""4K"
Show schema
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.
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"
Show schema
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"
Show schema
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"
Show schema
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.
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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 3339 date-timeexample"2026-06-25T12:50:26Z"
Show schema
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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
Show schema
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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 3339 date-timeexample"2026-06-25T12:50:26Z"
Show schema
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 GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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"
Show schema
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 GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 3339 date-timeexample"2026-04-21T14:30:00Z"
Show schema
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 requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 3339 date-timeexample"2026-04-21T14:30:00Z"
Show schema
Identifies the model that produced a generation result.
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.example"flux-2-pro"
Show schema
The status of an async generation task.
pending: accepted and queued, not yet started.processing: generation is in progress.completed: generation finished;resultis populated.failed: generation did not complete successfully.
"completed""pending" "processing" "completed" "failed"Show schema
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;resultis populated.failed: generation did not complete successfully.
example"completed"enum"pending""processing""completed""failed" - result objectnullable
The generated assets. Populated once
statusiscompleted.ShowHide child attributes of result
- assets GeneratedAsset[]Required
The generated assets. Currently a single asset is returned.
ShowHide child attributes of assets
Items GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
Show schema
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
resultis filled in oncestatusiscompleted.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;resultis populated.failed: generation did not complete successfully.
example"completed"enum"pending""processing""completed""failed" - result objectnullable
The generated assets. Populated once
statusiscompleted.ShowHide child attributes of result
- assets GeneratedAsset[]Required
The generated assets. Currently a single asset is returned.
ShowHide child attributes of assets
Items GeneratedAssetA 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 onlystorage.- storage one ofRequired
Where the generated asset is actually stored, determined by
storage_type. Usually matches the requesttarget; amanaged_assetrequest falls back totemporarywhen the caller lacks upload permission.secure_urlis always present.ShowHide child attributes of storage
One of (discriminatorstorage_type)ManagedAssetStorage storage_type:
managed_assetA generated asset stored as a permanent managed asset. Reference it in other Cloudinary APIs by
asset_id, or by theresource_type/type/public_idtriple.- 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.
formaturiURIexample"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.
formatint64Signed 64-bit integerexample1750000000
TemporaryStorage storage_type:
temporaryA 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.
formaturiURIexample"https://upload-global.cloudinary.com/v2/demo/uploads/a78a2e043c2da0b50a98961d60a8b05a/stream" - expires_at stringRequired
Time in UTC when secure_url stops being valid.
formatdate-timeRFC 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.
example1024 - height integer
The height of the generated image in pixels; zero if the model doesn't provide dimensions.
example768 - bytes integer
The size of the generated image in bytes.
formatint64Signed 64-bit integerexample2048576 - model Model
Identifies the model that produced a generation result.
ShowHide child attributes of model
- family stringRequired
The family this model belongs to.
nonewhen the model is not part of any family.A family holds exactly two tiers (
standardandpremium), so the family/tier taxonomy names only part of the roster. The remaining models are selected byidalone and are not part of any family, which is reported asnonerather 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 byfamilyandtieror pinned byid.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.
nonewhen the model is not part of any family. Seefamily.example"premium" - id stringRequired
The exact model identifier used for generation. Always a concrete model, and the reliable field to key on: unlike
familyandtier, it is nevernone.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.
example42 - created_at string
The timestamp when the image was generated.
formatdate-timeRFC 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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
- 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 NoticeA 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"
Show schema
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 NoticeA 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"
Show schema
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.
Show schema
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.
"user_error""user_error" "auth_error" "server_error" "rate_limit_error"Show schema
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.
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"
Show schema
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"
Show schema
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 AddonQuotaCredit 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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50
Show schema
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.
example1 - remaining integerRequirednullable
Credits remaining in the current period.
example48 - limit integerRequirednullable
Credits available per period.
example50