Cosmos 3

NVIDIA Cosmos 3 adalah model dasar dunia (WFM) terpadu untuk Physical AI — sebuah model omni tunggal yang menggabungkan generasi dunia, penalaran fisik, dan generasi aksi. Model ini menggantikan model Predict, Reason, dan Transfer yang terpisah dari rilis Cosmos sebelumnya: baik Anda membangun untuk robotika, kendaraan otonom, maupun ruang cerdas, Cosmos 3 memberikan satu fondasi untuk mensimulasikan dan memahami dunia fisik.

Yang disertakan dalam rilis ini:

• Model di Hugging Face Hub dengan kartu model dan lisensi
• Integrasi Cosmos 3 Diffusers untuk pipeline generasi (halaman ini)
• Skrip pelatihan pasca untuk penyesuaian halus Cosmos 3 pada data Anda sendiri
• Dataset generasi data sintetis (SDG) terbuka untuk AI Fisik

Apa yang baru di Cosmos 3

Perubahan terbesar dari rilis Cosmos sebelumnya adalah bahwa Cosmos 3 merupakan omni-model, yang dibangun di atas arsitektur Mixture-of-Transformers (MoT). Sebelumnya, pengembang bekerja dengan model-model terpisah untuk world generation (Predict), controlled generation (Transfer), scene understanding (Reason), dan action-policy generation. Cosmos 3 menyatukan semua fungsi tersebut dalam satu model yang melakukan penalaran dan generasi lintas modalitas dalam satu forward pass.

Dari satu model, Anda dapat:

• Hasilkan dunia video yang secara fisik masuk akal dari teks, gambar, atau input aksi (image-to-video, text-to-video, action-conditioned video generation).
• Berpikir tentang sifat-sifat fisik seperti gerak, kausalitas, dan hubungan spasial.
• Prediksikan urutan video dan aksi masa depan dari keadaan saat ini.
• Transfer adegan antar sudut pandang dan kondisi dengan kontrol struktural (segera hadir).

Di balik layar, satu Cosmos3OmniTransformer menjalankan model bahasa bergaya Qwen secara paralel dengan jalur generasi difusi: token teks mengalir melalui stream “pemahaman” kausal, sementara latens video dan suara mengalir melalui stream “generasi” yang diperhatikan secara bi-arah, yang disatukan oleh 3D multimodal RoPE. Lihat makalah Cosmos World Foundation Model Platform untuk latar belakang arsitekturnya.

Checkpoint yang tersedia

Dua checkpoint dirilis di Hub — nvidia/Cosmos3-Nano (lebih kecil, lebih cepat) dan nvidia/Cosmos3-Super (lebih besar, kualitas lebih tinggi). Kelas pipeline yang sama mendukung text-to-image, text-to-video, image-to-video, dan (dengan checkpoint yang mampu menghasilkan suara) text+image-to-video-with-sound — pilih repo dan gunakan tab per-model di masing-masing workflow di bawah.

Pastikan untuk melihat panduan Schedulers untuk mempelajari cara mengeksplorasi tradeoff antara kecepatan dan kualitas scheduler, serta lihat bagian reuse components across pipelines untuk mempelajari cara memuat komponen yang sama secara efisien ke dalam beberapa pipeline.

Denoising campuran FP8 W8A8/W8A16

Checkpoint ModelOpt FP8 resmi untuk Nano, Super, dan Edge dipublikasikan sebagai repositori Hub mereka sendiri: nvidia/Cosmos3-Nano-FP8, nvidia/Cosmos3-Super-FP8, dan nvidia/Cosmos3-Edge-FP8. Muat main dari repositori FP8. nvidia/Cosmos3-Super-Image2Video tidak memiliki repositori FP8 terpisah; muat dengan revision="fp8".

Semua checkpoint ini dikuantisasi dengan cara yang sama. W8A8 menggunakan bobot 8-bit dan aktivasi 8-bit (GEMM ModelOpt yang dipulihkan). W8A16 menggunakan kembali bobot 8-bit yang sama tetapi melewati kuantisasi aktivasi: bobot FP8 didekuantisasi dan linear standar dijalankan pada aktivasi BF16/FP16/FP32.

Menjalankan W8A8 pada setiap langkah dapat menghasilkan flickering yang terlihat pada pembuatan video multi-langkah. Oleh karena itu, checkpoint video Nano, Super, Super-I2V, dan Edge FP8 menyatakan jadwal di transformer/config.json: W8A16 pada 3 langkah pertama dan 3 langkah terakhir, W8A8 di tengah. Diffusers membaca jumlah tersebut dari checkpoint, bukan menghardcode-nya. Presisi dipilih sekali per langkah scheduler sehingga panggilan cond/uncond untuk classifier-free guidance cocok.

Generasi gambar dan checkpoint terdistil beberapa langkah tidak menunjukkan flickering tersebut, sehingga Super-T2I dan repositori terdistil 4-langkah FP8 tidak mendeklarasikan jadwal apa pun dan tetap W8A8 di setiap langkah. Jadwal ini juga hanya untuk ModelOpt FP8: backend kuantisasi lain (misalnya TorchAO) mempertahankan forward native mereka.

Muat repo FP8 dengan jalur restore yang sama seperti panduan ModelOpt. Repo tersebut sudah membawa konfigurasi kuantisasi. Presisi campuran kemudian mengikuti checkpoint secara otomatis:

