Sign in

v4

latestOpenAPI 3.0.22026-08-02109239415.7 KB
generate

Generate an editable V4 HTML design asynchronously via webhook

Accepts an Ideogram 4.0 HTML design request for asynchronous processing and returns immediately with a request_id. The generated design is POSTed to the supplied webhook_url once ready.

post/v1/ideogram-v4/async/generate-design

Query parameters

webhook_urlstring uri required

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

promptstring required

The text prompt for editable design generation.

seedinteger nullable

Random seed for reproducibility.

magic_prompt_option'AUTO' | 'ON' | 'OFF'

Determine if MagicPrompt should be used in generating the request or not.

magic_prompt_system_prompt_config_idstring

A base64url-encoded magic prompt system prompt config ID to use for this request.

resolution'1024x1024' | '896x1120' | '1120x896' | '864x1152' | '1152x864' | '832x1248' | '1248x832' | '800x1280' | '1280x800' | '720x1280' | '1280x720' | '720x1440' | '1440x720'

The resolutions supported for Ideogram 4.0 layout-to-image and design generation.

rendering_speed'FLASH' | 'TURBO' | 'BALANCED' | 'DEFAULT' | 'QUALITY'

The rendering speed to use.

inspiration_reference_imagesstring[]

Experimental. Up to 4 static inspiration images used as transferable visual style references for V4 layout-to-image design. Images are not edit targets and are not inserted into the generated HTML layout. Supported formats are JPEG, PNG, and WebP (max size 10MB each). Animated images are not supported.

inspiration_reference_model'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-7' nullable

Experimental. Model to use for the inspiration vision prepass.

artifact_generation_model'claude-sonnet-4-6' | 'claude-opus-4-6' | 'claude-opus-4-7' nullable

Experimental. Model to use for the HTML/layout and base-plate handoff generation call.

layout2image_variant'opus_4_7' | 'separate_image_layer' | 'bbox_aware' nullable

Experimental. Staging only. Select a v4 layout-to-image pipeline variant. Omit for the default v4l2i path. Rejected on production.

response_type'layered' | 'url' | 'binary' | 'html' nullable

layered (default): full editable design payload with text layers and HTML. url: JSON with an expiring link to the final composited cover image. binary: raw PNG bytes of the final composited cover image (Content-Type image/png). html: raw HTML document of the generated layout (Content-Type text/html).

Example request

{
  "magic_prompt_option": "ON",
  "resolution": "1024x1024"
}

Response

Request accepted for asynchronous delivery.

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