---
title: "Generate an editable V4 HTML design asynchronously via webhook"
method: POST
path: "/v1/ideogram-v4/async/generate-design"
tags: ["generate"]
---

# Generate an editable V4 HTML design asynchronously via webhook

`POST /v1/ideogram-v4/async/generate-design`

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.

## Query parameters

- `webhook_url` string, 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.

## Request body

- GenerateDesignRequestV4
  - `prompt` string, required — The text prompt for editable design generation.
  - `seed` integer, 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_id` string — 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_images` string[] — 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).

## Response `200`

Request accepted for asynchronous delivery.

- AsyncImageGenerationResponseV4 — Acknowledgement returned by the async (webhook) generation endpoints. The request is accepted for asynchronous processing and the generated images are POSTed to the supplied `webhook_url` once ready; this body carries only the generation_id so the caller can correlate the eventual webhook delivery.
  - `generation_id` string, 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.

## Other responses

- `400` — Invalid input provided.
- `401` — Not authorized.
- `422` — Prompt failed the safety check.
- `429` — Too many requests.

---

[API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/bd40f367a834/schema)