import torch
from diffusers import Cosmos3OmniPipeline

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano-FP8",
    dtype=torch.bfloat16,
    device_map="cuda",
)
result = pipe(prompt="...", num_inference_steps=35)

Dua pilihan saat generate:

• Default (mixed_precision_format=None): jika checkpoint menyatakan diffusion_step_policy, jalankan W8A16 pada N langkah pertama/terakhir dan W8A8 native di tengah. Itulah resep yang dimaksud untuk video FP8 multi-langkah (lebih sedikit flickering daripada all-W8A8). Distilled 4-step dan Super-T2I FP8 mengabaikan policy, sehingga default-nya sudah all W8A8.
• mixed_precision_format="none": pertahankan setiap langkah pada W8A8 native. Lebih cepat, karena W8A16 adalah dequant + torch.nn.functional.linear alih-alih FP8 GEMM yang dipulihkan, tetapi video multi-langkah dapat berkedip. Gunakan ini untuk A/B pada jadwal atau untuk mencocokkan baseline yang sepenuhnya terkuantisasi.

Pada satu workstation Blackwell, Cosmos3-Nano-FP8 pada 720×1280 / 35 langkah sekitar 27% lebih lambat (T2I) dan 13% lebih lambat (T2V 49-frame) dengan jadwal campuran bawaan dibandingkan dengan "none". Angka-angka tersebut bukan jaminan throughput. Gunakan "fp8" hanya untuk memaksa jadwal first/last-N pada checkpoint ModelOpt FP8 yang tidak memiliki kebijakan.

Upsampling prompt

Cosmos 3 dilatih pada caption yang panjang dan sangat deskriptif. Untuk kualitas optimal, prompt teks pendek harus di-upsample menjadi struktur JSON tertentu sebelum diteruskan ke pipeline. Upsampler ini terdapat dalam paket cosmos-framework.

Mulai dari prompt teks biasa yang singkat dan simpan ke assets/prompt.txt. Untuk contoh teks-ke-video di bawah, prompt aslinya adalah “A robotic arm is cleaning a plate in a kitchen”:

mkdir -p assets
echo "A robotic arm is cleaning a plate in a kitchen" > assets/prompt.txt

Lalu, instal framework dan jalankan upsampler. Contoh di bawah ini melakukan upsampling untuk text-to-video menggunakan Opus-4.6:

git clone https://github.com/NVIDIA/cosmos-framework.git packages/cosmos-framework
pip install -e packages/cosmos-framework

export PROMPT_UPSAMPLER_ENDPOINT_URL="https://api.anthropic.com/v1/"
export PROMPT_UPSAMPLER_MODEL_NAME="claude-opus-4-6"
export PROMPT_UPSAMPLER_API_TOKEN="<your_token>"

python -m cosmos_framework.inference.prompt_upsampling \
    --input assets/prompt.txt \
    --output assets/example_t2v_prompt.json \
    --mode text2video \
    --endpoint-url "${PROMPT_UPSAMPLER_ENDPOINT_URL}" \
    --model "${PROMPT_UPSAMPLER_MODEL_NAME}" \
    --api-token "${PROMPT_UPSAMPLER_API_TOKEN}" \
    --resolution 720 \
    --aspect-ratio "16,9"

Ubah --mode agar sesuai dengan alur kerja yang Anda tuju (text2image, text2video, image2video). Perintah ini menulis prompt yang di-upsample ke file --output sebagai array JSON (satu objek per baris non-kosong di --input); berikan path .jsonl sebagai gantinya untuk mendapatkan satu objek JSON per baris. Untuk image2video, Anda juga harus menyediakan gambar kondisioning melalui --image-url (URL atau path lokal) atau --image-list (satu gambar per prompt).

Prompt positif yang sudah di-upsample sebelumnya (assets/example_t2v_prompt.json) dan prompt negatif (assets/negative_prompt.json) disediakan untuk kemudahan, dan digunakan oleh contoh generasi di bawah. Contoh memuat file JSON ini dan meneruskannya ke pipeline sebagai string JSON melalui json.dumps(...).

Teks-ke-video

Generasi multi-frame yang dikondisikan hanya pada teks. Pilih num_frames berdasarkan durasi target — nilai default num_frames=189 menghasilkan ≈ 7,9 detik pada 24 FPS. Prompt dan negative prompt dibaca dari file yang di-upsample menggunakan JSON, seperti yang dijelaskan dalam Prompt upsampling.

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    num_frames=189,
    height=720,
    width=1280,
    num_inference_steps=35,
    guidance_scale=6.0,
    fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_t2v.mp4", fps=24, macro_block_size=1)

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    num_frames=189,
    height=720,
    width=1280,
    num_inference_steps=35,
    guidance_scale=6.0,
    fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_t2v.mp4", fps=24, macro_block_size=1)

Teks-ke-gambar

Generasi satu bingkai. Model dikondisikan hanya pada prompt teks; berikan num_frames=1. Upsample dengan --mode text2image untuk menghasilkan prompt JSON.

import json
import torch
from diffusers import Cosmos3OmniPipeline

# JSON-upsampled prompt (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2i_prompt.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

result = pipe(prompt=json.dumps(json_prompt), num_frames=1, height=720, width=1280)
result.video[0].save("cosmos3_t2i.jpg", format="JPEG", quality=85)

