Sign in

v7

latestOpenAPI 3.0.22026-08-08114248430.1 KB
generate

Reframe a source image to a target size asynchronously

Accepts the same request as POST /v1/ad-resizer for asynchronous processing and returns immediately with a generation_id. Poll GET /v1/generations/{generation_id} to retrieve the reframed image(s); the polled result is the final image, already cropped to the requested aspect ratio. If a webhook_url is supplied, the images are additionally POSTed to it once ready.

Supply the source image as either an AssetIdentifier reference (image_asset_identifier) or the raw image bytes directly (image, multipart requests only). Provide exactly one of the two; supplying both, or neither, is rejected with a 400.

The target resolution (WIDTHxHEIGHT) sets the target aspect ratio and selects the reframing layout, so it is required.

The model is fixed by the route, so no model field is accepted.

post/v1/async/ad-resizer

Query parameters

webhook_urlstring uri

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.

Example:https://api.example.com/webhooks/ideogram

Request body

imagestring binary

The source image to reframe (max size 10MB), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only. Provide exactly one of image_asset_identifier or image.

resolution'300x250' | '336x280' | '300x600' | '1080x1080' | '1080x1350' | '1080x1920' | '1920x1080' | '728x90' | '160x600' | '970x250' | '320x50' | '300x50' | '320x100' | '1800x900' | '2400x2400' | '1200x3500' required

Target ad resolution, formatted as WIDTHxHEIGHT. Must be one of the supported ad resolutions listed above; any other value is rejected with a 400. Each returned image has exactly these pixel dimensions.

promptstring

Optional edit instruction to apply while reframing, for example "remove the logo" or "put the price bottom-right".

quality'LOW' | 'MEDIUM' | 'HIGH'
num_imagesinteger

The number of reframed variations to generate.

store_assetsboolean

Reserved for a future release: accepted for forward compatibility but not yet applied. Resulting assets are not stored to your account regardless of this value.

Example request

{
  "image_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  }
}

Response

Request accepted for asynchronous processing.

generation_idstring required

URL-safe base64 ID of the accepted generation. Matches the generation_id field delivered in the webhook payload, and the generation_id accepted by the generation polling endpoint.

Example response

{
  "generation_id": "generation_id"
}