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

Documents Cosmos3DistilledModularPipeline with the same example prompt and first-frame image as the vLLM-Omni example, and adds the generated example output video.

.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

@@ -490,6 +490,77 @@ 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, using the same JSON-format upsampled prompt and first-frame image as the vLLM-Omni example above. The distilled checkpoint is not compatible with `Cosmos3OmniPipeline` or `Cosmos3OmniModularPipeline`; it must be loaded with `Cosmos3DistilledModularPipeline`.
+
+This path loads the full 64B model on a single device in BF16, so it needs a B200/GB200-class GPU. On H100/H200-class GPUs, use the multi-GPU vLLM-Omni serving configuration above instead.
+
+### 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
+
+Run this from the downloaded repo root, using the same `assets/example_prompt.json` and `assets/example_first_frame.png` inputs as the vLLM-Omni request. The example generates at 480p (`832x480` at 16:9), the recommended setting for this distilled I2V checkpoint.
+
+```python
+import json
+
+import torch
+from diffusers import Cosmos3DistilledModularPipeline
+from diffusers.utils import export_to_video, load_image
+
+# The prompt file holds the same positive and negative prompt fields the vLLM-Omni
+# example uses. Only the positive prompt is passed here: classifier-free guidance is
+# baked into the distilled weights, so the negative prompt has no effect.
+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`.

assets/example_output_diffusers.mp4

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