import json
import torch
from diffusers import Cosmos3OmniPipeline

# JSON-upsampled prompt (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2i_prompt.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

result = pipe(prompt=json.dumps(json_prompt), num_frames=1, height=720, width=1280)
result.video[0].save("cosmos3_t2i.jpg", format="JPEG", quality=85)

Gambar-ke-video

Lewatkan gambar kondisioning melalui image=. Pipeline mengaitkan frame 0 ke gambar yang diberikan dan melakukan denoising pada sisanya. Gambar di-resize sambil mempertahankan rasio aspeknya, dipotong di tengah (center-crop) ke ukuran output yang diminta, dan dinormalisasi dengan pembulatan ekuivalen uint8. Gunakan --mode image2video untuk menghasilkan prompt JSON.

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import export_to_video, load_image

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_i2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

image = load_image(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/releases/download/assets/robot_153.jpg"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    image=image,
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_i2v.mp4", fps=24, macro_block_size=1)

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import export_to_video, load_image

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_i2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

image = load_image(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/releases/download/assets/robot_153.jpg"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    image=image,
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_i2v.mp4", fps=24, macro_block_size=1)

Video-ke-video

Lewatkan klip kondisioning melalui video= (misalnya dari load_video). Pipeline mengikat frame laten awal yang diberikan oleh condition_frame_indexes_vision (default [0, 1]) ke klip tersebut dan melakukan denoising pada sisanya. Gunakan condition_video_keep ("first" atau "last") untuk memilih dari ujung mana klip sumber yang lebih panjang frame kondisioning diambil. Seperti pada mode lainnya, prompt harus mengikuti struktur JSON deskriptif yang dijelaskan dalam Prompt upsampling.

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    video=video,
    condition_frame_indexes_vision=[0, 1],
    condition_video_keep="first",
    num_frames=189,
    height=720,
    width=1280,
    num_inference_steps=35,
    guidance_scale=6.0,
    fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_v2v.mp4", fps=24, macro_block_size=1)

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    video=video,
    condition_frame_indexes_vision=[0, 1],
    condition_video_keep="first",
    num_frames=189,
    height=720,
    width=1280,
    num_inference_steps=35,
    guidance_scale=6.0,
    fps=24.0,
)
# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "cosmos3_v2v.mp4", fps=24, macro_block_size=1)

Video-ke-video dengan suara

Ketika checkpoint membawa sound_tokenizer, tambahkan enable_sound=True ke panggilan video-ke-video untuk secara bersama-sama menghasilkan trek audio yang tersinkronisasi. Gelombang suara dikembalikan bersama video dan dapat dicampur ke dalam MP4 dengan encode_video().

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import encode_video, load_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    video=video,
    condition_frame_indexes_vision=[0, 1],
    condition_video_keep="first",
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_sound=True,
)

encode_video(
    result.video,
    fps=24,
    audio=result.sound,
    audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
    output_path="cosmos3_v2v_with_sound.mp4",
)

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import encode_video, load_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    video=video,
    condition_frame_indexes_vision=[0, 1],
    condition_video_keep="first",
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_sound=True,
)

encode_video(
    result.video,
    fps=24,
    audio=result.sound,
    audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
    output_path="cosmos3_v2v_with_sound.mp4",
)

Teks-ke-video dengan suara

Jika checkpoint membawa sound_tokenizer, berikan enable_sound=True untuk menghasilkan trek audio yang tersinkronisasi secara bersama. Gelombang suara dikembalikan bersama video dan dapat dicampur ke dalam MP4 dengan encode_video().

Ini adalah pemanggilan yang sama dengan contoh teks-ke-video di atas dengan enable_sound=True yang ditambahkan:

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import encode_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_sound_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_sound=True,
)

encode_video(
    result.video,
    fps=24,
    audio=result.sound,
    audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
    output_path="cosmos3_with_sound.mp4",
)

import json
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import encode_video

# JSON-upsampled positive and negative prompts (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2v_sound_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

result = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_sound=True,
)

encode_video(
    result.video,
    fps=24,
    audio=result.sound,
    audio_sample_rate=pipe.sound_tokenizer.config.sampling_rate,
    output_path="cosmos3_with_sound.mp4",
)

Generasi yang dikondisikan oleh aksi

Action runs mengelompokkan setiap input spesifik aksi ke dalam CosmosActionCondition yang diteruskan melalui argumen action alih-alih argumen tingkat atas image / video / height / width. Atur resolution_tier (256/480/704/720) sedekat mungkin dengan resolusi asli video input; parameter ini memilih kanvas conditioning. Cosmos 3 mendukung tiga mode aksi — policy, forward_dynamics, dan inverse_dynamics. policy dan forward_dynamics hanya melakukan conditioning pada frame pertama (sehingga image maupun video sama-sama berfungsi), sedangkan inverse_dynamics memerlukan video. Video conditioning untuk sebuah action run diatur pada action.video (atau action.image), bukan pada argumen video tingkat atas pipeline.

Lewatkan deskripsi tugas biasa sebagai prompt dan pilih kamera dengan action.view_point (default "ego_view"; juga "third_person_view", "wrist_view", "concat_view"). Pipeline mengubah ini menjadi caption JSON terstruktur yang digunakan untuk melatih model, sehingga prompt aksi tidak perlu di-upsample oleh LLM.

