Sign in

v4

latestOpenAPI 3.0.22026-08-02109239415.7 KB
generate

Generate with Ideogram 4.0 asynchronously

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 for the delivery payload and how to verify webhook signatures.

post/v1/ideogram-v4/async/generate

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.

custom_model_uristring

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_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"
    ]
  },
  "custom_model_uri": "model/my-custom-model/version/0",
  "resolution": "2048x2048"
}

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