Skip to content

Docs

API docsOpen Ideogram

JSON Prompting

Write Ideogram JSON image prompts with text elements, color palettes and normalized bounding boxes. Learn the format, app workflow and layout limitations.
On this page

Ideogram 4.5 and 4.0 accept a plain-language prompt or a structured JSON prompt. Both models use the same JSON format. Ideogram 4.0 was trained on captions in this format, so a JSON prompt speaks to the model in its own terms.

Plain language works well for most images. JSON adds control that plain language can't give you:

  • Color control. Set up to 16 hex colors for the whole image and up to 5 for each element. They steer the colors strongly but don't lock every pixel.
  • Layout. Place any element in the frame with a bounding box.
  • Text placement. Each piece of text is its own element with its own position and style.
  • Reusable composition. Keep the same descriptions and regions while changing selected elements. Output can still vary between runs.

When to use JSON

Use caseApproach
Quick ideas, exploringPlain language
Expanding a short ideaPlain language with Magic Prompt
Posters, branded graphics, labels, signageJSON
A set color paletteJSON
The same layout across many imagesJSON
Photos where exact placement doesn't matterPlain language

Use a JSON prompt in the Image app

  1. Choose Ideogram 4.5 or Ideogram 4.0 explicitly in the Model picker.
  2. Paste the JSON into the Prompt box, without Markdown code fences.
  3. Turn Magic Prompt off where the toggle is shown if you want to avoid an expansion of your written prompt.
  4. Set aspect ratio, resolution, image count, quality and seed in the app controls.
  5. Generate, then review the text, colors and element placement before reusing the prompt.

The JSON describes image content. It doesn't replace the app's generation settings or serve as a complete API request body. For API requests, see the API Docs.

How Magic Prompt and JSON work together

You don't have to write JSON by hand. On Ideogram 4.5 and 4.0, Magic Prompt turns a plain-text prompt into a structured JSON prompt before generating:

  • Magic Prompt on: it rewrites and expands your idea, adding detail, style and layout, then builds the JSON.
  • Magic Prompt off: it keeps your wording and only converts it into the structured format.
  • You paste valid JSON: Ideogram uses your JSON as written and skips Magic Prompt, unless Magic Prompt is On. Then it rewrites your JSON too.

So when you've written JSON by hand and want it used exactly, turn Magic Prompt off.

If your JSON doesn't match the format below (for example, high_level_description is missing), Ideogram reads it as plain text. On Ideogram 4.5 the prompt box takes up to 10,000 characters, and long JSON prompts can lose their last elements, so list the most important elements first.

The schema

A JSON prompt has three top-level fields:

FieldRequiredWhat it holds
high_level_descriptionRequiredOne or two sentences that sum up the whole image
style_descriptionOptionalStyle, lighting, medium and color palette
compositional_deconstructionRequiredThe background and every element in the image

high_level_description

If you could say only one thing about the image, say it here.

{"high_level_description": "A medium-shot photograph of a barista pouring latte art in a cozy cafe."}

style_description

Every field is optional. Use photo for photographs, or art_style for illustration, painting, 3D, graphic design and the like. The model learned from captions that used one or the other, so pick one.

FieldTypeWhat it holds
aestheticsstringMood and look, for example "moody, cinematic, desaturated"
lightingstringFor example "golden hour, rim light, dramatic shadows"
photostringCamera and lens, for example "35mm, f/1.4, bokeh". Use this or art_style, not both.
mediumstringFree text, for example "photograph", "illustration", "3D render", "painting", "graphic design"
art_stylestringFor non-photo work, for example "flat vector illustration, bold outlines". Use this or photo, not both.
color_palettelist of stringsUp to 16 six-digit hex colors that steer the main colors, such as #FFD700.

compositional_deconstruction

This field holds background (a string describing the setting) and elements (a list). Both are required.

Each element is an object ("obj") or text ("text"):

TypeKey order
"obj"type, bbox (optional), desc, color_palette (optional)
"text"type, bbox (optional), text, desc, color_palette (optional)
FieldTypeWhat it holds
typestring"obj" for objects and subjects, "text" for text in the image
bboxlist of 4 integersPosition as [y_min, x_min, y_max, x_max]. Optional.
descstringA detailed description of the element
textstringText elements only: the exact words to render
color_palettelist of stringsUp to 5 six-digit #RRGGBB colors for this element. Optional.
Note

Ideogram puts the keys inside each block in the order the model expects, so you don't need to. Keep the three top-level fields in the order shown in the schema table.

Bounding boxes