Kebijakan tindakan

Generasi kebijakan aksi memprediksi token video dan aksi masa depan dari bingkai observasi pertama, prompt teks, dan metadata domain aksi. Contoh di bawah ini menggunakan domain robot Bridge dan menuliskan chunk aksi yang diprediksi ke JSON dalam ruang aksi yang dinormalisasi oleh model.

import json

import torch
from diffusers import Cosmos3OmniPipeline, CosmosActionCondition
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

prompt = "Put the pot to the left of the purple item."
video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/action/bridge_20260501_0.mp4"
)

result = pipe(
    prompt=prompt,
    action=CosmosActionCondition(
        mode="policy",
        chunk_size=16,
        domain_name="bridge_orig_lerobot",
        resolution_tier=480,
        video=video,
        view_point="ego_view",
    ),
    fps=5,
    num_inference_steps=30,
    guidance_scale=1.0,
    use_system_prompt=False,
)

# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "sample.mp4", fps=5, macro_block_size=1)

if result.action is not None:
    with open("sample_action.json", "w") as f:
        json.dump(result.action[0].tolist(), f)

import json

import torch
from diffusers import Cosmos3OmniPipeline, CosmosActionCondition
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Super", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

prompt = "Put the pot to the left of the purple item."
video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/action/bridge_20260501_0.mp4"
)

result = pipe(
    prompt=prompt,
    action=CosmosActionCondition(
        mode="policy",
        chunk_size=16,
        domain_name="bridge_orig_lerobot",
        resolution_tier=480,
        video=video,
        view_point="ego_view",
    ),
    fps=5,
    num_inference_steps=30,
    guidance_scale=1.0,
    use_system_prompt=False,
)

# macro_block_size=1 allows arbitrary frame sizes (Cosmos3 outputs are not always divisible by 16).
export_to_video(result.video, "sample.mp4", fps=5, macro_block_size=1)

if result.action is not None:
    with open("sample_action.json", "w") as f:
        json.dump(result.action[0].tolist(), f)

SeaCache

SeaCache dinonaktifkan secara default. Cosmos 3 mendukung pengaktifan eksplisit dengan SeaCacheConfig. SeaCache menggunakan ulang residual transformer ketika indikator Spectral-Evolution-Aware berubah secara lambat, sehingga mengurangi jumlah eksekusi transformer penuh. Indikator ini dihitung dari latens visual mentah, termasuk frame kondisioning bersih untuk generasi gambar-ke-video. Aktifkan pada transformer dengan callback metadata scheduler dari pipeline:

import torch
from diffusers import Cosmos3OmniPipeline, SeaCacheConfig

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16, device_map="cuda"
)

pipe.transformer.enable_cache(SeaCacheConfig(threshold=0.2, max_consecutive_cached=2))

API tingkat model yang sama berfungsi dengan Cosmos3OmniPipeline, Cosmos3OmniModularPipeline, dan Cosmos3DistilledModularPipeline. SeaCache bersifat aproksimasi dan dapat mengubah output yang dihasilkan. Nonaktifkan dengan pipe.transformer.disable_cache() ketika Anda membutuhkan setiap langkah denoising untuk mengeksekusi transformer secara penuh. Status cache direset setelah setiap pemanggilan pipeline, dan cabang panduan kondisional serta non-kondisional mempertahankan riwayat yang independen.

Cosmos 3 mempertahankan gerbang SeaCache di luar lapisan dekodernya yang berulang, sehingga kompatibel dengan kompilasi regional. Kompilasi lapisan setelah mengaktifkan cache:

pipe.transformer.compile_repeated_blocks(fullgraph=True)

SeaCache juga mendukung helper paralel konteks Ulysses Cosmos 3 dan helper paralel tensor berbasis DTensor yang didokumentasikan di bawah. Keputusan cache disinkronkan antar rank. Kompilasi model penuh dan strategi pemecahan model lainnya tidak diklaim.

Paralelisme konteks

Untuk video panjang atau resolusi tinggi, satu langkah forward dapat melebihi anggaran memori dan latensi satu GPU. Cosmos 3 mendukung context parallelism (CP) untuk membagi dimensi sekuens di antara beberapa GPU, memecah komputasi attention sehingga setiap perangkat hanya menyimpan sebagian token.

Cosmos 3 mendukung paralelisme konteks Ulysses (pertukaran urutan/kepala all-to-all). Ring attention tidak didukung.

Berbeda dengan sebagian besar model diffusers, Cosmos 3 tidak menyambungkan CP ke dalam transformer atau jalur deklaratif enable_parallelism(): grouped-query attention-nya, stream pemahaman/generasi yang terpisah (stream generasi memperhatikan keduanya), dan panjang per-stream yang tidak seragam tidak dapat diekspresikan sebagai _cp_plan. Sebagai gantinya, model ini mengekspos seam shard/gather kecil yang no-op, dan implementasinya berada di examples/cosmos3/cosmos_parallel.py — sebuah modul mandiri yang dapat Anda baca dari awal hingga akhir dan sesuaikan. Modul ini menawarkan dua sumbu sharding yang ortogonal dan dapat dikomposisikan:

Gunakan salah satu atau keduanya secara bersamaan pada mesh 2-D (tp, cp) (lihat Mengakomodasi model besar dengan tensor parallelism).

