For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Accepts a P-Image Ideogram 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.
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.
Request
A request to generate an image with P-Image Ideogram.
promptstringRequired
The prompt for image generation. Accepts either natural language or
a structured Ideogram 4.0 JSON prompt; the server detects which was supplied.
prompt_upsamplingenumOptional
Controls magic-prompt (prompt upsampling). Defaults to AUTO.
Allowed values:
seedinteger or nullOptional
Random seed for reproducibility.
qualityenumOptional
The generation quality level. Defaults to MEDIUM.
Allowed values:
resolutionenumOptional
The output-size tier. Defaults to 1K.
Allowed values:
aspect_ratioenumOptional
The output aspect ratio. Defaults to 1x1.
custom_widthinteger or nullOptional
Optional. An exact output width in pixels, used together with
`custom_height` for output sizes outside the preset tiers. Must be
a positive multiple of 16 between 16 and 4096, and
`custom_width` × `custom_height` must not exceed 4,194,304 pixels
(2048×2048). Cannot be combined with `resolution` or
`aspect_ratio`; the request is billed at the resolution tier
matching its total pixel count.
custom_heightinteger or nullOptional
Optional. An exact output height in pixels, used together with
custom_width. See custom_width for the accepted range and
billing behavior.
enable_copyright_detectionboolean or nullOptional
Optional. Opt this request into post-generation copyright detection.
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
Accepts a P-Image Ideogram 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.
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.
Optional. An exact output width in pixels, used together with
custom_height for output sizes outside the preset tiers. Must be
a positive multiple of 16 between 16 and 4096, and
custom_width × custom_height must not exceed 4,194,304 pixels
(2048×2048). Cannot be combined with resolution or
aspect_ratio; the request is billed at the resolution tier
matching its total pixel count.
