Model Skills

---
name: ideogram-4-oss
description: Teaches an LLM to write effective image prompts for ideogram-4-oss.
---

# ideogram-4-oss

## When To Use

Use this skill when the user asks for an image or an edit made with ideogram-4-oss and you need to write or revise the prompt. Apply the rules below when composing the prompt text; do not paste the rules into the prompt itself.

## Prompt Schema

The model was trained exclusively on JSON captions of this exact shape
(source: the official prompting guide in the ideogram-oss/ideogram4 GitHub
repository). Fill the fields, keep the key
order, drop optional keys you do not need:

```json
{
  "high_level_description": "One- or two-sentence summary of the whole image. Optional, strongly recommended.",
  "style_description": {
    "aesthetics": "moody, cinematic, desaturated",
    "lighting": "golden hour, rim light, dramatic shadows",
    "photo": "35mm, f/1.4, shallow depth of field",
    "medium": "photograph",
    "color_palette": ["#1B1B2F", "#162447", "#E43F5A"]
  },
  "compositional_deconstruction": {
    "background": "Environment description. Required, must come before elements.",
    "elements": [
      {
        "type": "obj",
        "bbox": [200, 300, 800, 900],
        "desc": "Detailed description of the object.",
        "color_palette": ["#F5C542"]
      },
      {
        "type": "text",
        "bbox": [657, 0, 755, 142],
        "text": "THE LITERAL TEXT TO RENDER",
        "desc": "Typography spec: font style, weight, color, placement.",
        "color_palette": ["#FFFFFF"]
      }
    ]
  }
}
```

- `compositional_deconstruction` (with `background` and `elements`) is required; the other two top-level fields are optional but strongly recommended.
- Non-photo captions replace `photo` with `art_style` and reorder `style_description` keys to: `aesthetics`, `lighting`, `medium`, `art_style`, `color_palette`.
- `bbox` is `[y_min, x_min, y_max, x_max]` on a normalized 0–1000 canvas with the origin at the top-left; rough coordinates suffice. `bbox` and `color_palette` are optional inside an element.
- Serialize compactly: in Python use `json.dumps(caption, separators=(",", ":"), ensure_ascii=False)`.

### Worked example

```json
{
  "high_level_description": "A golden retriever riding a skateboard down a sunny suburban street.",
  "style_description": {
    "aesthetics": "vibrant, cinematic, warm",
    "lighting": "golden hour, soft shadows, lens flare",
    "photo": "35mm, f/2.8, shallow depth of field",
    "medium": "photograph",
    "color_palette": ["#F5C542", "#1B1B2F", "#E43F5A", "#FFFFFF", "#2C5F2D"]
  },
  "compositional_deconstruction": {
    "background": "Tree-lined suburban street with houses on both sides, warm sunlight casting long shadows, clear blue sky.",
    "elements": [
      {
        "type": "obj",
        "bbox": [400, 350, 650, 750],
        "desc": "Golden retriever sitting on a skateboard, tongue out, looking happy and focused.",
        "color_palette": ["#F5C542"]
      },
      {
        "type": "text",
        "bbox": [657, 0, 755, 142],
        "text": "STREET RIDER",
        "desc": "Bold sans-serif typography, white with a thin black outline, placed on a dark wall in the background.",
        "color_palette": ["#FFFFFF"]
      }
    ]
  }
}
```

## Text To Image

### Parameters And Constraints

- Specify 'bbox' coordinates in row-first order as [y_min, x_min, y_max, x_max] using 0–1000 normalized integers.
- For object elements, the JSON keys must follow the order: type, bbox, desc, color_palette; for text elements, the JSON keys must follow the order: type, bbox, text, desc, color_palette.
- The `compositional_deconstruction` field is mandatory in the JSON caption schema, and within it, both `background` and `elements` are required keys.
- Ideogram-4-oss requires prompts to be provided as structured JSON objects following a specific caption schema rather than natural language text.

### Capabilities

- The transformer uses a unified positional space for text and image tokens via 3D MRoPE, allowing for seamless integration of text and visual context within the same sequence.

### Prompting Rules

- Use 'art_style' instead of 'photo' for subjects that are prints, drawings, or graphics, even if they resemble photographs, to ensure the correct rendering path is used.
- Use 'color_palette' with hex values to provide direct color direction, as describing colors in 'desc' is interpreted as natural language rather than strict conditioning.
- Use the 'text' type for elements requiring exact, byte-for-byte rendering of copy, as the model renders these literally rather than interpreting them as natural language.
- When using structured JSON, field ordering is critical because the model was trained on a specific sequence: for photos use aesthetics → lighting → photo → medium, and for non-photos use aesthetics → lighting → medium → art_style.
- Use verbose natural-language prompts with magic prompt ON for exploration and loose briefs where you want the model to interpret intent, but use structured JSON with magic prompt OFF for precise palettes, specific compositions, or legible text.
- Use `compositional_deconstruction` with an `elements` list containing objects with bounding boxes and descriptions for precise spatial layout control.
- To control colors in structured JSON, include up to 16 uppercase #RRGGBB hex values in the style_description field for dominant colors, or up to 5 per element for per-subject color control.
- For complex style blends involving typography and illustration, define the composition hierarchy (dominant headline, central illustration, supporting detail) and include elements that break formality to maintain the intended aesthetic.
- The `color_palette` field in `style_description` is optional but must be placed in the final position if included.
- When serializing the prompt JSON in Python, use separators=(",", ":") and ensure_ascii=False to avoid encoding warnings.
- Use `bbox` coordinates in the prompt to explicitly place subjects, text elements, and background regions.
- Specify hex colors in the `colour_palette` array within the style description to condition the image's dominant color scheme.