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 case | Approach |
|---|---|
| Quick ideas, exploring | Plain language |
| Expanding a short idea | Plain language with Magic Prompt |
| Posters, branded graphics, labels, signage | JSON |
| A set color palette | JSON |
| The same layout across many images | JSON |
| Photos where exact placement doesn't matter | Plain language |
Use a JSON prompt in the Image app
- Choose Ideogram 4.5 or Ideogram 4.0 explicitly in the Model picker.
- Paste the JSON into the Prompt box, without Markdown code fences.
- Turn Magic Prompt off where the toggle is shown if you want to avoid an expansion of your written prompt.
- Set aspect ratio, resolution, image count, quality and seed in the app controls.
- 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:
| Field | Required | What it holds |
|---|---|---|
high_level_description | Required | One or two sentences that sum up the whole image |
style_description | Optional | Style, lighting, medium and color palette |
compositional_deconstruction | Required | The 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.
| Field | Type | What it holds |
|---|---|---|
aesthetics | string | Mood and look, for example "moody, cinematic, desaturated" |
lighting | string | For example "golden hour, rim light, dramatic shadows" |
photo | string | Camera and lens, for example "35mm, f/1.4, bokeh". Use this or art_style, not both. |
medium | string | Free text, for example "photograph", "illustration", "3D render", "painting", "graphic design" |
art_style | string | For non-photo work, for example "flat vector illustration, bold outlines". Use this or photo, not both. |
color_palette | list of strings | Up 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"):
| Type | Key order |
|---|---|
"obj" | type, bbox (optional), desc, color_palette (optional) |
"text" | type, bbox (optional), text, desc, color_palette (optional) |
| Field | Type | What it holds |
|---|---|---|
type | string | "obj" for objects and subjects, "text" for text in the image |
bbox | list of 4 integers | Position as [y_min, x_min, y_max, x_max]. Optional. |
desc | string | A detailed description of the element |
text | string | Text elements only: the exact words to render |
color_palette | list of strings | Up to 5 six-digit #RRGGBB colors for this element. Optional. |
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
#RRGGBBvalues, 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.

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.

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