Coordinates run from 0 to 1000 on each axis, with [0, 0] at the top-left corner, written as [y_min, x_min, y_max, x_max]. So [0, 0, 500, 1000] fills the top half of the image and [250, 250, 750, 750] sits in the center. Leave bbox out and the model places the element itself.

For a headline region with a small outer margin, [100, 50, 300, 950] requests a box from 10% to 30% of the image height and 5% to 95% of its width. The vertical coordinates come first. These are relative coordinates, not pixel dimensions, so changing output resolution doesn't require multiplying each number by the pixel count.

Keep the lower coordinate before the upper one on each axis and stay within 0–1000. Reserve enough space for each text block and check for overlaps in your intended layout. Bounding boxes guide the generated composition; use Studio layers when positions and editable wording must be set directly.

Color tips

  • Add the background colors to the palette if you want to set the overall tone.
  • Add both highlight and shadow colors for more control over lighting.
  • Use full six-digit #RRGGBB values, such as #FFD700, rather than three-digit shorthand. The public schema accepts uppercase or lowercase hex digits.

Example: no bounding boxes

Try this prompt first:

{
  "high_level_description": "A lone lighthouse on a sea cliff under a glowing violet aurora at night.",
  "style_description": {
    "aesthetics": "dreamlike, majestic, quiet",
    "lighting": "aurora glow from above, warm beam from the lighthouse, deep blue shadows",
    "photo": "wide-angle, long exposure, crisp stars",
    "medium": "photograph",
    "color_palette": ["#2A1B5C", "#7B4FD6", "#3FD9B0", "#F5C46B", "#0B1026"]
  },
  "compositional_deconstruction": {
    "background": "A night sky filled with swirling violet and teal aurora ribbons and scattered stars above a dark, calm sea.",
    "elements": [
      {
        "type": "obj",
        "desc": "A white lighthouse with a red top standing on the edge of a rugged grassy cliff, its warm beam cutting across the sky."
      },
      {
        "type": "obj",
        "desc": "Gentle waves breaking white against the rocks at the base of the cliff."
      }
    ]
  }
}

Settings: Ideogram 4.0, Magic Prompt off, aspect ratio 1:2.

Photograph of a white lighthouse on a dark grassy sea cliff under swirling violet and teal aurora, its warm light glowing above the calm sea

Example: text with bounding boxes

Use bounding boxes when every line of text needs its own place:

{
  "high_level_description": "A bold event poster for a jazz night called 'Blue Note Sessions' at The Velvet Room, Saturday August 9th.",
  "style_description": {
    "aesthetics": "moody, retro, sophisticated, 1960s jazz club aesthetic",
    "lighting": "dramatic, deep shadows, warm spotlight glow",
    "medium": "graphic_design",
    "art_style": "vintage poster design, textured paper, bold typography, muted color palette with warm accents",
    "color_palette": ["#1A1A2E", "#16213E", "#E8C97A", "#D4A843", "#F5F0E8", "#8B4513"]
  },
  "compositional_deconstruction": {
    "background": "Deep navy and near-black background with subtle aged paper texture and faint horizontal grain lines.",
    "elements": [
      {
        "type": "obj",
        "bbox": [150, 200, 650, 800],
        "desc": "A silhouetted jazz trumpeter in side profile, mid-performance, instrument raised. Warm golden spotlight illuminates from above, casting dramatic shadows. Stylized, slightly abstract illustration style."
      },
      {
        "type": "text",
        "bbox": [30, 50, 140, 950],
        "text": "BLUE NOTE SESSIONS",
        "desc": "Large bold all-caps serif headline in warm golden-yellow, spanning the full width near the top of the poster."
      },
      {
        "type": "text",
        "bbox": [660, 100, 760, 900],
        "text": "Live jazz every Saturday night",
        "desc": "Medium-weight italic serif subheading in off-white, centered beneath the main title."
      },
      {
        "type": "text",
        "bbox": [820, 200, 900, 800],
        "text": "THE VELVET ROOM",
        "desc": "Smaller all-caps sans-serif venue name in warm gold, centered near the bottom."
      },
      {
        "type": "text",
        "bbox": [900, 300, 970, 700],
        "text": "SAT · AUGUST 9",
        "desc": "Small light-weight serif date text in off-white, near the bottom of the poster."
      }
    ]
  }
}

Settings: Ideogram 4.0, Magic Prompt off, aspect ratio 1:2.

Vintage jazz poster of a spotlit trumpeter reading Blue Note Sessions, Live jazz every Saturday night, The Velvet Room, Sat August 9

For tips on wording the text itself, see Text in Images.