# How to JSON prompt for Ideogram 4.0

Ideogram publishes a public search API over its indexed pages; the guide is at https://ideogram.ai/agents/agent-access.

Source: https://ideogram.ai/blog/ideogram-4-json-prompting/
Source observed: 2026-11-03T18:37:01.788Z
Last checked: 2026-11-08T15:45:23.275+00:00
Indexed: 2026-11-03T18:41:47.265+00:00

---

# How to JSON prompt for Ideogram 4.0

**Blog · June 18, 2026**

We explain how structured JSON captions give Ideogram 4.0 more precise control over text, layout, color, and style. JSON is organized labeled information, not necessarily code you must write by hand.

## Why prompts feel different in 4.0

Ideogram 4.0 responds more literally to specific descriptions. Replace vague terms such as “moody,” “vibrant,” or “editorial feel” with concrete details such as “warm directional light from the upper left,” “Hasselblad medium format,” named references, light sources, and exact colors.

Plain-text prompts trigger significantly more false positives with the safety filter than structured prompts. When an innocuous prompt is blocked, adding detail to JSON is the fastest fix described here.

## JSON explained

JSON gives image components labeled slots for the overall scene, visual style, background, and specific elements:

- `high_level_description`: overall scene.
- `style_description`: visual style.
- `background`: background description.
- `elements`: specific objects or text.

### Plain text example

```text
A lush tropical greenhouse interior, Rousseau-style oil painting, jungle plants, parrot, bright flowers
```

The model infers palette, flowers, and layout, so repeated generations can drift.

### Structured caption example

```json
{
  "high_level_description": "Lush tropical greenhouse interior, Rousseau-style oil painting",
  "style_description": {
    "aesthetics": "dreamlike, abundant, deeply saturated",
    "lighting": "dappled greenhouse light through glass ceiling",
    "medium": "oil painting",
    "art_style": "Henri Rousseau, naive jungle painting, rich impasto"
  },
  "compositional_deconstruction": {
    "background": "dense emerald and cadmium green foliage filling the frame",
    "elements": [
      { "type": "obj", "desc": "broad tropical leaves in deep green, layered and overlapping" },
      { "type": "obj", "desc": "exotic orchids in crimson and gold, scattered throughout" },
      { "type": "obj", "desc": "a parrot perched mid-frame, vivid red and blue plumage" }
    ]
  }
}
```

The structured version explicitly names the oil medium, saturated palette, orchids, parrot, and layered foliage.

