Sign in

v4

latestOpenAPI 3.0.22026-08-02109239415.7 KB
generate

Generate with P-Image Ideogram asynchronously

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.

post/v1/async/text-to-image/p-image-ideogram

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

promptstring required

The prompt for image generation. Accepts either natural language or a structured Ideogram 4.0 JSON prompt; the server detects which was supplied.

prompt_upsampling'AUTO' | 'ON' | 'OFF'

Determine if MagicPrompt should be used in generating the request or not.

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.

quality'VERY_LOW' | 'LOW' | 'MEDIUM' | 'HIGH'

The generation quality level. Higher levels may use more inference steps or additional prompt processing.

resolution'1K' | '2K'

The output-size tier for P-Image Ideogram.

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

The aspect ratio to use for image generation, which determines the image's resolution. Cannot be used in conjunction with resolution. Defaults to 1x1.

custom_widthinteger nullable

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 nullable

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 nullable

Optional. Opt this request into post-generation copyright detection.

Example request

{
  "prompt_upsampling": "ON"
}

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