Dua persyaratan khusus untuk Cosmos 3:

• Gunakan backend perhatian native. Cosmos 3 menggunakan grouped-query attention (GQA), dan backend SDPA native adalah satu-satunya yang menerima enable_gqa (cuDNN dan flash menolaknya). Helper memperluas kepala KV menjadi jumlah kepala query dan memanggil SDPA dengan enable_gqa=False sehingga tetap di-dispatch ke kernel flash (fallback matematika akan mematerialkan skor penuh [S, S] dan menyebabkan OOM pada urutan panjang).
• Derajat CP (Ulysses) harus membagi jumlah query-head (32 untuk Nano, 64 untuk Super); untuk TP, derajatnya harus membagi KV heads (8). Aliran pemahaman (teks) dan generasi (video/suara) di-shard secara independen sepanjang sequence, dan panjang yang tidak rata di-zero-pad secara internal menjadi kelipatan dari world size.

Jalankan

CLI lengkap examples/cosmos3/inference_cosmos3.py menggunakan Cosmos3OmniModularPipeline dan memanfaatkan kembali helper ini, sehingga semua modality (text-to-image/video, image-to-video, sound, action modes) dapat dijalankan multi-GPU melalui --tp-degree / --cp-degree. Jalankan dengan torchrun; --tp-degree * --cp-degree harus sama dengan --nproc_per_node. Setiap rank menghasilkan output yang sama; rank 0 yang menuliskannya.

# CP only — Nano (fits one GPU); CP degree must divide 32 query heads.
torchrun --nproc_per_node=4 examples/cosmos3/inference_cosmos3.py --model nano --cp-degree 4 --prompt "..."

# TP only — Super; TP degree must divide 64 query heads and 8 KV heads.
torchrun --nproc_per_node=4 examples/cosmos3/inference_cosmos3.py --model super --tp-degree 4 --prompt "..."

# TP + CP — Super, with sound (TP=2 x CP=2 across 4 GPUs).
torchrun --nproc_per_node=4 examples/cosmos3/inference_cosmos3.py \
    --model super --tp-degree 2 --cp-degree 2 --enable-sound --prompt "..."

Bobot Super yang berukuran ~120 GB tidak muat di satu GPU 96 GB, sehingga memerlukan TP; Nano muat di satu GPU, sehingga CP untuknya murni sebagai optimasi latensi. (Kedua flag diabaikan untuk menjalankan single-GPU.)

Melatih model besar dengan paralelisme tensor

CP memecah aktivasi tetapi mereplikasi setiap bobot di setiap rank, sehingga tidak mengurangi jejak bobot model — model yang tidak muat di satu GPU tetap tidak akan muat hanya dengan CP. Untuk memecah bobot, enable_cosmos3_tensor_parallel(transformer, tp_mesh) menerapkan tensor parallelism gaya Megatron pada sumbu mesh kedua yang ortogonal:

• Proyeksi attention dan MLP di-shard per kolom/baris di seluruh grup TP (to_q/to_k/to_v + add_q/k/v dan gate/up dari MLP bersifat paralel kolom; to_out/to_add_out dan down dari MLP bersifat paralel baris dengan all-reduce). Setiap rank pada akhirnya memiliki query_heads / tp kepala query dan kv_heads / tp kepala KV.
• TP dikomposisikan dengan CP pada mesh perangkat 2-D (tp, cp): TP membagi head/berat secara persisten, sedangkan CP memotong (shard) urutan di atasnya. Kendalanya adalah tp harus membagi habis KV heads (8), dan tp * cp harus membagi habis query heads (32 untuk Nano, 64 untuk Super).
• Bobot dimuat ke CPU dan dipartisi ke GPU secara per lapisan, sehingga model lengkap tidak pernah direalisasikan pada satu perangkat.

TP menerbitkan all-reduce pada setiap blok attention dan MLP, sehingga sangat berat dari segi bandwidth. Pada host tanpa NVLink, ini menjadi biaya yang dominan; utamakan derajat TP terkecil yang memungkinkan bobot muat, dan masukkan GPU yang tersisa ke CP.

Gunakan di pipeline modular Anda sendiri

Flag CLI sangat praktis, tetapi Anda dapat memanggil helper secara langsung dengan Cosmos3OmniModularPipeline. Muat konfigurasi pipeline dan komponen di CPU, terapkan TP sebelum memindahkan pipeline ke GPU lokal rank, beralih ke backend native, dan kemudian aktifkan CP. Jangan gunakan device_map untuk alur ini:

import os
import sys

import torch
import torch.distributed as dist
from diffusers import Cosmos3OmniModularPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from torch.distributed.device_mesh import init_device_mesh

# Make the helper module importable.
sys.path.insert(0, "examples/cosmos3")
from cosmos_parallel import (
    enable_cosmos3_context_parallel,
    enable_cosmos3_flash_attention,
    enable_cosmos3_tensor_parallel,
)

# torchrun sets RANK / WORLD_SIZE / LOCAL_RANK. Pick tp_degree * cp_degree == world size.
local_rank = int(os.environ["LOCAL_RANK"])
torch.cuda.set_device(local_rank)
dist.init_process_group("nccl")
mesh = init_device_mesh("cuda", (tp_degree, cp_degree), mesh_dim_names=("tp", "cp"))

