### Install and Initialize Pre-commit Hooks Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Installs the pre-commit package and registers the git hooks for the repository. This should be done once per clone. ```bash pip install pre-commit pre-commit install ``` -------------------------------- ### Install Package in Editable Mode with uv Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Installs the current project in editable mode using 'uv pip'. This is an alternative to using pip for editable installs. ```bash uv venv && source .venv/bin/activate uv pip install -e . ``` -------------------------------- ### Full JSON Prompt Example Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md This example demonstrates a detailed JSON structure for generating an image. It includes high-level descriptions, style parameters, and a compositional deconstruction with bounding boxes and descriptions for various elements. ```json { "high_level_description": "A medium-shot photograph of Formula 1 driver Max Verstappen wearing his Red Bull Racing racing suit and cap, smiling as he holds his racing helmet and talks to a man in a white shirt and black vest at a race track.", "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 or track environment. Several blurred figures are visible, including one in an orange shirt. A purple and white structure with a red 'F1' logo stands on the left. The scene is outdoors with daylight, though the sky is not visible.", "elements": [ {"type": "obj", "bbox": [55, 642, 1000, 937], "desc": "An older man standing in profile, facing left toward Max Verstappen. He has grey hair and fair skin. He is wearing a white long-sleeved button-down shirt with a navy blue quilted vest over it. He has a slight smile."}, {"type": "obj", "bbox": [34, 137, 1000, 617], "desc": "Max Verstappen, a fair-skinned male Formula 1 driver, positioned in the center. He is facing forward with a joyful expression and a slight smile. He wears a navy blue Red Bull Racing team uniform with numerous sponsor logos and a matching baseball cap with the number '1'. He is holding a white and red racing helmet in his hands. He has a silver watch on his left wrist."}, {"type": "obj", "bbox": [422, 212, 792, 452], "desc": "Max Verstappen's racing helmet, held in front of his chest. It features a white, red, and yellow design with the Red Bull logo and the 'Player 0.0' branding. The visor is clear and open."}, {"type": "text", "bbox": [657, 0, 755, 142], "text": "F1", "desc": "Large, stylized red logo on a black and purple background in the lower left."}, {"type": "text", "bbox": [768, 0, 818, 147], "text": "Formula 1\nWorld Championship™", "desc": "Small white sans-serif text below the F1 logo on the left side."}, {"type": "text", "bbox": [78, 447, 117, 510], "text": "ORACLE\nRed Bull\nRacing", "desc": "Very small white and orange logo on the front of the navy blue cap."}, {"type": "text", "bbox": [78, 417, 120, 440], "text": "1", "desc": "Bold red numeral '1' on the front left side of the navy blue cap."}, {"type": "text", "bbox": [332, 442, 363, 483], "text": "Red Bull", "desc": "Small yellow and red text logo on the collar of the uniform."}, {"type": "text", "bbox": [373, 490, 423, 532], "text": "RAUCH", "desc": "Small yellow and blue logo on the right chest of the uniform."}, {"type": "text", "bbox": [422, 473, 500, 532], "text": "BYBIT\nHONDA", "desc": "Medium-sized white sans-serif text on the right chest of the uniform."}, {"type": "text", "bbox": [410, 203, 442, 257], "text": "RAUCH", "desc": "Small yellow logo on the left upper arm of the uniform."}, {"type": "text", "bbox": [530, 448, 627, 510], "text": "Red Bull", "desc": "Medium red text logo on the right side of the torso, part of the Red Bull graphic."}, {"type": "text", "bbox": [680, 417, 768, 523], "text": "Red Bull", "desc": "Large red text logo across the lower torso of the uniform."}, {"type": "text", "bbox": [797, 475, 815, 518], "text": "MAX", "desc": "Small white text next to a Dutch flag on the belt area of the uniform."}, {"type": "text", "bbox": [558, 317, 715, 355], "text": "Player 0.0", "desc": "Black sans-serif text on a white band on the racing helmet."}, {"type": "text", "bbox": [560, 800, 582, 835], "text": "IA.COM", "desc": "Small blue sans-serif text on the right sleeve of the white shirt."}, {"type": "text", "bbox": [968, 8, 997, 332], "text": "© Anadolu Agency via Getty Images", "desc": "Small white watermark text in the bottom left corner." ] } } ``` -------------------------------- ### Style Description with Color Palette Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md Example of using `style_description` to define aesthetics, lighting, photographic style, medium, and a specific color palette for the overall image. ```json { "style_description": { "aesthetics": "moody, cinematic", "lighting": "low-key, deep shadows", "photo": "35mm, f/1.4", "medium": "photograph", "color_palette": ["#1B1B2F", "#162447", "#1F4068", "#E43F5A", "#F5F5F5"] } } ``` -------------------------------- ### Run Inference with Sampler Preset Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/inference.md Use this command to run inference with a specific sampler preset. The preset `V4_QUALITY_48` is used here as an example. ```bash python run_inference.py \ --prompt "a cat wearing a tiny top hat" \ --sampler-preset V4_QUALITY_48 \ --output out.png ``` -------------------------------- ### Install Package in Editable Mode Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Installs the current project in editable mode using pip. This ensures that changes to the source code are immediately reflected without needing to reinstall. ```bash pip install -e . ``` -------------------------------- ### Run Pre-commit Hooks Manually Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Manually runs all configured pre-commit hooks against every file in the repository. Useful for initial setup or CI checks. ```bash pre-commit run --all-files ``` -------------------------------- ### Install Ideogram 4.0 Source: https://github.com/ideogram-oss/ideogram4/blob/main/README.md Install the Ideogram 4.0 package using pip. For development, use editable mode to apply changes without reinstalling. ```bash pip install . ``` ```bash pip install -e . ``` -------------------------------- ### JSON Schema Example: High-Level Description Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md An example of the 'high_level_description' field within the JSON caption schema. This field provides a concise summary of the image. ```json "high_level_description": "A medium-shot photograph of a barista pouring latte art in a cozy cafe." ``` -------------------------------- ### Generate Image with Ideogram CLI Source: https://github.com/ideogram-oss/ideogram4/blob/main/README.md Use the Ideogram CLI to generate an image from a text prompt. This example uses the hosted magic-prompt API and specifies output file, quantization, and API key. ```bash python run_inference.py \ --prompt "a ginger cat wearing a tiny wizard hat reading a spellbook" \ --output out.png \ --quantization "nf4" \ --magic-prompt-key "$IDEOGRAM_API_KEY" ``` -------------------------------- ### Guided Velocity Calculation Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Formula for calculating the guided velocity used in Classifier-Free Guidance (CFG), combining conditional and unconditional predictions. ```text v_guided = gw * v_conditional + (1 - gw) * v_unconditional ``` -------------------------------- ### Create and Activate Virtual Environment with uv Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Creates a Python virtual environment using the 'uv' tool and activates it. This is an alternative to the standard venv module. ```bash uv venv && source .venv/bin/activate ``` -------------------------------- ### Create and Activate Virtual Environment Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Creates a Python virtual environment named .venv and activates it. This isolates project dependencies. ```bash python -m venv .venv && source .venv/bin/activate ``` -------------------------------- ### Authenticate Hugging Face Model Download Source: https://github.com/ideogram-oss/ideogram4/blob/main/README.md Log in to Hugging Face using the CLI to authenticate model downloads. Alternatively, export your HF_TOKEN as an environment variable. ```bash hf auth login ``` ```bash export HF_TOKEN="hf_..." ``` -------------------------------- ### Run Inference with Magic Prompt CLI Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md Executes the inference script using a specified prompt and output file, with the 'claude-opus-v1' magic prompt model. Requires the MAGIC_PROMPT_API_KEY environment variable. ```bash python run_inference.py \ --prompt "an isometric illustration of a tiny city floating in the clouds" \ --output out.png \ --quantization "nf4" \ --magic-prompt-model claude-opus-v1 \ --magic-prompt-key "$MAGIC_PROMPT_API_KEY" ``` -------------------------------- ### Euler Integration for Inference Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Shows the Euler method integration step used at inference time to go from noisy latents z_t to clean image latents z_0. ```text z_{t-dt} = z_t + v(z_t, t) * dt ``` -------------------------------- ### Basic Text Prompting with Ideogram 4 Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md Use this method for simple image generation tasks. It relies on predefined sampling presets for parameters. ```python from ideogram4 import PRESETS preset = PRESETS["V4_QUALITY_48"] images = pipe( "a golden retriever on a skateboard", height=1024, width=1024, num_steps=preset.num_steps, guidance_schedule=preset.guidance_schedule, mu=preset.mu, std=preset.std, ) ``` -------------------------------- ### Run Inference with Safety Screening Source: https://github.com/ideogram-oss/ideogram4/blob/main/README.md Execute the inference script with prompt, output, quantization, and API keys for safety screening. Ensure Hive keys are exported as environment variables or passed as arguments. ```bash python run_inference.py \ --prompt "an isometric illustration of a tiny city floating in the clouds" \ --output out.png \ --quantization "nf4" \ --magic-prompt-key "$MAGIC_PROMPT_API_KEY" \ --hive-text-key "$HIVE_TEXT_MODERATION_KEY" \ --hive-visual-key "$HIVE_VISUAL_MODERATION_KEY" ``` -------------------------------- ### Expand Prompt with Claude Opus Magic Prompt Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md Instantiates the Claude Opus Magic Prompt and expands a simple text prompt into a structured caption. Requires setting the MAGIC_PROMPT_API_KEY environment variable. ```python import os from ideogram4 import ClaudeOpusMagicPromptV1, PRESETS magic = ClaudeOpusMagicPromptV1(api_key=os.environ["MAGIC_PROMPT_API_KEY"]) caption = magic.expand("a golden retriever on a skateboard", aspect_ratio="1:1") preset = PRESETS["V4_QUALITY_48"] images = pipe( caption, height=1024, width=1024, num_steps=preset.num_steps, guidance_schedule=preset.guidance_schedule, mu=preset.mu, std=preset.std, ) ``` -------------------------------- ### Advanced JSON Prompting with Ideogram 4 Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md Employ this for enhanced control over image details, spatial arrangement, and style fidelity. Requires importing the 'json' library. ```python import json from ideogram4 import PRESETS caption = { "high_level_description": "A golden retriever riding a skateboard down a sunny sidewalk.", "style_description": { "aesthetics": "warm, playful, vibrant", "lighting": "bright afternoon sunlight, long soft shadows", "photo": "shallow depth of field, eye-level, 85mm lens", "medium": "photograph", "color_palette": ["#F5C542", "#87CEEB", "#4A4A4A", "#FFFFFF", "#2E8B57"] }, "compositional_deconstruction": { "background": "A sun-drenched suburban sidewalk lined with green hedges and a white picket fence. Dappled light filters through overhead trees.", "elements": [ {"type": "obj", "bbox": [200, 300, 800, 900], "desc": "A golden retriever with a fluffy coat, standing on a red skateboard with all four paws. Its tongue is out and ears are flapping in the wind."}, {"type": "obj", "bbox": [250, 750, 750, 950], "desc": "A worn red skateboard with black wheels rolling along the concrete sidewalk."} ] } } preset = PRESETS["V4_QUALITY_48"] images = pipe( json.dumps(caption, separators=((",", ":")), ensure_ascii=False), height=1024, width=1024, num_steps=preset.num_steps, guidance_schedule=preset.guidance_schedule, mu=preset.mu, std=preset.std, ) ``` -------------------------------- ### Magic Prompt JSON Output Contract Source: https://github.com/ideogram-oss/ideogram4/blob/main/src/ideogram4/magic_prompt_system_prompts/v1.txt The expected JSON output structure for the magic prompt system. It must contain exactly three top-level keys in the specified order: aspect_ratio, high_level_description, and compositional_deconstruction. ```json { "aspect_ratio":"W:H", "high_level_description":"...", "compositional_deconstruction":{ "background":"...", "elements":[ ... ] } } ``` -------------------------------- ### VAE Decoder Generation Call Pseudocode Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Pseudocode illustrating a single generation call, encompassing text encoding, noise initialization, Euler integration for diffusion, and final decoding to pixels. This process uses a conditional and unconditional diffusion model pass combined with Classifier-Free Guidance. ```python # Pseudocode for one generation call: # 1. Encode text text_features = qwen3_vl.encode(prompt) # (B, L_text, D) # 2. Initialize noise z = torch.randn(B, grid_h * grid_w, 128) # pure noise at t=1 # 3. Euler integration from t=1 to t=0 for step in reversed(range(num_steps)): t = schedule(step) s = schedule(step - 1) # Conditional pass (text + image) v_cond = dit(text_features, z, t) # Unconditional pass (image only, zeroed text) v_uncond = dit(zeros, z, t) # CFG combination v = gw[step] * v_cond + (1 - gw[step]) * v_uncond # Euler step z = z + v * (s - t) # 4. Decode to pixels image = vae.decode(z) ``` -------------------------------- ### DiT Sequence Layout Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Illustrates the sequence layout within the DiT backbone, showing how text tokens and image latent tokens are concatenated. ```text Sequence layout (per sample): ┌───────────────────┬────────────────────────┐ │ text tokens │ image latent tokens │ │ (up to 2048) │ (grid_h × grid_w) │ └───────────────────┴────────────────────────┘ ▲ ▲ Qwen3-VL features noisy latents z_t ``` -------------------------------- ### Adjusted Timestep Schedule Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Explains how the timestep schedule is adjusted based on image resolution, using a base pixel count and a logarithmic scaling. ```text mu_adjusted = mu_base + 0.5 * log(num_pixels / base_pixels) ``` -------------------------------- ### Update Pinned Pre-commit Hook Versions Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/development.md Updates the pinned versions of pre-commit hooks specified in the .pre-commit-config.yaml file to their latest compatible versions. ```bash pre-commit autoupdate ``` -------------------------------- ### Warm Sunset Palette Prompt Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md This prompt defines a scene with a lone sailboat at sunset, specifying aesthetics, lighting, photographic style, and a warm color palette. ```json { "high_level_description": "A lone sailboat on calm water at sunset.", "style_description": { "aesthetics": "serene, warm, golden hour", "lighting": "golden hour backlighting, warm atmospheric haze", "photo": "wide angle, f/8, long exposure", "medium": "photograph", "color_palette": ["#FF6B35", "#F7C59F", "#004E89", "#1A659E", "#2B2D42"] }, "compositional_deconstruction": { "background": "A calm ocean stretching to a low horizon, sky washed in orange and pink with thin wisps of cloud.", "elements": [ {"type": "obj", "desc": "A single sailboat with a white triangular sail, silhouetted against the setting sun."} ] } } ``` -------------------------------- ### Corporate Design Palette Prompt Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md This prompt outlines a clean, modern business card design for a tech company, detailing aesthetics, lighting, graphic design style, and a corporate color palette. ```json { "high_level_description": "A clean, modern business card layout for a tech company.", "style_description": { "aesthetics": "minimal, professional, geometric", "lighting": "even, diffuse studio lighting", "medium": "graphic_design", "art_style": "flat vector design, generous whitespace, sans-serif typography", "color_palette": ["#FFFFFF", "#F0F0F0", "#333333", "#0066FF", "#00CC88"] }, "compositional_deconstruction": { "background": "A solid off-white card surface with subtle paper texture.", "elements": [ {"type": "text", "text": "ACME TECH", "desc": "Bold dark grey sans-serif company name across the upper third of the card.","font_family": "sans-serif"}, {"type": "text", "text": "hello@acme.tech", "desc": "Small blue sans-serif contact email near the bottom of the card.","font_family": "sans-serif"} ] } } ``` -------------------------------- ### Ideogram4 Transformer Architecture Overview Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/model_architecture.md This diagram illustrates the flow of data through the Ideogram4 transformer, from text prompt processing to image generation. ```text prompt ─► Qwen3-VL-8B-Instruct (extract hidden states from layers (0,3,…,33,35) → concat) │ ▼ ┌──────────────────────────────────────────────────┐ │ Ideogram4Transformer │ │ • 34 × Ideogram4TransformerBlock │ │ – Ideogram4Attention (QK-RMSNorm, MRoPE) │ │ – Ideogram4MLP (SwiGLU) │ │ – adaln scale/gate from t-embedding │ │ • Ideogram4FinalLayer │ └──────────────────────────────────────────────────┘ │ velocity prediction ▼ Euler flow-matching sampler with asymmetric CFG │ denoised image latents ▼ VAE decode │ ▼ PIL.Image ``` -------------------------------- ### Flow Matching ODE Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Defines the Ordinary Differential Equation (ODE) used in flow matching, where the model predicts a velocity field v(z_t, t). ```text dz/dt = v(z_t, t) ``` -------------------------------- ### Ideogram 4 Pipeline Components Source: https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md Conceptual overview of the four main components in the Ideogram 4 inference pipeline: Text Encoder, Transformer (DiT) + Sampler, VAE Decoder, and the final Image output. ```text ┌─────────────┐ ┌──────────────────────┐ ┌──────────────┐ ┌───────────┐ │ Qwen3-VL │ │ Ideogram4 │ │ KL VAE │ │ │ │ Text ├──►│ Transformer (DiT) ├──►│ VAE ├──►│ Image │ │ Encoder │ │ + Euler Sampler │ │ Decoder │ │ │ └─────────────┘ └──────────────────────┘ └──────────────┘ └───────────┘ frozen trainable frozen ``` -------------------------------- ### Element Object Structure Source: https://github.com/ideogram-oss/ideogram4/blob/main/src/ideogram4/magic_prompt_system_prompts/v1.txt Defines the structure for individual elements within the compositional_deconstruction. Elements can be of type 'obj' (object) or 'text', each with an optional bounding box (bbox) and a description. ```json {"type":"obj","bbox":[y1,x1,y2,x2],"desc":"..."} ``` ```json {"type":"text","bbox":[y1,x1,y2,x2],"text":"LINE ONE\nLINE TWO","desc":"..."} ``` -------------------------------- ### BibTeX Citation for Ideogram 4 Source: https://github.com/ideogram-oss/ideogram4/blob/main/README.md Use this BibTeX entry when citing Ideogram 4 in academic research or publications. ```bibtex @misc{ideogram-4-2026, author={Ideogram AI}, title={{Ideogram 4}}, year={2026}, howpublished={\url{https://ideogram.ai/blog/ideogram-4.0/}}, } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.