Skip to navigation
Tools

Ad Variations

Creates on-brand variations of an ad along one axis, preserving logos, brand colors, the product, and all on-image text. Upload the source creative as image using multipart/form-data and choose a variation_type. Returns a generation_id; poll GET /v2/generations/{generation_id} or supply a webhook_url.

Authentication

Api-Keystring

API key for access control. Use in the header with the name "Api-Key"

Request

The source creative and the variation axis.
imagefileRequired

The source creative to vary (max size 25MB). JPEG, PNG, and WEBP formats are supported. Multipart requests only. Each output keeps the source's aspect ratio, capped at 3:1 between the long and short sides.

variation_typeenumRequired

The axis to vary. people replaces the people in the ad with different talent. setting moves the same subject and product to a different environment. group_size changes how many people appear. scene shifts the moment or occasion (time of day, season, or activity).

Allowed values:
promptstringOptional
Optional direction to steer the variation, for example "set it on a beach" or "make the models older". Anything it explicitly asks to change takes priority over the default preservation rules.
qualityenumOptional
The quality tier for the edit. Higher tiers may improve detail and take longer to complete.
Allowed values:
num_imagesintegerOptional1-4Defaults to 1
The number of variations to generate along the requested axis.
webhook_urlstringOptionalformat: "uri"<=2048 characters

HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a JSON POST to this URL once all images for the request have finished generating. The body mirrors the synchronous generate response: request_id, created, and a data array containing every generated image (url, prompt, resolution, seed, is_image_safe). Each delivery is signed with Ed25519 and verifiable against the public keys at https://api.ideogram.ai/v1/.well-known/jwks.json. Must be HTTPS; private and loopback hosts and the cloud metadata service are rejected.

Response

Ad variation accepted for asynchronous processing.
generation_idstring

URL-safe base64 ID accepted by the generation polling endpoint.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error