Sign in

v4

latestOpenAPI 3.0.22026-08-02109239415.7 KB
generate

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.

post/v1/ideogram-v3/generate

Request body

promptstring required

The prompt to use to generate the image.

seedinteger

Random seed. Set for reproducible generation.

resolution'512x1536' | '576x1408' | '576x1472' | '576x1536' | '640x1344' | '640x1408' | '640x1472' | '640x1536' | '704x1152' | '704x1216' | '704x1280' | '704x1344' | '704x1408' | '704x1472' | '736x1312' | '768x1088' | '768x1216' | '768x1280' | '768x1344' | '800x1280' | '832x960' | '832x1024' | '832x1088' | '832x1152' | '832x1216' | '832x1248' | '864x1152' | '896x960' | '896x1024' | '896x1088' | '896x1120' | '896x1152' | '960x832' | '960x896' | '960x1024' | '960x1088' | '1024x832' | '1024x896' | '1024x960' | '1024x1024' | '1088x768' | '1088x832' | '1088x896' | '1088x960' | '1120x896' | '1152x704' | '1152x832' | '1152x864' | '1152x896' | '1216x704' | '1216x768' | '1216x832' | '1248x832' | '1280x704' | '1280x768' | '1280x800' | '1312x736' | '1344x640' | '1344x704' | '1344x768' | '1408x576' | '1408x640' | '1408x704' | '1472x576' | '1472x640' | '1472x704' | '1536x512' | '1536x576' | '1536x640'

The resolutions supported for Ideogram 3.0.

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.

rendering_speed'FLASH' | 'TURBO' | 'BALANCED' | 'DEFAULT' | 'QUALITY'

The rendering speed to use.

magic_prompt'AUTO' | 'ON' | 'OFF'

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

magic_prompt_system_prompt_config_idstring

A base64url-encoded magic prompt system prompt config ID to use for this request.

negative_promptstring

Description of what to exclude from an image. Descriptions in the prompt take precedence to descriptions in the negative prompt.

num_imagesinteger

Number of images to generate.

style_codesStyleCode[]

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_type'AUTO' | 'GENERAL' | 'REALISTIC' | 'DESIGN' | 'CUSTOM' | 'FICTION' | 'STYLIZED'

The style type to generate with.

style_preset'80S_ILLUSTRATION' | '90S_NOSTALGIA' | 'ABSTRACT_ORGANIC' | 'ANALOG_NOSTALGIA' | 'ART_BRUT' | 'ART_DECO' | 'ART_POSTER' | 'AURA' | 'AVANT_GARDE' | 'BAUHAUS' | 'BLUEPRINT' | 'BLURRY_MOTION' | 'BRIGHT_ART' | 'C4D_CARTOON' | 'CHILDRENS_BOOK' | 'COLLAGE' | 'COLORING_BOOK_I' | 'COLORING_BOOK_II' | 'CUBISM' | 'DARK_AURA' | 'DOODLE' | 'DOUBLE_EXPOSURE' | 'DRAMATIC_CINEMA' | 'EDITORIAL' | 'EMOTIONAL_MINIMAL' | 'ETHEREAL_PARTY' | 'EXPIRED_FILM' | 'FLAT_ART' | 'FLAT_VECTOR' | 'FOREST_REVERIE' | 'GEO_MINIMALIST' | 'GLASS_PRISM' | 'GOLDEN_HOUR' | 'GRAFFITI_I' | 'GRAFFITI_II' | 'HALFTONE_PRINT' | 'HIGH_CONTRAST' | 'HIPPIE_ERA' | 'ICONIC' | 'JAPANDI_FUSION' | 'JAZZY' | 'LONG_EXPOSURE' | 'MAGAZINE_EDITORIAL' | 'MINIMAL_ILLUSTRATION' | 'MIXED_MEDIA' | 'MONOCHROME' | 'NIGHTLIFE' | 'OIL_PAINTING' | 'OLD_CARTOONS' | 'PAINT_GESTURE' | 'POP_ART' | 'RETRO_ETCHING' | 'RIVIERA_POP' | 'SPOTLIGHT_80S' | 'STYLIZED_RED' | 'SURREAL_COLLAGE' | 'TRAVEL_POSTER' | 'VINTAGE_GEO' | 'VINTAGE_POSTER' | 'WATERCOLOR' | 'WEIRD' | 'WOODBLOCK_PRINT'

A predefined style preset that applies a specific artistic style to the generated image.

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

style_reference_imagesstring[]

A set of images to use as style references (maximum total size 10MB across all style references). The images should be in JPEG, PNG or WebP format.

character_reference_imagesstring[]

Generations with character reference are subject to the character reference pricing. A set of images to use as character references (maximum total size 10MB across all character references), currently only supports 1 character reference image. The images should be in JPEG, PNG or WebP format.

character_reference_images_maskstring[]

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.

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: if the org has it on, this is ignored; if the org has it off, setting this true enables detection for this request only. Adds detection latency. Flagged images come back with is_image_safe: false.

Example request

{
  "prompt": "A photo of a cat",
  "seed": 12345,
  "resolution": "1280x800",
  "magic_prompt": "ON",
  "negative_prompt": "brush strokes, painting",
  "color_palette": {
    "name": "PASTEL"
  },
  "style_codes": [
    "AAFF5733",
    "0133FF57",
    "DE3357FF"
  ],
  "style_type": "GENERAL",
  "style_preset": "BRIGHT_ART",
  "custom_model_uri": "model/my-custom-model/version/1"
}

Response

Image(s) generated successfully.

createdstring date-time required

The time the request was created.

Example response

{
  "data": [
    {
      "style_type": "GENERAL",
      "seed": 12345,
      "upscaled_resolution": "4096x4096",
      "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
      "resolution": "1280x800",
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89",
      "is_image_safe": true
    },
    {
      "style_type": "GENERAL",
      "seed": 12345,
      "upscaled_resolution": "4096x4096",
      "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
      "resolution": "1280x800",
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89",
      "is_image_safe": true
    }
  ],
  "created": "2000-01-23T04:56:07+00:00"
}