Sign in

v4

latestOpenAPI 3.0.22026-08-02109239415.7 KB
generate

Generate a design from a text prompt with text detection and correction

Generates a design synchronously from a text prompt using the Ideogram 3.0 model, then detects and corrects text layers within the generated image.

The response includes the generated image URL along with detected text layers (with font, size, color, position) and image asset layers.

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-design

Request body

promptstring required

The prompt to use to generate the design.

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 a design. Descriptions in the prompt take precedence to descriptions in the negative prompt.

num_imagesinteger

Number of designs 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.

font_file_h1string binary

Custom font file for H1 (heading) text. Supported formats .ttf, .otf, .woff, .woff2 (max 5MB). Takes priority over font_name_h1.

font_name_h1string

Font name from the available font library for H1 text. Ignored if font_file_h1 is provided.

font_file_h2string binary

Custom font file for H2 (subheading) text. Supported formats .ttf, .otf, .woff, .woff2 (max 5MB). Takes priority over font_name_h2.

font_name_h2string

Font name from the available font library for H2 text. Ignored if font_file_h2 is provided.

font_file_bodystring binary

Custom font file for body text. Supported formats .ttf, .otf, .woff, .woff2 (max 5MB). Takes priority over font_name_body.

font_name_bodystring

Font name from the available font library for body text. Ignored if font_file_body is provided.

font_file_smallstring binary

Custom font file for small/caption text. Supported formats .ttf, .otf, .woff, .woff2 (max 5MB). Takes priority over font_name_small.

font_name_smallstring

Font name from the available font library for small text. Ignored if font_file_small is provided.

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.

reference_asset_imagesstring[]

A set of asset images (e.g., logos, icons) to use as references for detection and replacement (maximum 10 images). The images should be in JPEG, PNG or WebP format.

Example request

{
  "prompt": "A birthday card saying 'Happy Birthday'",
  "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",
  "font_name_h1": "Ubuntu-Bold.ttf"
}

Response

Design(s) generated successfully with text correction.

response_type'layered'

Discriminator for the postGenerateDesignV4 oneOf response. Always "layered" for this shape; absent on the legacy postGenerateDesignV3 endpoint.

createdstring date-time required

The time the request was created.

Example response

{
  "data": [
    {
      "text_containers": [
        {
          "id": "id",
          "items": [
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            },
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            }
          ]
        },
        {
          "id": "id",
          "items": [
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            },
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            }
          ]
        }
      ],
      "image_layers": [
        {
          "ref_id": "REF_0",
          "x": 4,
          "width": 1,
          "y": 7,
          "height": 1
        },
        {
          "ref_id": "REF_0",
          "x": 4,
          "width": 1,
          "y": 7,
          "height": 1
        }
      ],
      "url": "https://openapi-generator.tech",
      "text_html": "text_html"
    },
    {
      "text_containers": [
        {
          "id": "id",
          "items": [
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            },
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            }
          ]
        },
        {
          "id": "id",
          "items": [
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            },
            {
              "font_candidates": [
                "font_candidates",
                "font_candidates"
              ],
              "spans": [
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                },
                {
                  "color": "#212121",
                  "text": "text",
                  "font_fx": [
                    "bold",
                    "italic"
                  ]
                }
              ],
              "text_shadows": [
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                },
                {
                  "color": "color",
                  "blur": 0.2027123,
                  "offset_x": 9.301444,
                  "offset_y": 3.6160767
                }
              ],
              "font_size": 5,
              "vertical_alignment": "top",
              "text_transform": "none",
              "glyph_type": "bullet",
              "line_height": 2.302136,
              "x": 0,
              "width": 1,
              "style_class": "body",
              "y": 6,
              "angle": 0,
              "alignment": "center",
              "font_file": "font_file",
              "letter_spacing": 7.0614014,
              "height": 5
            }
          ]
        }
      ],
      "image_layers": [
        {
          "ref_id": "REF_0",
          "x": 4,
          "width": 1,
          "y": 7,
          "height": 1
        },
        {
          "ref_id": "REF_0",
          "x": 4,
          "width": 1,
          "y": 7,
          "height": 1
        }
      ],
      "url": "https://openapi-generator.tech",
      "text_html": "text_html"
    }
  ],
  "created": "2000-01-23T04:56:07+00:00",
  "response_type": "layered"
}