Sign in

e7f5f98d7fdb

latestOpenAPI 3.0.22026-08-13115250435.7 KB
generate

Generate with Ideogram 4.0 (Transparent Background) asynchronously

Accepts an Ideogram 4.0 transparent-background 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 the synchronous /v1/ideogram-v4/generate-transparent endpoint for the request semantics, including output_resolution tiers.

See Webhooks for the delivery payload and how to verify webhook signatures.

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

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

text_promptstring

A natural-language prompt for image generation. When supplied, magic-prompt is enabled automatically. Mutually exclusive with json_prompt.

seedinteger nullable

Random seed for reproducibility.

magic_prompt_system_prompt_config_idstring

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.

aspect_ratio'AUTO' | '1x4' | '1x3' | '1x2' | '9x16' | '10x16' | '2x3' | '3x4' | '4x5' | '1x1' | '5x4' | '4x3' | '3x2' | '16x10' | '16x9' | '2x1' | '3x1' | '4x1'

The aspect ratio for an Ideogram 4.0 magic prompt. AUTO lets the model select the most suitable ratio from the prompt; any other value pins the ratio. The non-AUTO values are the buckets the 4.0 model supports.

output_resolution'1K' | '2K' | '4K' | '8K'

The output resolution tier for the generated image. Tiers are total-pixel budgets matching a square of the named size (for example, 8K delivers at most 8192x8192 total pixels); wide and tall aspect ratios keep the same pixel budget, so a single dimension may exceed the named size. Defaults to 1K.

rendering_speed'TURBO' | 'DEFAULT' | 'QUALITY'

The rendering speed to use. Defaults to DEFAULT.

enable_copyright_detectionboolean 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.

Example request

{
  "json_prompt": {
    "high_level_description": "high_level_description",
    "style_description": {
      "photo": "photo",
      "art_style": "art_style",
      "medium": "medium",
      "aesthetics": "aesthetics",
      "lighting": "lighting",
      "color_palette": [
        "#FFD700",
        "#FFD700"
      ]
    },
    "compositional_deconstruction": {
      "background": "background",
      "elements": [
        {
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "type": "obj",
          "desc": "desc",
          "color_palette": [
            "#FFD700",
            "#FFD700"
          ]
        },
        {
          "bbox": [
            0,
            0,
            1000,
            1000
          ],
          "type": "obj",
          "desc": "desc",
          "color_palette": [
            "#FFD700",
            "#FFD700"
          ]
        }
      ]
    },
    "tags": [
      "tags",
      "tags"
    ]
  }
}

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