Add Ideogram 4 (#13859)

* Add Ideogram 4

Adds the Ideogram 4 text-to-image model: transformer, standard pipeline,
modular pipeline, docs, and tests.

Checkpoint: ideogram-ai/ideogram-4-nf4

Co-Authored-By: YiYi Xu <yiyi@huggingface.co>

* Use split q/k/v projections in Ideogram4 attention

Replace the fused `qkv`/`o` linears with canonical `to_q`/`to_k`/`to_v`/`to_out`
projections, matching the standard diffusers attention layout and the split
checkpoint format. Mathematically equivalent to the fused form (q/k/v are
contiguous row-slices of the fused weight). Drops the now-inapplicable
fuse/unfuse overrides.

---------

Co-authored-by: Jin <jin.li@ideogram.ai>
Co-authored-by: YiYi Xu <yiyi@huggingface.co>

Author: 3 people

docs/source/en/_toctree.yml

@@ -349,6 +349,8 @@
         title: HunyuanVideo15Transformer3DModel
       - local: api/models/hunyuan_video_transformer_3d
         title: HunyuanVideoTransformer3DModel
+      - local: api/models/ideogram4_transformer2d
+        title: Ideogram4Transformer2DModel
       - local: api/models/transformer_joyimage
         title: JoyImageEditTransformer3DModel
       - local: api/models/latte_transformer3d
@@ -541,6 +543,8 @@
         title: Hunyuan-DiT
       - local: api/pipelines/hunyuanimage21
         title: HunyuanImage2.1
+      - local: api/pipelines/ideogram4
+        title: Ideogram 4
       - local: api/pipelines/pix2pix
         title: InstructPix2Pix
       - local: api/pipelines/joyimage_edit

docs/source/en/api/models/ideogram4_transformer2d.md

@@ -0,0 +1,19 @@
+<!--Copyright 2026 Ideogram AI and The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+-->
+
+# Ideogram4Transformer2DModel
+
+A transformer for image-like data from [Ideogram 4](https://github.com/ideogram-oss/ideogram-4). 
+
+## Ideogram4Transformer2DModel
+
+[[autodoc]] Ideogram4Transformer2DModel

docs/source/en/api/pipelines/ideogram4.md

@@ -0,0 +1,51 @@
+<!--Copyright 2026 Ideogram AI and The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+-->
+
+# Ideogram 4
+
+Ideogram 4 is a flow-matching text-to-image model that uses a multimodal text encoder and an asymmetric
+classifier-free guidance scheme: a dedicated `unconditional_transformer` produces the negative branch with zeroed text
+features, while the main `transformer` consumes the full packed text + image sequence.
+
+The pipeline defaults are the recommended settings for best quality, so a plain `pipe(prompt)` call produces
+best-quality results out of the box: 48 flow-matching steps on a logit-normal schedule (`mu=0.0`, `std=1.5`) with
+classifier-free guidance held at 7.0 for the main steps and dropped to 3.0 for the final 3 "polish" steps.
+
+Key inference-time knobs are exposed via the pipeline call:
+
+- `num_inference_steps`, `mu`, and `std` control the resolution-aware logit-normal flow-matching schedule.
+- `guidance_scale` (or a full per-step `guidance_schedule`) blends the conditional and unconditional velocities.
+
+## Text-to-image
+
+```python
+import torch
+from diffusers import Ideogram4Pipeline
+
+pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", torch_dtype=torch.bfloat16)
+pipe.to("cuda")
+
+prompt = "A photo of a cat holding a sign that says hello world"
+# The defaults are the recommended settings for best quality.
+image = pipe(prompt, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
+image.save("ideogram4.png")
+```
+
+## Ideogram4Pipeline
+
+[[autodoc]] Ideogram4Pipeline
+	- all
+	- __call__
+
+## Ideogram4PipelineOutput
+
+[[autodoc]] pipelines.ideogram4.pipeline_output.Ideogram4PipelineOutput

src/diffusers/__init__.py

@@ -258,6 +258,7 @@
             "HunyuanVideoFramepackTransformer3DModel",
             "HunyuanVideoTransformer3DModel",
             "I2VGenXLUNet",
+            "Ideogram4Transformer2DModel",
             "JoyImageEditTransformer3DModel",
             "Kandinsky3UNet",
             "Kandinsky5Transformer3DModel",
@@ -475,6 +476,8 @@
             "HeliosPyramidModularPipeline",
             "HunyuanVideo15AutoBlocks",
             "HunyuanVideo15ModularPipeline",
+            "Ideogram4AutoBlocks",
+            "Ideogram4ModularPipeline",
             "LTXAutoBlocks",
             "LTXModularPipeline",
             "QwenImageAutoBlocks",
@@ -590,6 +593,7 @@
             "HunyuanVideoImageToVideoPipeline",
             "HunyuanVideoPipeline",
             "I2VGenXLPipeline",
+            "Ideogram4Pipeline",
             "IFImg2ImgPipeline",
             "IFImg2ImgSuperResolutionPipeline",
             "IFInpaintingPipeline",
@@ -1098,6 +1102,7 @@
             HunyuanVideoFramepackTransformer3DModel,
             HunyuanVideoTransformer3DModel,
             I2VGenXLUNet,
+            Ideogram4Transformer2DModel,
             JoyImageEditTransformer3DModel,
             Kandinsky3UNet,
             Kandinsky5Transformer3DModel,
@@ -1294,6 +1299,8 @@
             HeliosPyramidModularPipeline,
             HunyuanVideo15AutoBlocks,
             HunyuanVideo15ModularPipeline,
+            Ideogram4AutoBlocks,
+            Ideogram4ModularPipeline,
             LTXAutoBlocks,
             LTXModularPipeline,
             QwenImageAutoBlocks,
@@ -1405,6 +1412,7 @@
             HunyuanVideoImageToVideoPipeline,
             HunyuanVideoPipeline,
             I2VGenXLPipeline,
+            Ideogram4Pipeline,
             IFImg2ImgPipeline,
             IFImg2ImgSuperResolutionPipeline,
             IFInpaintingPipeline,

src/diffusers/models/__init__.py

@@ -118,6 +118,7 @@
     _import_structure["transformers.transformer_hunyuan_video15"] = ["HunyuanVideo15Transformer3DModel"]
     _import_structure["transformers.transformer_hunyuan_video_framepack"] = ["HunyuanVideoFramepackTransformer3DModel"]
     _import_structure["transformers.transformer_hunyuanimage"] = ["HunyuanImageTransformer2DModel"]
+    _import_structure["transformers.transformer_ideogram4"] = ["Ideogram4Transformer2DModel"]
     _import_structure["transformers.transformer_joyimage"] = ["JoyImageEditTransformer3DModel"]
     _import_structure["transformers.transformer_kandinsky"] = ["Kandinsky5Transformer3DModel"]
     _import_structure["transformers.transformer_longcat_audio_dit"] = ["LongCatAudioDiTTransformer"]
@@ -248,6 +249,7 @@
             HunyuanVideo15Transformer3DModel,
             HunyuanVideoFramepackTransformer3DModel,
             HunyuanVideoTransformer3DModel,
+            Ideogram4Transformer2DModel,
             JoyImageEditTransformer3DModel,
             Kandinsky5Transformer3DModel,
             LatteTransformer3DModel,

src/diffusers/models/transformers/__init__.py

@@ -39,6 +39,7 @@
     from .transformer_hunyuan_video15 import HunyuanVideo15Transformer3DModel
     from .transformer_hunyuan_video_framepack import HunyuanVideoFramepackTransformer3DModel
     from .transformer_hunyuanimage import HunyuanImageTransformer2DModel
+    from .transformer_ideogram4 import Ideogram4Transformer2DModel
     from .transformer_joyimage import JoyImageEditTransformer3DModel
     from .transformer_kandinsky import Kandinsky5Transformer3DModel
     from .transformer_longcat_audio_dit import LongCatAudioDiTTransformer