Add Diffusers usage section for the distilled 4-step I2V pipeline

.gitattributes

@@ -38,3 +38,4 @@ assets/example_first_frame.png filter=lfs diff=lfs merge=lfs -text
 assets/example_output.mp4 filter=lfs diff=lfs merge=lfs -text
 images/aa-i2v-all-models-2026-07-17.png filter=lfs diff=lfs merge=lfs -text
 images/aa-i2v-open-models-2026-07-17.png filter=lfs diff=lfs merge=lfs -text
+assets/example_output_diffusers.mp4 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:**
 
@@ -490,6 +491,70 @@ Example output generated from `assets/example_first_frame.png`:
 
 <video controls width="832" height="480" src="https://huggingface.co/nvidia/Cosmos3-Super-Image2Video-4Step/resolve/main/assets/example_output.mp4"></video>
 
+## Usage: Run Inference with Diffusers
+
+`Cosmos3-Super-Image2Video-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: Image to Video Generation
+
+```python
+import json
+
+import torch
+from diffusers import Cosmos3DistilledModularPipeline
+from diffusers.utils import export_to_video, load_image
+
+json_prompt = json.load(open("assets/example_prompt.json"))
+image = load_image("assets/example_first_frame.png")
+
+pipe = Cosmos3DistilledModularPipeline.from_pretrained("nvidia/Cosmos3-Super-Image2Video-4Step")
+pipe.load_components(torch_dtype=torch.bfloat16)
+pipe.enable_safety_checker()
+pipe.to("cuda")
+
+videos = pipe(
+    prompt=json_prompt["prompt"],
+    image=image,
+    num_frames=189,
+    height=480,
+    width=832,
+    fps=24,
+    add_resolution_template=False,
+    add_duration_template=False,
+    output="videos",
+)
+export_to_video(videos, "cosmos3_i2v_4step_diffusers.mp4", fps=24, macro_block_size=1)
+print("Saved video to cosmos3_i2v_4step_diffusers.mp4")
+```
+
+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_first_frame.png`:
+
+<video controls width="832" height="480" src="https://huggingface.co/nvidia/Cosmos3-Super-Image2Video-4Step/resolve/main/assets/example_output_diffusers.mp4"></video>
+
 ### Inferencing with Custom Prompts
 
 `Cosmos3-Super-Image2Video-4Step` supports dense natural-language prompts together with a first-frame image, and it also supports JSON-format upsampled prompts for improved quality. The recommended way to prepare an upsampled prompt is to use [Prepare Prompts with Prompt Upsampling](#usage-prepare-prompts-with-prompt-upsampling). The helper below is a simple proof-of-concept script for building a JSON-format prompt from a custom natural-language instruction and the input image. It requires an OpenAI-compatible VLM model like `claude-opus-4.7` and `gpt-5.5`.
@@ -512,7 +577,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
 

assets/example_output_diffusers.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7337f6ae74b214bcca061c7de85e952e8cd8206d69755e8fb2fdb46784aa2641
+size 1135801