![Tropical greenhouse oil painting generated from a plain-text prompt](https://storage.googleapis.com/ideogram-static/website/images/be6f16fd7fb7f8e5.webp)

![Lush Rousseau-style tropical greenhouse interior generated from a structured JSON caption](https://storage.googleapis.com/ideogram-static/website/images/81aec52261b7ff80.webp)

## Breaking down the JSON format

| Field | Description | Type |
|---|---|---|
| `high_level_description` | One- or two-sentence scene summary; start with the subject and recognizable properties; keep it under 50 words | string |
| `style_description` | Aesthetics, lighting, medium (`photograph`, `illustration`, or `graphic_design`), and optional color palette | object |
| `compositional_deconstruction` | Background plus an `elements` array for layout, text placement, and bounding boxes | object |

### Key ordering

The `style_description` fields must use the trained order:

- Photography: `aesthetics` → `lighting` → `photo` → `medium` → `color_palette`
- Illustration/design: `aesthetics` → `lighting` → `medium` → `art_style` → `color_palette`

[CaptionVerifier](https://github.com/ideogram-oss/ideogram-4) catches ordering mistakes before generation.

## Natural language to JSON with Magic Prompt

Magic Prompt is a built-in translator. On live Ideogram 4.0 it turns on or off automatically: plain text is expanded, while valid, well-formed JSON passes through as-is.

Example input:

```text
a product shot of a perfume bottle, elegant
```

Example structured caption sent to the model:

```json
{
  "high_level_description": "A perfume bottle product shot, luxury cosmetics photography",
  "style_description": {
    "aesthetics": "editorial, luxury, minimal",
    "lighting": "single soft key light upper left, subtle fill right",
    "medium": "photograph",
    "photo": "studio"
  },
  "compositional_deconstruction": {
    "background": "clean white surface, slight shadow",
    "elements": [
      {
        "type": "obj",
        "bbox": [100, 300, 900, 700],
        "desc": "cylindrical frosted glass perfume bottle, gold metal cap, embossed logo"
      }
    ]
  }
}
```

Magic Prompt can:

- Populate sparse scenes with secondary elements.
- Upgrade vague references to specific ones, such as “Nike Air Jordan 1” instead of “retro sneaker.”
- Remove hedging language such as “could include,” “various,” or “or similar.”
- Drop metadata such as bokeh and film grain unless explicitly named.
- Choose one value when two are supplied, such as turning “cream or ivory” into “cream.”

Use plain text for quick exploration. Write JSON directly when brand colors, text, or placement are non-negotiable; Magic Prompt does not expand an already structured prompt.

![Living room generated from a natural-language prompt with general placement cues](https://storage.googleapis.com/ideogram-static/website/images/15539fc4d8450d56.webp)

![Living room generated from JSON with explicit bounding boxes](https://storage.googleapis.com/ideogram-static/website/images/30c8d9fb025952d7.webp)

## Text rendering

Ideogram 4.0 supports literal text rendering. Put the exact text to render in double quotation marks. Keep each quoted string to 5–7 words maximum because accuracy decreases with longer strings. In JSON, use `"type": "text"`, a `"text"` field for the literal string, and `"desc"` for visual treatment.

Example:

```text
Vintage naturalist collector card, "MANTIS SHRIMP" in bold display serif at top, "Odontodactylus scyllarus" in green italic below the illustration, "Possesses the most complex eyes in the animal kingdom." in smaller roman, "8 of 50" bottom right, "OCEAN MARVELS" in banner at bottom
```

The page reports the following approximate guide:

- Large English text: ~97% accurate.
- Small English text: ~90% accurate.
- Large Arabic text: works well for single words and short phrases.
- Small Arabic text or full paragraphs: expect garbling and phantom letters.

For small charts or labels, words such as “forty-two percent” are described as more reliable than `42%`.

![Vintage naturalist collector card with quoted text rendered across five type styles](https://storage.googleapis.com/ideogram-static/website/images/54e08641987e1159.webp)

## Controlling placement with bounding boxes

Ideogram 4.0 uses bounding boxes on a 0–1000 grid. The format is `[y_min, x_min, y_max, x_max]`, with 0 at the top-left and 1000 at the bottom-right. The lower-right quadrant is `[500, 500, 1000, 1000]`.

```json
{ "type": "obj", "bbox": [535, 96, 830, 523], "desc": "folded broadsheet newspaper" }
```

Use bounding boxes for posters, packaging, social templates, and infographics. They are layout guides rather than pixel-perfect crops.

- Ground, floor, and pavement always belong in `background`, not as bounding-box elements.
- Keep total elements to 5 or fewer per image for best quality.
- Leave margin around each box.

### Complete bounding-box example

```json
{
  "high_level_description": "Overhead flat lay of a breakfast table, morning light",
  "style_description": {
    "aesthetics": "clean, editorial",
    "lighting": "soft natural window light, warm morning",
    "medium": "food photography"
  },
  "compositional_deconstruction": {
    "background": "white linen tablecloth, soft shadows",
    "elements": [
      { "type": "obj", "bbox": [293, 288, 461, 461], "desc": "ceramic coffee cup with latte art" },
      { "type": "obj", "bbox": [266, 549, 496, 781], "desc": "buttered croissant on a small plate" },
      { "type": "obj", "bbox": [535, 96, 830, 523], "desc": "folded broadsheet newspaper" },
      { "type": "obj", "bbox": [549, 584, 781, 861], "desc": "small glass vase with fresh tulips" }
    ]
  }
}
```

![Breakfast flat lay with coffee cup, croissant, newspaper, and tulips placed inside declared bounding zones](https://storage.googleapis.com/ideogram-static/website/images/85f871c713969275.webp)

## Exact brand colors

Ideogram 4.0 supports hex color conditioning. A code such as `#2D5A27` anchors the image palette around that value.

| Field | Description | Limit |
|---|---|---:|
| `color_palette` (style) | Image-wide dominant palette; include background and shadow values | Up to 16 hex codes |
| `color_palette` (element) | Per-element color steering for a text or object element | Up to 5 hex codes |

Use uppercase `#RRGGBB` values only. Do not use shorthand such as `#f63` or lowercase such as `#ff6b35`. Include background and shadow/highlight values. The page gives `["#0A0A0A", "#C9A84C", "#FFFFFF"]` as a fuller example than `["#C9A84C"]`.

![Iridescent glass flamingo in warm amber, rose gold, and garnet tones](https://storage.googleapis.com/ideogram-static/website/images/d3165c9824c55aa2.webp)

![Iridescent glass flamingo in cool amethyst, ice blue, and violet tones](https://storage.googleapis.com/ideogram-static/website/images/c8264b714da19bf4.webp)

The two images use the same prompt with different `color_palette` arrays; the palette steers highlights, shadows, and reflections.

## Consistent style with Style Codes

A Style Code is a visual fingerprint extracted from a generation and reusable in future prompts. Generate a hero image, copy its Style Code from the generation panel, and pass it as `style_code`.

The page demonstrates the prompt “A fox portrait, clean background” with these sample Style Codes:

- Dutch oil · `SC_7f3d2`
- Woodblock · `SC_2a8c1`
- Bauhaus · `SC_9e4f3`

![Fox portrait in Dutch Golden Age oil-painting style](https://storage.googleapis.com/ideogram-static/website/images/6e899cee9fe89f15.webp)

![Fox portrait in Japanese ukiyo-e woodblock style](https://storage.googleapis.com/ideogram-static/website/images/926a0cc8535e0c1c.webp)

![Fox portrait in Bauhaus geometric style](https://storage.googleapis.com/ideogram-static/website/images/0e77d040183fefdd.webp)

These are sample demonstrations. Style Codes extracted from `V4_QUALITY_48` are described as tending to produce better results when reapplied.

Preset quality levels:

- `V4_TURBO_12` (~21s at 1024²): exploration and drafts.
- `V4_DEFAULT_20` (~32s at 1024²): daily production work.
- `V4_QUALITY_48` (~72s at 1024²): finals, typography-critical output, and Style Code extraction.

## Settings that change output

| Setting | Description | Values |
|---|---|---|
| `style_code` | Locks an exact visual aesthetic from a favorite generation | `SC_xxxxx` |
| `style_type` | Broad aesthetic category when no Style Code is set; AUTO infers from the prompt | `REALISTIC` · `DESIGN` · `AUTO` |
| `magic_prompt` | Always `AUTO` on live Ideogram 4.0; plain text expands and valid JSON passes through | `AUTO` |
| `negative_prompt` | Specific elements to suppress; pair exclusions with positive framing | string |
| `seed` | Reproducibility anchor; same seed and prompt produce the same composition | integer |
| `sampler_preset` | Quality/speed tradeoff; use `V4_QUALITY_48` for typography-critical output | `V4_TURBO_12` · `V4_DEFAULT_20` · `V4_QUALITY_48` |

## Plain text or JSON?

| Use case | Approach |
|---|---|
| First idea or exploration | Plain text; Magic Prompt expands it |
| Brand asset with exact colors | JSON with `color_palette` |
| Poster or packaging with specific text | JSON plus text elements and `bbox` |
| Full campaign consistency | JSON plus `style_code` from the hero image |
| Safety-filter block | JSON prompt |
| Self-hosted or local inference | JSON; Magic Prompt backend is separate |

## Open-source tooling

The JSON schema, CaptionVerifier, and three Magic Prompt backends are available at [github.com/ideogram-oss/ideogram4](https://github.com/ideogram-oss/ideogram-4). The backends can use the hosted Ideogram API, Claude Opus/Sonnet through OpenRouter, or Gemini Flash-Lite.

## What to try next

Start with plain language, add a `style_code` from a preferred result, and switch to JSON for exact colors or placed text. The techniques can be combined.

- Generate at scale with the API using [the generate endpoint](https://developer.ideogram.ai/api-reference/api-reference/generate-v4) for batch runs, seed pinning, and Style Code reuse.
- Explore [the open-source tooling](https://github.com/ideogram-oss/ideogram-4) locally or with another LLM backend.
- Edit an existing product photo with our [Ideogram 4.5 product photo editing guide](https://ideogram.ai/blog/ideogram-4-5-product-photo-editing/).

[Open Ideogram](https://ideogram.ai/)

---

[Read this page’s summary](https://ideogram.ai/agents/api/public/v1/page-tldr?url=https%3A%2F%2Fideogram.ai%2Fblog%2Fideogram-4-json-prompting%2F&trace=t_380edc68d53d)

## Ask a follow-up about this page

Need a more specific answer? Ask the exact question you have. It returns a fresh, cited answer from Ideogram’s knowledge base. No account or API key required.

Open this URL with your own question, URL-encoded. Include your question in q. All research inputs are optional; no account or setup.

`GET https://ideogram.ai/agents/agent/faq?q={question}&trace=t_380edc68d53d`

[Tool guide and examples](https://ideogram.ai/agents/agent-access) · [OpenAPI](https://ideogram.ai/agents/api/public/v1/openapi.json) · [Page TLDR form](https://ideogram.ai/agents/agent-tools/page-tldr?url=https%3A%2F%2Fideogram.ai%2Fblog%2Fideogram-4-json-prompting%2F). Opening a form does not execute a tool.