latestOpenAPI 3.0.22026-08-22136296577.7 KB

015774bae5bc

edit-workflow

Advertisement Resizer

Reframes the source creative to the exact requested ad resolution, regenerating the layout so text and key elements stay legible at the target size.

The request is processed asynchronously. Poll GET /v1/generations/{generation_id} with the returned generation_id until the generation is completed or failed. The completed generation reports the exact amount billed for the request in usage_cost_usd_micros.

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

post/v2/tool/ad-resizer

Request body

imagestring binary

The source creative to reframe (max size 25MB), 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' | '2880x2880' | '2560x3200' | '3200x2560' | '2448x3264' | '3264x2448' | '2336x3504' | '3504x2336' | '2240x3584' | '3584x2240' | '2160x3840' | '3840x2160' | '1920x3840' | '3840x1920' | '1280x3840' | '3840x1280' 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'VERY_LOW' | 'LOW' | 'MEDIUM' | 'HIGH'

The generation quality level. Higher levels may use more inference steps or additional prompt processing.

num_imagesinteger

The number of reframed variations to generate.

privateboolean

If true, the user is requesting private generation. If omitted, this defaults to the user's plan entitlement. Enterprise generations are always private.

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 request

{
  "image_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  },
  "webhook_url": "https://api.example.com/webhooks/ideogram"
}

Response

Ad resize accepted for asynchronous processing.

generation_idstring required

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

Example response

{
  "generation_id": "generation_id"
}