API Reference

Generate with Ideogram 3.0

Generates images synchronously based on a given prompt and optional parameters using the Ideogram 3.0 model.

Images links are available for a limited period of time; if you would like to keep the image, you must download it.

Authentication

Api-Keystring

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

Request

A request to generate an image with Ideogram 3.0.
promptstringRequired
The prompt to use to generate the image.
seedintegerOptional0-2147483647
Random seed. Set for reproducible generation.
resolutionenumOptional
The resolutions supported for Ideogram 3.0.
aspect_ratioenumOptional
The aspect ratio to use for image generation, which determines the image's resolution. Cannot be used in conjunction with resolution. Defaults to 1x1.
rendering_speedenumOptionalDefaults to DEFAULT
The rendering speed to use.
Allowed values:
magic_promptenumOptional
Determine if MagicPrompt should be used in generating the request or not.
Allowed values:
negative_promptstringOptional
Description of what to exclude from an image. Descriptions in the prompt take precedence to descriptions in the negative prompt.
num_imagesintegerOptional1-8Defaults to 1
Number of images to generate.
color_paletteobjectOptional

A color palette for generation, must EITHER be specified via one of the presets (name) or explicitly via hexadecimal representations of the color with optional weights (members). Not supported by V_1, V_1_TURBO, V_2A and V_2A_TURBO models.

style_codeslist of stringsOptional

A list of 8 character hexadecimal codes representing the style of the image. Cannot be used in conjunction with style_reference_images or style_type.

style_typeenumOptionalDefaults to GENERAL
The style type to generate with.
Allowed values:
style_presetenumOptional
A predefined style preset that applies a specific artistic style to the generated image.
custom_model_uristringOptional

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, and style_type is not required.

style_reference_imagesfilesOptional

A set of images to use as style references (max size 25MB per image; the whole request must stay under 50MB). The images should be in JPEG, PNG or WebP format.

character_reference_imagesfilesOptional

Generations with character reference are subject to the character reference pricing. A set of images to use as character references (max size 25MB per image; the whole request must stay under 50MB), currently only supports 1 character reference image. The images should be in JPEG, PNG or WebP format.

character_reference_images_maskfilesOptional

Optional masks for character reference images. When provided, must match the number of character_reference_images. Each mask should be a grayscale image of the same dimensions as the corresponding character reference image. The images should be in JPEG, PNG or WebP format.

Response

Image(s) generated successfully.

createddatetime
The time the request was created.
datalist of objects

A list of ImageObjects that contain the generated image(s).

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
429
Too Many Requests Error