# Load components on CPU first; a TP-sharded model may not fit one GPU.
pipe = Cosmos3OmniModularPipeline.from_pretrained(model_id)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()

if tp_degree > 1:
    enable_cosmos3_tensor_parallel(pipe.transformer, mesh["tp"])  # shard weights -> GPUs
pipe.to(f"cuda:{local_rank}")                                     # move the replicated remainder
pipe.transformer.set_attention_backend("native")
if cp_degree > 1:
    enable_cosmos3_context_parallel(pipe.transformer, mesh["cp"])  # shard the sequence
elif tp_degree > 1:
    enable_cosmos3_flash_attention(pipe.transformer)               # GQA-safe dense attention

# Modular pipelines replace components through update_components().
scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)
pipe.update_components(scheduler=scheduler)

# A single output name returns that value; a list returns a dictionary.
outputs = pipe(
    prompt='{"scene":"A robot arm in a kitchen"}',
    num_frames=189,
    height=720,
    width=1280,
    output=["videos", "sound", "sampling_rate", "action"],
)
videos = outputs["videos"]
sound = outputs["sound"]  # None unless sound generation was requested.
action = outputs["action"]  # None unless an action workflow produced actions.

Untuk CP saja (tanpa sharding bobot), gunakan mesh 1-D: init_device_mesh("cuda", (world_size,), mesh_dim_names=("cp",)) dan cukup enable_cosmos3_context_parallel.

enable_safety_checker() memuat dan mengaktifkan checker default; disable_safety_checker() secara eksplisit menonaktifkannya. Gunakan metode pipeline tersebut alih-alih argumen konstruksi task-pipeline enable_safety_checker= atau argumen pemanggilan enable_safety_check=. Pipeline modular juga tidak mengembalikan Cosmos3OmniPipelineOutput: gunakan output="videos" untuk frame saja, atau daftar output dan kamus yang dikembalikannya seperti yang ditunjukkan di atas, alih-alih result.video, result.sound, atau result.action.

Pada beberapa topologi multi-GPU, NCCL all-to-all pertama dapat hang. Jika eksekusi CP macet di awal langkah denoising pertama, setel NCCL_P2P_DISABLE=1 di lingkungan sebelum meluncurkan torchrun.

CP dan TP dapat dikombinasikan dengan semua alur kerja di atas (teks-ke-video, gambar-ke-video, teks-ke-video dengan suara, dan generasi yang dikondisikan oleh aksi) serta dengan checkpoint Nano dan Super — hanya baris konstruksi pipeline dan pengaturan paralelisme yang berubah.

Template metadata

tokenize_prompt appends short metadata sentences inside the user message so the LLM sees the conditioning the model was trained with. The positive prompt gets sentences like “The video is 7.9 seconds long and is of 24 FPS.” and “This video is of 720x1280 resolution.”; the negative prompt gets the inverse (”… is not …”).

Keduanya aktif secara default. Nonaktifkan salah satu pasangan melalui __call__:

result = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    add_duration_template=False,    # skip the duration sentence on both prompts
    add_resolution_template=False,  # skip the resolution sentence on both prompts
)

add_duration_template tidak berpengaruh ketika num_frames == 1 (mode gambar); dalam kasus tersebut, hanya kalimat resolusi yang ditambahkan.

Pemeriksa keamanan

Cosmos3 mengintegrasikan cosmos_guardrail CosmosSafetyChecker dan menjalankannya secara default. Guardrail teks menolak prompt yang tidak aman sebelum generasi (ValueError); guardrail video dijalankan pada frame yang didekode dan akan memikselasi wajah yang terdeteksi atau menolak output. Output audio tidak dijaga oleh guardrail.

Instal dependensi opsional untuk mengaktifkan checker default:

pip install cosmos_guardrail

Checker bersifat wajib di bawah Perjanjian Lisensi Model Terbuka NVIDIA. Dua flag di bawah ini ada untuk alur kerja pengujian dan pengembangan di mana guardrail akan menjadi redundan (misalnya, input sudah dibersihkan, atau Anda sengaja menguji pipeline pada input tepi).

Nonaktifkan saat konstruksi (tidak ada checker yang diinstansiasi, sehingga tidak ada model guardrail yang diunduh atau dimuat ke memori):

import torch
from diffusers import Cosmos3OmniPipeline

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano",
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
    enable_safety_checker=False,
)

Nonaktifkan untuk satu panggilan (pemeriksa tetap dimuat — berguna untuk bypass sekali pakai sambil mempertahankan default aktif untuk panggilan berikutnya):

result = pipe(
    prompt=prompt,
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_safety_check=False,
)

Untuk menyediakan checker kustom (misalnya, subclass no-op untuk pengujian cepat), lewati sebagai safety_checker=:

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano",
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
    safety_checker=MyCustomSafetyChecker(),
)

Cosmos3OmniPipeline

• semua
• call

Cosmos3OmniModularPipeline

Cosmos 3 juga tersedia sebagai pipeline Modular Diffusers. Pipeline berbasis tugas Cosmos3OmniPipeline tetap tersedia; pipeline modular ini berdampingan dengannya dan mencakup mode yang sama (text2image, text2video, image2video, video2video, generasi yang dikondisikan oleh aksi, dan transfer (kontrol struktural), dengan opsi suara jika didukung oleh checkpoint).

