---
title: "Generate with Ideogram 4.0 asynchronously"
method: POST
path: "/v1/ideogram-v4/async/generate"
tags: ["generate"]
---

# Generate with Ideogram 4.0 asynchronously

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

Accepts an Ideogram 4.0 generation request for asynchronous processing and
returns immediately with a generation_id. Poll `GET /v1/generations/{generation_id}`
to retrieve the result. If a `webhook_url` is supplied, the generated images are
additionally POSTed to it once ready, in a payload that mirrors the synchronous
response with an added generation_id for correlation.

See [Webhooks](/ideogram-api/webhooks) for the delivery payload and how to verify webhook signatures.

## Query parameters

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

## Request body

- GenerateImageRequestV4 — Request body for Ideogram 4.0 image generation. Supply exactly one of `text_prompt` or `json_prompt`. When `text_prompt` is supplied, magic-prompt is applied automatically. When `json_prompt` is supplied, magic-prompt is skipped and the structured prompt is consumed directly.
  - `text_prompt` string — A natural-language prompt for image generation. When supplied, magic-prompt is enabled automatically. Mutually exclusive with `json_prompt`.
  - `json_prompt` V4JsonPrompt — Structured prompt for Ideogram 4.0 generation. When `json_prompt` is supplied, magic-prompt is disabled and the diffusion model consumes the JSON contract directly. Mutually exclusive with `text_prompt` and the legacy `prompt` field.
    - `high_level_description` string, required — One- or two-sentence overall description of the desired image.
    - `style_description` V4StyleDescription — Optional style description supplied alongside a V4 JSON prompt.
      - `aesthetics` string — Aesthetic notes (mood, vibe, references).
      - `art_style` string — Optional art-style hint (e.g., illustration, oil painting).
      - `lighting` string — Lighting description.
      - `medium` string — Medium description (e.g., photograph, digital art).
      - `photo` string — Optional photographic style notes (e.g., lens, film stock).
      - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock.
    - `compositional_deconstruction` V4CompositionalDeconstruction, required — The compositional breakdown of a V4 prompt — background plus an ordered list of elements.
      - `background` string, required — Description of the background of the scene.
      - `elements` V4PromptElement[], required — Ordered list of elements (objects and text) composing the scene.
        - union — A single element in the V4 prompt's compositional deconstruction. Discriminated by the `type` field.
          - object — A non-text element (object, character, background detail) in the V4 prompt layout.
            - `type` 'obj', required — Discriminator. Must be `obj`.
            - `bbox` integer[] — Bounding box for an element, expressed as four integers in `[0, 1000]` with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are normalized so the canvas is `1000 x 1000` regardless of the final resolution.
            - `desc` string, required — Description of the object element.
            - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock.
          - object — A text element to render in the V4 prompt layout.
            - `type` 'text', required — Discriminator. Must be `text`.
            - `bbox` integer[] — Bounding box for an element, expressed as four integers in `[0, 1000]` with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are normalized so the canvas is `1000 x 1000` regardless of the final resolution.
            - `text` string, required — The literal text to render in the image.
            - `desc` string, required — Description of the text element (style, role, placement notes).
            - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock.
    - `tags` string[] — Round-trip metadata surfaced by the describe endpoint when `strip_tags=false`. Ignored by the v4 sampler on generate input.
  - `seed` integer, nullable — Random seed for reproducibility.
  - `magic_prompt_system_prompt_config_id` string — A base64url-encoded magic prompt system prompt config ID to use for this request. Honored when `text_prompt` is supplied. Ignored when `json_prompt` is supplied.
  - `custom_model_uri` string — A custom model URI in the format model/<model_name>/version/<version_name>. When provided, the model version and style will be resolved from this URI.
  - `resolution` '2048x2048' | '1440x2880' | '2880x1440' | '1664x2496' | '2496x1664' | '1792x2240' | '2240x1792' | '1440x2560' | '2560x1440' | '1600x2560' | '2560x1600' | '1728x2304' | '2304x1728' | '1296x3168' | '3168x1296' | '1152x2944' | '2944x1152' | '1248x3328' | '3328x1248' | '1280x3072' | '3072x1280' | '1024x3072' | '3072x1024' | '1024x1024' | '896x1120' | '1120x896' | '864x1152' | '1152x864' | '832x1248' | '1248x832' | '800x1280' | '1280x800' | '720x1280' | '1280x720' | '720x1440' | '1440x720' | '512x1536' | '1536x512' — The 1K and 2K resolutions supported for Ideogram 4.0 image generation.
  - `rendering_speed` 'FLASH' | 'TURBO' | 'BALANCED' | 'DEFAULT' | 'QUALITY' — The rendering speed to use.
  - `enable_copyright_detection` boolean, nullable — Optional. Opt this request into post-generation copyright detection (Hive likeness + logo checks). The effective gate is the OR of this field and the organization's `copyright_detection_enabled` setting on `/api`. See GenerateImageRequestV3 for details.

## 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/versions/bd40f367a834/schema)