Add Diffusers usage section for the distilled 4-step T2I pipeline (#17)

- Add Diffusers usage section for the distilled 4-step T2I pipeline (4f396a09a7b98d7627f78bb216b00abc2d596a9b)


Co-authored-by: Yuliya Zhautouskaya <yzhautouskay@users.noreply.huggingface.co>

.gitattributes

@@ -38,3 +38,4 @@ assets/example_image.png filter=lfs diff=lfs merge=lfs -text
 images/aa-t2i-all-models-2026-07-17.png filter=lfs diff=lfs merge=lfs -text
 images/aa-t2i-open-models-2026-07-17.png filter=lfs diff=lfs merge=lfs -text
 assets/benchmark-text2image.png filter=lfs diff=lfs merge=lfs -text
+assets/example_output_diffusers.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -196,6 +196,7 @@ Our AI models are designed and/or optimized to run on NVIDIA GPU-accelerated sys
 
 - [PyTorch](https://github.com/nvidia/cosmos3)
 - [vLLM-Omni](https://github.com/vllm-project/vllm-omni)
+- [Hugging Face Diffusers](https://github.com/huggingface/diffusers)
 
 **Supported Hardware Microarchitecture Compatibility:**
 
@@ -494,6 +495,70 @@ Example output generated from `assets/example_caption.json`:
 
 ![example_image](assets/example_image.png)
 
+## Usage: Run Inference with Diffusers
+
+`Cosmos3-Super-Text2Image-4Step` is supported by the Hugging Face Diffusers **modular** pipeline. The distilled checkpoint is not compatible with `Cosmos3OmniPipeline` or `Cosmos3OmniModularPipeline`; it must be loaded with `Cosmos3DistilledModularPipeline`.
+
+### Install
+
+Install Diffusers from the main branch until a release containing `Cosmos3DistilledModularPipeline` is available:
+
+```bash
+uv venv --python 3.13 --seed --managed-python
+source .venv/bin/activate
+uv pip install \
+  "diffusers @ git+https://github.com/huggingface/diffusers.git" \
+  accelerate \
+  av \
+  cosmos_guardrail \
+  huggingface_hub \
+  imageio \
+  imageio-ffmpeg \
+  torch \
+  torchvision \
+  transformers
+```
+
+The safety checker requires access to the gated [nvidia/Cosmos-1.0-Guardrail](https://huggingface.co/nvidia/Cosmos-1.0-Guardrail) repository.
+
+### Example: Text to Image Generation
+
+```python
+import json
+
+import torch
+from diffusers import Cosmos3DistilledModularPipeline
+
+json_prompt = json.load(open("assets/example_caption.json"))
+json_prompt["resolution"] = {"H": 768, "W": 768}
+json_prompt["aspect_ratio"] = "1,1"
+
+pipe = Cosmos3DistilledModularPipeline.from_pretrained("nvidia/Cosmos3-Super-Text2Image-4Step")
+pipe.load_components(torch_dtype=torch.bfloat16)
+pipe.enable_safety_checker()
+pipe.to("cuda")
+
+images = pipe(
+    prompt=json.dumps(json_prompt),
+    num_frames=1,
+    height=768,
+    width=768,
+    add_resolution_template=False,
+    generator=torch.Generator(device="cuda").manual_seed(1143),
+    output="videos",
+)
+images[0].save("cosmos3_t2i_4step_diffusers.png")
+print("Saved image to cosmos3_t2i_4step_diffusers.png")
+```
+
+Single-frame generation uses `num_frames=1`, and the frame comes back through the pipeline's `videos` output.
+
+The 4-step schedule and the guidance scale come from the checkpoint: `num_inference_steps` is fixed to the length of the distilled sigma schedule and `guidance_scale` is forced to `1.0`, so passing any other value raises an error. `negative_prompt` is ignored, and unlike the base Cosmos3 models there is no scheduler to swap in and no `flow_shift` to set.
+
+Example output generated from `assets/example_caption.json`:
+
+![example_image](https://huggingface.co/nvidia/Cosmos3-Super-Text2Image-4Step/resolve/main/assets/example_output_diffusers.png)
+
 ## Limitations
 
 Cosmos3 may produce imperfect outputs in challenging scenarios. Generation artifacts include temporal inconsistency, unstable camera or object motion, imprecise physical interactions, inaccurate audio-video synchronization, and action-state drift — especially in long-horizon or high-resolution outputs. Reasoning may also be incorrect: object states, causal relationships, spatial geometry, temporal ordering, agent intent, and future outcomes can be misinferred, and complex or long-context inputs may yield hallucinated entities, inconsistent interpretations, or implausible predictions. Because the model lacks an explicit physics simulator, 3D geometry, 4D space-time evolution, object permanence, contact dynamics, and physical laws are only approximated — producing artifacts such as disappearing or morphing objects, unrealistic collisions, and physically implausible motions. Quality further degrades in out-of-distribution environments, safety-critical edge cases, and domains underrepresented in training.
@@ -502,7 +567,7 @@ Cosmos3 outputs should not be treated as physically accurate simulation, reliabl
 
 ## Inference
 
-**Acceleration Engine:** [PyTorch](https://pytorch.org/), [vLLM-Omni](https://github.com/vllm-project/vllm-omni)
+**Acceleration Engine:** [PyTorch](https://pytorch.org/), [vLLM-Omni](https://github.com/vllm-project/vllm-omni), [Hugging Face Diffusers](https://github.com/huggingface/diffusers)
 
 **Test Hardware:** RTX PRO 6000, H20, H100, H200, B200