import torch
from diffusers import Cosmos3OmniModularPipeline

pipe = Cosmos3OmniModularPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano", dtype=torch.bfloat16
)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()

videos = pipe(
    prompt='{"scene":"A robot arm in a kitchen"}',
    num_frames=1,
    height=720,
    width=1280,
    output="videos",
)

# Modular pipelines expose declared outputs directly instead of using the task pipeline's
# `return_dict`/`Cosmos3OmniPipelineOutput` API.
image = videos[0]

Anda juga dapat memuat melalui ModularPipeline dan membiarkan konfigurasi repositori memilih kelas blok:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("nvidia/Cosmos3-Nano", dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()
videos = pipe(
    prompt='{"scene":"A robot arm in a kitchen"}', num_frames=1, height=720, width=1280, output="videos"
)

Untuk memeriksa atau menyesuaikan alur kerja modular Cosmos tertentu, gunakan available_workflows + get_workflow():

available = pipe.blocks.available_workflows
image2video_blocks = pipe.blocks.get_workflow("image2video")

Contoh modular untuk semua workflow yang ada

Pipeline modular mendukung tanda panggil yang sama seperti pipeline tugas. Cuplikan di bawah ini mencerminkan setiap contoh generasi yang ditunjukkan di atas (text2video, text2image, image2video, video2video, video2video_sound, text2video_sound, dan action_policy). Transfer (kontrol struktural) memiliki inputnya sendiri dan ditampilkan secara terpisah di Transfer modular di bawah ini.

import json
import torch
from diffusers import Cosmos3OmniModularPipeline, CosmosActionCondition
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import encode_video, export_to_video, load_image, load_video

pipe = Cosmos3OmniModularPipeline.from_pretrained("nvidia/Cosmos3-Nano", dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.enable_safety_checker()
pipe.to("cuda")  # or "mps", "xpu", "cpu"
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

# text2video
json_prompt = json.load(open("assets/example_t2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
videos = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    num_frames=189,
    height=720,
    width=1280,
    num_inference_steps=35,
    guidance_scale=6.0,
    fps=24.0,
    output="videos",
)
export_to_video(videos, "cosmos3_modular_t2v.mp4", fps=24, macro_block_size=1)

# text2image
json_prompt = json.load(open("assets/example_t2i_prompt.json"))
videos = pipe(prompt=json.dumps(json_prompt), num_frames=1, height=720, width=1280, output="videos")
videos[0].save("cosmos3_modular_t2i.jpg", format="JPEG", quality=85)

# image2video
json_prompt = json.load(open("assets/example_i2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
image = load_image("https://github.com/nvidia-cosmos/cosmos-dependencies/releases/download/assets/robot_153.jpg")
videos = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    image=image,
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    output="videos",
)
export_to_video(videos, "cosmos3_modular_i2v.mp4", fps=24, macro_block_size=1)

# video2video
json_prompt = json.load(open("assets/example_v2v_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt_i2v.json"))
video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_pouring.mp4"
)
videos = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    video=video,
    condition_frame_indexes_vision=[0, 1],
    condition_video_keep="first",
    num_frames=189,
    height=720,
    width=1280,
    num_inference_steps=35,
    guidance_scale=6.0,
    fps=24.0,
    output="videos",
)
export_to_video(videos, "cosmos3_modular_v2v.mp4", fps=24, macro_block_size=1)

# video2video_sound
outputs = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    video=video,
    condition_frame_indexes_vision=[0, 1],
    condition_video_keep="first",
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_sound=True,
    output=["videos", "sound", "sampling_rate"],
)
encode_video(
    outputs["videos"],
    fps=24,
    audio=outputs["sound"],
    audio_sample_rate=outputs["sampling_rate"],
    output_path="cosmos3_modular_v2v_with_sound.mp4",
)

# text2video_sound
json_prompt = json.load(open("assets/example_t2v_sound_prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
outputs = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    num_frames=189,
    height=720,
    width=1280,
    fps=24.0,
    enable_sound=True,
    output=["videos", "sound", "sampling_rate"],
)
encode_video(
    outputs["videos"],
    fps=24,
    audio=outputs["sound"],
    audio_sample_rate=outputs["sampling_rate"],
    output_path="cosmos3_modular_t2v_with_sound.mp4",
)

# action_policy
prompt = "Put the pot to the left of the purple item."
action_video = load_video(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/action/bridge_20260501_0.mp4"
)
outputs = pipe(
    prompt=prompt,
    action=CosmosActionCondition(
        mode="policy",
        chunk_size=16,
        domain_name="bridge_orig_lerobot",
        resolution_tier=480,
        video=action_video,
        view_point="ego_view",
    ),
    fps=5,
    num_inference_steps=30,
    guidance_scale=1.0,
    use_system_prompt=False,
    output=["videos", "action"],
)
export_to_video(outputs["videos"], "cosmos3_modular_action_policy.mp4", fps=5, macro_block_size=1)
if outputs["action"] is not None:
    with open("cosmos3_modular_action_policy.json", "w") as f:
        json.dump(outputs["action"][0].tolist(), f)

Transfer modular (kontrol struktural)

Transfer mengikuti video kontrol yang sudah dihitung sebelumnya (edge, blur, depth, segmentation, atau peta skenario dunia) yang diteruskan melalui control_videos= sebagai pemetaan {hint: video}. Ini hanya untuk video (tanpa image / video / action / enable_sound), prompt-nya adalah caption JSON yang sudah di-upsample sebelumnya (lihat Prompt upsampling), dan klip panjang dihasilkan secara autoregresif dalam potongan num_video_frames_per_chunk dan dijahit secara otomatis. guidance_scale adalah CFG teks yang biasa; control_guidance (!= 1.0) secara tambahan memperkuat sinyal kontrol. Nilai awal yang direkomendasikan per hint:

Diffusers tidak menyertakan aset kontrol. Aset yang sudah jadi (video kontrol + prompt.json yang sesuai untuk setiap hint, serta negative_prompt.json bersama) tersedia di Cosmos cookbook. Untuk contoh edge di bawah, unduh aset tersebut ke folder lokal assets/:

base=https://github.com/NVIDIA/cosmos/raw/refs/heads/main/cookbooks/cosmos3/generator/transfer/assets
mkdir -p assets/edge
curl -sL "$base/edge/control_edge.mp4" -o assets/edge/control_edge.mp4
curl -sL "$base/edge/prompt.json"      -o assets/edge/prompt.json
curl -sL "$base/negative_prompt.json"  -o assets/negative_prompt.json

import json
import torch
from diffusers import Cosmos3OmniModularPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video, load_video

pipe = Cosmos3OmniModularPipeline.from_pretrained("nvidia/Cosmos3-Nano", dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"
pipe.scheduler = UniPCMultistepScheduler.from_config(
    pipe.scheduler.config, flow_shift=10.0, use_karras_sigmas=False
)

# Downloaded into assets/ from the Cosmos cookbook (see the curl snippet above).
json_prompt = json.load(open("assets/edge/prompt.json"))
negative_prompt = json.load(open("assets/negative_prompt.json"))
control_edge = load_video("assets/edge/control_edge.mp4")

videos = pipe(
    prompt=json.dumps(json_prompt),
    negative_prompt=json.dumps(negative_prompt),
    control_videos={"edge": control_edge},
    num_frames=121,
    height=720,
    width=1280,
    fps=30.0,
    num_inference_steps=35,
    guidance_scale=3.0,
    control_guidance=1.5,
    output="videos",
)
export_to_video(videos, "cosmos3_modular_transfer_edge.mp4", fps=30, macro_block_size=1)

Teks-ke-gambar dan gambar-ke-video yang telah didistilasi (sedikit langkah)

Checkpoint distilasi beberapa langkah disajikan oleh Cosmos3DistilledModularPipeline (blok: Cosmos3DistilledBlocks); Cosmos3OmniModularPipeline dan Cosmos3OmniPipeline dasar tidak mendukungnya. num_inference_steps dikunci pada panjang konfigurasi pipeline distilled_sigmas (dari modular_model_index.json checkpoint) dan guidance_scale dipaksa menjadi 1.0 karena panduan sudah tertanam dalam bobot — memberikan nilai lain untuk salah satu dari keduanya akan memicu error, dan negative_prompt akan diberi peringatan serta diabaikan.

Checkpoint distilasi FP8 (revision="fp8") tidak mendeklarasikan kebijakan presisi campuran, sehingga setiap langkah tetap menggunakan W8A8 native.

Prompts mengikuti struktur JSON deskriptif yang sama dengan model non-distilled, sehingga teks pendek harus di-upsample terlebih dahulu — gunakan --mode text2image (T2I) atau --mode image2video (I2V) seperti yang dijelaskan dalam Prompt upsampling, lalu kirimkan JSON melalui json.dumps(...).

import json
import torch
from diffusers import Cosmos3DistilledModularPipeline
from diffusers.utils import export_to_video, load_image

# JSON-upsampled prompt (see "Prompt upsampling" above).
json_prompt = json.load(open("assets/example_t2i_prompt.json"))

repo = "nvidia/Cosmos3-Super-Text2Image-4Step"
pipe = Cosmos3DistilledModularPipeline.from_pretrained(repo, dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# text-to-image (distilled)
videos = pipe(
    prompt=json.dumps(json_prompt),
    num_frames=1,
    height=720,
    width=1280,
    output="videos",
)
videos[0].save("cosmos3_distilled_t2i.jpg", format="JPEG", quality=85)

# image-to-video (distilled) — load the I2V repo instead
# JSON-upsampled prompt (see "Prompt upsampling" above); upsampled from the source prompt
# "The right robotic hand picks up the red sphere on the shelf."
json_prompt_i2v = json.load(open("assets/example_i2v_prompt.json"))

repo_i2v = "nvidia/Cosmos3-Super-Image2Video-4Step"
pipe = Cosmos3DistilledModularPipeline.from_pretrained(repo_i2v, dtype=torch.bfloat16)
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = load_image(
    "https://github.com/nvidia-cosmos/cosmos-dependencies/raw/refs/heads/assets/cosmos3/inputs/vision/robot_153.jpg"
)
videos = pipe(
    prompt=json.dumps(json_prompt_i2v),
    image=image,
    num_frames=189,
    height=720,
    width=1280,
    output="videos",
)
export_to_video(videos, "cosmos3_distilled_i2v.mp4", fps=24, macro_block_size=1)

• semua
• call

Cosmos3DistilledModularPipeline

• semua
• call

CosmosActionCondition

Cosmos3OmniPipelineOutput