Generate with Ideogram 4.0 (Transparent Background) asynchronously | Ideogram

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.

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](/ideogram-api/webhooks) for the delivery payload and how to verify webhook signatures.

Authentication

Api-Keystring

API key for access control. Use in the header with the name “Api-Key”

Query parameters

webhook_urlstringOptionalformat: "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.

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

A request to generate a transparent-background image with Ideogram 4.0.

text_promptstringOptional

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

json_promptobjectOptional

A structured prompt that conforms to the Ideogram 4.0 JSON contract. When supplied, magic-prompt is disabled and the structured prompt is consumed by the diffusion model directly, except that compositional_deconstruction.background is replaced with a transparent-background directive. Mutually exclusive with text_prompt.

aspect_ratioenumOptionalDefaults to AUTO

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_resolutionenumOptionalDefaults to 1K

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.

Allowed values:

rendering_speedenumOptionalDefaults to DEFAULT

The rendering speed to use. Defaults to DEFAULT.

Allowed values:

enable_copyright_detectionboolean or nullOptional

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

Request accepted for asynchronous delivery.

generation_idstring

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.

Errors

400

Bad Request Error

401

Unauthorized Error

422

Unprocessable Entity Error

429

Too Many Requests Error