Ideogram 4 Documentation

Ideogram 4 is a foundation model built on a fully single-stream Diffusion Transformer (DiT) architecture. Unlike models with separate text and image branches, Ideogram 4 concatenates text and image tokens into a single sequence processed by a 34-layer transformer, allowing for deep cross-modal interaction at every layer.

Key Architectural Components:

• Text Encoder: Uses Qwen3-VL-8B-Instruct (a vision-language model) instead of traditional text-only encoders like CLIP or T5. It extracts and concatenates hidden states from 13 intermediate layers to provide multi-scale semantic features.
• Classifier-Free Guidance: Features a dual-branch system where conditional (positive) and unconditional (negative) branches can be independently refined for control over prompt adherence and image quality.
• Resolution Support: Natively supports any resolution from 256 to 2048 (must be multiples of 16), with aspect ratios up to 6:1.

Ideogram 4 supports structured JSON prompts, which provide significantly more control over composition, color palettes, typography, and spatial layout compared to plain-text prompts. Using this schema allows you to explicitly define high-level descriptions, stylistic attributes, and a detailed compositional deconstruction of the scene.

The JSON schema consists of three primary keys:

• high_level_description: A prose description of the overall scene.
• style_description: An object defining the aesthetic properties of the image.
• compositional_deconstruction: An object detailing the background and specific elements within the scene.

Within compositional_deconstruction, you can define:

• background: A description of the environment.
• elements: An array of objects representing specific items, people, or text. Each element can have a type (e.g., obj or text), a bbox (bounding box), a desc (description), and for text elements, the specific text content.

{
  "high_level_description": "A medium-shot photograph of Formula 1 driver Max Verstappen...",
  "style_description": {
    "aesthetics": "saturated primary colors, rule of thirds, joyful and triumphant",
    "lighting": "overcast daylight, diffused, soft subtle shadows",
    "photo": "shallow depth of field, sharp focus, eye-level, telephoto",
    "medium": "photograph"
  },
  "compositional_deconstruction": {
    "background": "The background is an out-of-focus racing paddock...",
    "elements": [
      {
        "type": "obj",
        "bbox": [55, 642, 1000, 937],
        "desc": "An older man standing in profile..."
      },
      {
        "type": "text",
        "bbox": [657, 0, 755, 142],
        "text": "F1",
        "desc": "Large, stylized red logo..."
      }
    ]
  }
}

Ideogram4 is a single-stream Diffusion Transformer (DiT). It processes text and image information by concatenating text tokens (derived from Qwen3-VL-8B-Instruct hidden states) and image latent tokens into a single sequence.

Key architectural components include:

• Ideogram4Transformer: Composed of 34 Ideogram4TransformerBlock layers.
• Ideogram4Attention: Utilizes QK-RMSNorm and 3D MRoPE (Multimodal Rotary Positional Embedding) to ensure text and image tokens share a unified positional space.
• Ideogram4MLP: Uses SwiGLU activation.
• Modulation: Per-block modulation is performed via AdaLN (Adaptive Layer Norm) scaled/gated by a timestep embedding.
• Sampling: Uses an Euler flow-matching sampler with a logit-normal schedule and asymmetric CFG (Classifier-Free Guidance).
• Output: The process produces denoised image latents which are then decoded via a VAE into a PIL.Image.

Ideogram 4 is a flow-matching text-to-image model utilizing a single-stream Diffusion Transformer (DiT). The end-to-end pipeline consists of four main stages:

1. Text Encoder (Qwen3-VL-8B-Instruct): A frozen vision-language model that tokenizes the prompt and extracts multi-scale hidden states from 13 specific layers (0, 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 35) to create a rich text representation.
2. DiT Backbone (Ideogram4Transformer): A 34-layer trainable transformer that processes concatenated text and image latent tokens in a single sequence. It uses Flow Matching to predict a velocity field and an Euler sampler for integration.
3. Classifier-Free Guidance (CFG): A mechanism that combines conditional (text + image) and unconditional (image only) velocity predictions to amplify prompt adherence.
4. VAE Decoder (KL Autoencoder): A frozen decoder that unpatches and denormalizes the denoised latents to produce the final RGB image.

┌─────────────┐   ┌──────────────────────┐   ┌──────────────┐   ┌───────────┐
 │  Qwen3-VL   │   │  Ideogram4           │   │  KL VAE      │   │           │
 │  Text       ├──►│  Transformer (DiT)   ├──►│  VAE         ├──►│  Image    │
 └─────────────┘   └──────────────────────┘   └──────────────┘   └───────────┘
     frozen              trainable                 frozen