#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença. -->

# Cosmos 3

O NVIDIA Cosmos 3 é um modelo de fundação de mundo (WFM) unificado para IA Física — um único modelo omni que combina geração de mundos, raciocínio físico e geração de ações. Ele substitui os modelos separados Predict, Reason e Transfer das versões anteriores do Cosmos: seja você construindo para robótica, veículos autônomos ou espaços inteligentes, o Cosmos 3 oferece uma única base para simular e compreender o mundo físico.

O que está sendo lançado nesta versão:

- Modelos no Hugging Face Hub com cartões de modelo e licenciamento
- Integração do Cosmos 3 Diffusers para pipelines de geração (esta página)
- Scripts de pós-treinamento para ajuste fino do Cosmos 3 com seus próprios dados
- Conjuntos de dados abertos de geração de dados sintéticos (SDG) para IA física

## Novidades no Cosmos 3

A maior mudança em relação às versões anteriores do Cosmos é que o Cosmos 3 é um *omni-model*, construído sobre uma arquitetura Mixture-of-Transformers (MoT). Anteriormente, os desenvolvedores trabalhavam com modelos separados para geração de mundo (Predict), geração controlada (Transfer), compreensão de cena (Reason) e geração de política de ação. O Cosmos 3 unifica todos esses componentes em um único modelo que raciocina e gera entre modalidades em uma única passagem de frente.

A partir de um modelo, você pode:

- Gere mundos de vídeo fisicamente plausíveis a partir de texto, imagens ou entradas de ação (geração de vídeo a partir de imagem, geração de vídeo a partir de texto, geração de vídeo condicionada por ação).
- Raciocinar sobre propriedades físicas, como movimento, causalidade e relações espaciais.
- Preveja sequências futuras de vídeo e ações a partir do estado atual.
- Transfira cenas entre pontos de vista e condições com controle estrutural *(em breve)*.

Por baixo dos panos, uma única instância de `Cosmos3OmniTransformer` executa um modelo de linguagem no estilo Qwen em paralelo com um caminho de geração por difusão: os tokens de texto fluem por um fluxo causal de "compreensão", enquanto os latentes de vídeo e som fluem por um fluxo de "geração" com atenção bidirecional, unidos por um RoPE multimodal 3D. Consulte o [artigo da plataforma de modelos fundacionais do Cosmos World](https://huggingface.co/papers/2501.03575) para o contexto arquitetural.

## Checkpoints disponíveis

Dois checkpoints são publicados no Hub — [`nvidia/Cosmos3-Nano`](https://huggingface.co/nvidia/Cosmos3-Nano) (menor, mais rápido) e [`nvidia/Cosmos3-Super`](https://huggingface.co/nvidia/Cosmos3-Super) (maior, de qualidade superior). A mesma classe de pipeline suporta texto-para-imagem, texto-para-vídeo, imagem-para-vídeo e (com um checkpoint capaz de gerar som) texto+imagem-para-vídeo-com-som — escolha um repositório e use a aba específica de cada modelo em cada fluxo de trabalho abaixo.

> [!TIP]
> Certifique-se de consultar o [guia](../../using-diffusers/schedulers) de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção [reutilização de componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

## Denoising misto FP8 W8A8/W8A16

Os checkpoints oficiais ModelOpt FP8 para Nano, Super e Edge são publicados como repositórios próprios no Hub: [`nvidia/Cosmos3-Nano-FP8`](https://huggingface.co/nvidia/Cosmos3-Nano-FP8), [`nvidia/Cosmos3-Super-FP8`](https://huggingface.co/nvidia/Cosmos3-Super-FP8) e [`nvidia/Cosmos3-Edge-FP8`](https://huggingface.co/nvidia/Cosmos3-Edge-FP8). Carregue o `main` do repositório FP8. [`nvidia/Cosmos3-Super-Image2Video`](https://huggingface.co/nvidia/Cosmos3-Super-Image2Video) não possui um repositório FP8 separado; carregue-o com `revision="fp8"`.

Todos esses checkpoints são quantizados da mesma forma. **W8A8** usa pesos de 8 bits e ativações de 8 bits (o GEMM do ModelOpt restaurado). **W8A16** reutiliza os mesmos pesos de 8 bits, mas ignora a quantização das ativações: o peso FP8 é desquantizado e uma operação linear padrão é executada em ativações BF16/FP16/FP32.

Executar W8A8 em cada etapa pode produzir um efeito de flickering visível na geração de vídeo em múltiplas etapas. Por isso, os checkpoints de vídeo Nano, Super, Super-I2V e Edge FP8 declaram um agendamento em `transformer/config.json`: **W8A16 nas primeiras 3 e nas últimas 3 etapas**, **W8A8 no meio**. O Diffusers lê essas contagens do checkpoint em vez de fixá-las no código. A precisão é escolhida uma vez por etapa do agendador para que as chamadas cond/uncond do classifier-free guidance correspondam.

A geração de imagens e os checkpoints destilados de poucas etapas não apresentam esse flickering, portanto o Super-T2I e os repositórios destilados de 4 etapas em FP8 não declaram nenhum schedule e permanecem em W8A8 em todas as etapas. O schedule também é exclusivo do **ModelOpt FP8**: outros backends de quantização (por exemplo, TorchAO) mantêm seus forwards nativos.

Carregue um repositório FP8 com o mesmo caminho de restauração do [guia do ModelOpt](../../quantization/modelopt). O repositório já contém a configuração de quantização. A precisão mista, então, segue automaticamente o checkpoint:

```python
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)
```

Duas opções no momento da geração:

- **Padrão** (`mixed_precision_format=None`): se o checkpoint declarar `diffusion_step_policy`, execute W8A16 nos primeiros/últimos N passos e W8A8 nativo no meio. Essa é a receita prevista para **video** FP8 de múltiplos passos (menos flickering do que tudo em W8A8). Os modelos FP8 destilados de 4 passos e Super-T2I omitem a política, então o padrão já é tudo em W8A8.
- **`mixed_precision_format="none"`**: mantém cada etapa no W8A8 nativo. Mais rápido, pois o W8A16 é desquantização + `torch.nn.functional.linear` em vez do GEMM FP8 restaurado, mas vídeos de múltiplas etapas podem apresentar flicker. Use isso para comparar o agendamento ou para corresponder a uma linha de base totalmente quantizada.

Em uma workstation Blackwell, o Cosmos3-Nano-FP8 em 720×1280 / 35 passos foi cerca de **27% mais lento** (T2I) e **13% mais lento** (T2V de 49 quadros) com o agendamento misto padrão do que com `"none"`. Esses números não são uma garantia de throughput. Passe `"fp8"` apenas para forçar o agendamento first/last-N em um checkpoint ModelOpt FP8 que não possui política.

## Ampliação de prompt

O Cosmos 3 foi treinado com legendas longas e altamente descritivas. Para obter a qualidade ideal, prompts de texto curtos devem ser **ampliados para uma estrutura JSON específica** antes de serem passados para o pipeline. O amplificador está no pacote [cosmos-framework](https://github.com/NVIDIA/cosmos-framework).

Comece com um prompt curto em texto simples e salve-o em `assets/prompt.txt`. Para o exemplo de texto para vídeo abaixo, o prompt original é *"A robotic arm is cleaning a plate in a kitchen"*:

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

Em seguida, instale o framework e execute o upsampler. O exemplo abaixo faz o upsampling para text-to-video usando Opus-4.6:

```bash
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"
```

Alterne `--mode` para corresponder ao fluxo de trabalho que você está direcionando (`text2image`, `text2video`, `image2video`). O comando grava os prompts ampliados no arquivo `--output` como um array JSON (um objeto por linha não vazia em `--input`); passe um caminho `.jsonl` em vez disso para obter um objeto JSON por linha. Para `image2video`, você também deve fornecer a imagem de condicionamento via `--image-url` (uma URL ou caminho local) ou `--image-list` (uma imagem por prompt).

Um prompt positivo pré-ampleado (`assets/example_t2v_prompt.json`) e um prompt negativo (`assets/negative_prompt.json`) são fornecidos para conveniência e são usados nos exemplos de geração abaixo. Os exemplos carregam esses arquivos JSON e os passam para o pipeline como strings JSON via `json.dumps(...)`.

## Texto para vídeo

Geração multi-frame condicionada apenas em texto. Escolha `num_frames` com base na duração alvo — o padrão `num_frames=189` produz ≈ 7,9 s a 24 FPS. O prompt e o prompt negativo são lidos dos arquivos JSON-ampleados descritos em [Ampliação de prompt](#prompt-upsampling).

```python
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)
```

```python
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)
```

## Texto para imagem

Geração de quadro único. O modelo é condicionado apenas no prompt de texto; passe `num_frames=1`. Use `--mode text2image` para fazer o upsample e produzir o prompt em JSON.

```python
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)
```

```python
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)
```

## Imagem para vídeo

Passe uma imagem de condicionamento via `image=`. O pipeline ancora o frame 0 à imagem fornecida e remove o ruído dos demais. A imagem é redimensionada preservando sua proporção, recortada centralmente para o tamanho de saída solicitado e normalizada com arredondamento equivalente a uint8. Use `--mode image2video` para gerar o prompt em JSON.

```python
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)
```

```python
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)
```

## Vídeo-para-vídeo

Passe um clipe de condicionamento via `video=` (por exemplo, de `load_video`). O pipeline ancora os quadros latentes iniciais definidos por `condition_frame_indexes_vision` (padrão `[0, 1]`) ao clipe e remove o ruído do restante. Use `condition_video_keep` (`"first"` ou `"last"`) para escolher de qual extremidade de um clipe de origem mais longo os quadros de condicionamento são extraídos. Assim como nos outros modos, o prompt deve seguir a estrutura JSON descritiva detalhada em [Ampliação de prompt](#prompt-upsampling).

```python
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)
```

```python
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)
```

## Vídeo-para-vídeo com som

Quando o checkpoint inclui um `sound_tokenizer`, adicione `enable_sound=True` à chamada de vídeo-para-vídeo para gerar simultaneamente uma trilha de áudio sincronizada. A forma de onda é retornada junto com o vídeo e pode ser multiplexada no MP4 com [encode_video()](/docs/diffusers/v0.43.0/pt/api/utilities#diffusers.utils.encode_video).

```python
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",
)
```

```python
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",
)
```

## Texto para vídeo com som

Quando o checkpoint contém um `sound_tokenizer`, passe `enable_sound=True` para gerar simultaneamente uma trilha de áudio sincronizada. A forma de onda é retornada junto com o vídeo e pode ser multiplexada no MP4 com [encode_video()](/docs/diffusers/v0.43.0/pt/api/utilities#diffusers.utils.encode_video).

Esta é a mesma chamada do exemplo de texto para vídeo acima, com `enable_sound=True` adicionado:

```python
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",
)
```

```python
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",
)
```

## Geração condicionada por ação

Action runs agrupa cada entrada específica de ação em um [CosmosActionCondition](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.CosmosActionCondition) passado via argumento `action`, em vez dos argumentos de nível superior `image` / `video` / `height` / `width`. Defina `resolution_tier` (`256`/`480`/`704`/`720`) próximo à resolução nativa do vídeo de entrada; ele seleciona o canvas de condicionamento. O Cosmos 3 suporta três modos de ação — `policy`, `forward_dynamics` e `inverse_dynamics`. `policy` e `forward_dynamics` condicionam apenas no primeiro quadro (portanto, tanto `image` quanto `video` funcionam), enquanto `inverse_dynamics` exige um `video`. O vídeo de condicionamento para uma execução de ação é definido em `action.video` (ou `action.image`), e não no argumento de nível superior `video` do pipeline.

Passe uma descrição de tarefa simples como `prompt` e escolha a câmera com `action.view_point` (padrão `"ego_view"`; também `"third_person_view"`, `"wrist_view"`, `"concat_view"`). O pipeline converte esses elementos na legenda JSON estruturada em que o modelo foi treinado, portanto, os prompts de ação não devem ser expandidos por um LLM.

### Política de ação

A geração de política de ação prevê tokens de vídeo e de ação futuros a partir do primeiro quadro de observação, do prompt de texto e dos metadados do domínio de ação. O exemplo abaixo usa o domínio do robô Bridge e grava o bloco de ação previsto em JSON no espaço de ação normalizado pelo modelo.

```python
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)
```

```python
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 é desabilitado por padrão. O Cosmos 3 suporta a ativação explícita por meio de [SeaCacheConfig](/docs/diffusers/v0.43.0/pt/api/cache#diffusers.SeaCacheConfig). O SeaCache reutiliza resíduos do transformer quando o indicador Spectral-Evolution-Aware muda lentamente, reduzindo o número de execuções completas do transformer. Ele calcula o indicador a partir dos latentes visuais brutos, incluindo os quadros de condicionamento limpos para a geração de imagem para vídeo. Ative-o no transformer com callbacks de metadados do agendador a partir do pipeline:

```python
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))
```

A mesma API de nível de modelo funciona com [Cosmos3OmniPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline), [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) e [Cosmos3DistilledModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline). O SeaCache é aproximado e pode alterar as saídas geradas. Desative-o com `pipe.transformer.disable_cache()` quando for necessário que cada etapa de desruidamento execute o transformador completo. O estado do cache é reiniciado após cada chamada do pipeline, e os ramos de orientação condicional e incondicional mantêm históricos independentes.

O Cosmos 3 mantém o gate do SeaCache fora das camadas repetidas do decodificador, o que o torna compatível com compilação regional. Compile as camadas após habilitar o cache:

```python
pipe.transformer.compile_repeated_blocks(fullgraph=True)
```

O SeaCache também oferece suporte aos helpers de paralelismo de contexto Ulysses do Cosmos 3 e de paralelismo de tensor baseado em DTensor, documentados abaixo. As decisões de cache são sincronizadas entre os ranks. Não há garantia de compilação do modelo completo nem de outras estratégias de sharding de modelo.

## Paralelismo de contexto

Para vídeos longos ou altas resoluções, uma única passagem de frente pode exceder o orçamento de memória e latência de uma única GPU. O Cosmos 3 oferece suporte a **paralelismo de contexto (CP)** para dividir a dimensão da sequência entre várias GPUs, separando o cálculo de atenção para que cada dispositivo mantenha apenas uma fatia dos tokens.

O Cosmos 3 suporta paralelismo de contexto **Ulysses** (troca de sequência/cabeça all-to-all). O ring attention não é suportado.

Diferente da maioria dos modelos de difusores, o Cosmos 3 não **incorpora** o CP no transformer nem no caminho declarativo `enable_parallelism()`: sua atenção de consulta agrupada, seus fluxos separados de compreensão/geração (o fluxo de geração atende a ambos) e seus comprimentos irregulares por fluxo não podem ser expressos como um `_cp_plan`. Em vez disso, o modelo expõe pequenas emendas de shard/gather sem operação, e a implementação está em [`examples/cosmos3/cosmos_parallel.py`](https://github.com/huggingface/diffusers/blob/main/examples/cosmos3/cosmos_parallel.py) — um módulo autossuficiente que você pode ler do início ao fim e adaptar. Ele oferece dois eixos de sharding ortogonais e composáveis:

| Auxiliar | Shards | Usar para |
|---|---|---|
| `enable_cosmos3_context_parallel(transformer, cp_mesh)` | sequência (CP / Ulysses) | latência em um modelo que cabe em uma GPU (`Nano`) |
| `enable_cosmos3_tensor_parallel(transformer, tp_mesh)` | pesos (TP) | ajustando um modelo que não cabe em uma única GPU (`Super`) |

Use um ou ambos juntos em uma malha 2-D `(tp, cp)` (veja [Ajustando modelos grandes com paralelismo de tensor](#fitting-large-models-with-tensor-parallelism)).

Duas exigências são específicas do Cosmos 3:

- Use o backend de atenção `native`. O Cosmos 3 usa grouped-query attention (GQA), e o backend SDPA nativo é o único que aceita `enable_gqa` (cuDNN e flash o rejeitam). Os helpers expandem as cabeças KV para o número de cabeças de query e chamam SDPA com `enable_gqa=False` para que ainda assim seja despachado para o kernel flash (o fallback matemático materializaria as pontuações completas de `[S, S]` e causaria OOM em sequências longas).
- O grau de CP (Ulysses) deve dividir o número de cabeças de query (32 para `Nano`, 64 para `Super`); para TP, o grau deve dividir as cabeças KV (8). Os fluxos de compreensão (texto) e geração (vídeo/som) são fragmentados independentemente ao longo da sequência, e comprimentos irregulares são preenchidos com zeros internamente até um múltiplo do tamanho do mundo.

### Execute

A CLI completa [`examples/cosmos3/inference_cosmos3.py`](https://github.com/huggingface/diffusers/blob/main/examples/cosmos3/inference_cosmos3.py) usa [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) e reutiliza esses helpers, de modo que **qualquer modalidade** (texto-para-imagem/vídeo, imagem-para-vídeo, som, modos de ação) é executada em multi-GPU via `--tp-degree` / `--cp-degree`. Inicie com [torchrun](https://docs.pytorch.org/docs/stable/elastic/run.html); `--tp-degree * --cp-degree` deve ser igual a `--nproc_per_node`. Cada rank produz a mesma saída; o rank 0 a grava.

```bash
# 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 "..."
```

Os ~120 GB de pesos do `Super` não cabem em uma única GPU de 96 GB, portanto ele requer TP; o `Nano` cabe em uma única GPU, então o CP para ele é uma otimização pura de latência. (Omita ambas as flags para executar em uma única GPU.)

### Treinando modelos grandes com paralelismo de tensor

CP faz o sharding das *activations*, mas replica todos os pesos em cada rank, portanto não reduz a pegada de pesos de um modelo — um modelo que não cabe em uma única GPU ainda não caberá apenas com CP. Para fazer o sharding dos **pesos**, `enable_cosmos3_tensor_parallel(transformer, tp_mesh)` aplica tensor parallelism no estilo Megatron em um segundo eixo de malha ortogonal:

- As projeções de atenção e MLP são particionadas por coluna/linha no grupo de TP (`to_q/to_k/to_v` + `add_q/k/v` e os `gate/up` dos MLPs são paralelos por coluna; `to_out/to_add_out` e os `down` dos MLPs são paralelos por linha com um all-reduce). Cada rank acaba possuindo `query_heads / tp` cabeças de query e `kv_heads / tp` cabeças de KV.
- O TP se compõe com o CP em uma malha de dispositivos 2D `(tp, cp)`: o TP divide cabeças/pesos de forma persistente, e o CP faz o sharding da sequência por cima. As restrições são que `tp` deve dividir as cabeças KV (8) e que `tp * cp` deve dividir as cabeças de query (32 para `Nano`, 64 para `Super`).
- Os pesos são carregados na CPU e distribuídos nos GPUs camada por camada, de modo que o modelo completo nunca é materializado em um único dispositivo.

> [!TIP]
> O TP emite um all-reduce em cada bloco de atenção e MLP, o que exige muita largura de banda. Em hosts sem NVLink, esse é o custo dominante; prefira o menor grau de TP que permita que os pesos caibam e coloque os GPUs restantes no CP.

### Use-o em seu próprio pipeline modular

As flags de CLI são convenientes, mas você pode chamar os helpers diretamente com [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline). Carregue a configuração do pipeline e os componentes na CPU, aplique TP *antes* de mover o pipeline para a GPU local do rank, alterne para o backend `native` e, em seguida, ative o CP. Não use `device_map` para este fluxo:

```python
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.
```

Apenas para CP (sem sharding de pesos), use uma malha 1-D: `init_device_mesh("cuda", (world_size,), mesh_dim_names=("cp",))` e apenas `enable_cosmos3_context_parallel`.

`enable_safety_checker()` carrega e habilita o verificador padrão; `disable_safety_checker()` o desabilita explicitamente. Use esses métodos de pipeline em vez do argumento de construção `enable_safety_checker=` do pipeline de tarefa ou do argumento de chamada `enable_safety_check=`. Pipelines modulares também não retornam `Cosmos3OmniPipelineOutput`: use `output="videos"` para apenas os quadros, ou uma lista de saída e seu dicionário retornado, conforme mostrado acima, em vez de `result.video`, `result.sound` ou `result.action`.

> [!TIP]
> Em algumas topologias multi-GPU, o primeiro all-to-all do NCCL pode travar. Se uma execução de CP travar no início da primeira etapa de desruidamento, defina `NCCL_P2P_DISABLE=1` no ambiente antes de iniciar o `torchrun`.

CP e TP se combinam com todos os fluxos de trabalho acima (texto-para-vídeo, imagem-para-vídeo, texto-para-vídeo com som e geração condicionada por ação) e com os checkpoints `Nano` e `Super` — apenas as linhas de construção do pipeline e de configuração do paralelismo mudam.

## Modelos de metadados

`tokenize_prompt` adiciona frases curtas de metadados dentro da mensagem do usuário para que o LLM veja o condicionamento com o qual o modelo foi treinado. O prompt positivo recebe frases como *"O vídeo tem 7,9 segundos de duração e é de 24 FPS."* e *"Este vídeo tem resolução de 720x1280."*; o prompt negativo recebe o inverso (*"… não é …"*).

Ambos estão ativados por padrão. Desative qualquer par por meio de `__call__`:

```python
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` não tem efeito quando `num_frames == 1` (modo de imagem); nesse caso, apenas a frase de resolução é adicionada.

## Verificador de segurança

Cosmos3 integra o [`cosmos_guardrail`](https://pypi.org/project/cosmos-guardrail/) `CosmosSafetyChecker` e o executa **por padrão**. O guardrail de texto rejeita prompts inseguros antes da geração (`ValueError`); o guardrail de vídeo é executado nos quadros decodificados e, ou pixeliza os rostos detectados, ou rejeita a saída. A saída de áudio não possui guardrail.

Instale a dependência opcional para habilitar o verificador padrão:

```
pip install cosmos_guardrail
```

O verificador é obrigatório nos termos do Acordo de Licença de Modelo Aberto da NVIDIA. As duas flags abaixo existem para fluxos de trabalho de testes e desenvolvimento em que a salvaguarda seria redundante (por exemplo, a entrada já foi limpa ou você está exercitando intencionalmente o pipeline com entradas de borda).

**Desativar na construção** (nenhum verificador é instanciado, portanto, nenhum modelo de guardrail é baixado ou carregado na memória):

```python
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,
)
```

**Desativar para uma única chamada** (o verificador permanece carregado — útil para uma exceção pontual mantendo o padrão ativado para as chamadas subsequentes):

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

Para fornecer um verificador personalizado (por exemplo, uma subclasse no-op para testes rápidos), passe-o como `safety_checker=`:

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

## Cosmos3OmniPipeline[[diffusers.Cosmos3OmniPipeline]]

#### diffusers.Cosmos3OmniPipeline[[diffusers.Cosmos3OmniPipeline]]

```python
diffusers.Cosmos3OmniPipeline(transformer: Cosmos3OmniTransformer, text_tokenizer: AutoTokenizer, vae: AutoencoderKLWan, scheduler: UniPCMultistepScheduler, sound_tokenizer: diffusers.models.autoencoders.autoencoder_cosmos3_audio.Cosmos3AVAEAudioTokenizer | None = None, safety_checker: diffusers.pipelines.cosmos.pipeline_cosmos3_omni.CosmosSafetyChecker | None = None, enable_safety_checker: bool = True, default_use_system_prompt: bool = True, use_native_flow_schedule: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L413)

#### decode_sound[[diffusers.Cosmos3OmniPipeline.decode_sound]]

```python
decode_sound(latent: Tensor)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L517)

Decodifique um latente de som `[C, T]` para uma forma de onda `[audio_ch, N]`.

Adiciona/remove a dimensão de lote esperada pelo decodificador do tokenizador de som.

#### prepare_latents[[diffusers.Cosmos3OmniPipeline.prepare_latents]]

```python
prepare_latents(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, NoneType] = None, video: typing.Union[list[PIL.Image.Image], torch.Tensor, numpy.ndarray, NoneType] = None, condition_frame_indexes_vision: collections.abc.Iterable[int] = (0, 1), condition_video_keep: typing.Literal['first', 'last'] = 'first', num_frames: int | None = None, height: int | None = None, width: int | None = None, fps: float = 24.0, latents: typing.Optional[torch.Tensor] = None, sound_latents: typing.Optional[torch.Tensor] = None, action_latents: typing.Optional[torch.Tensor] = None, generator: typing.Optional[torch.Generator] = None, device: str = 'cuda', dtype: dtype = torch.bfloat16, enable_sound: bool = False, action: CosmosActionCondition | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L763)

**Retorna:**

Tensores ruidosos iniciais, além de máscaras de condição/metadata para as modalidades de visão, som e ações opcionais.

Construa a condição e o ruído inicial para uma única amostra.

#### tokenize_prompt[[diffusers.Cosmos3OmniPipeline.tokenize_prompt]]

```python
tokenize_prompt(prompt: str, negative_prompt: str | None = None, num_frames: int = 189, height: int = 720, width: int = 1280, fps: float = 24.0, use_system_prompt: bool | None = None, add_resolution_template: bool = True, add_duration_template: bool = True, action_mode: str | None = None, action_view_point: str | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L1132)

**Retorna:**

`(cond_input_ids, uncond_input_ids)` — listas de ids de tokens para esta amostra.

Aplique os modelos de aumento de prompt e tokenize os prompts cond/uncond por meio do modelo de chat configurado.

Este pipeline não executa um codificador de texto separado: o transformador conjunto Cosmos3 consome IDs de tokens brutos junto com tokens de visão (e, opcionalmente, de som).

Quando `negative_prompt` é `None`, uma string vazia é usada; a página de documentação do Cosmos3 documenta os prompts negativos recomendados para controle de qualidade a serem passados explicitamente para text2video / image2video. Os modelos de duração e resolução são anexados ao prompt, e os modelos inversos são anexados ao prompt negativo, quando habilitado.

Quando `action_mode` está definido, o prompt é convertido para a legenda JSON de ação estruturada na qual o modelo foi treinado (veja `_build_action_json_prompt`), usando `action_view_point` para o campo de enquadramento; os modelos de metadados planos são ignorados porque o JSON já contém duration/fps/resolution/aspect_ratio.

- todos
- __call__

## Cosmos3OmniModularPipeline

O Cosmos 3 também está disponível como um pipeline Modular Diffusers. O pipeline baseado em tarefas [Cosmos3OmniPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline) continua disponível; o pipeline modular coexiste com ele e cobre os mesmos modos (`text2image`, `text2video`, `image2video`, `video2video`, geração condicionada por ação e `transfer` (controle estrutural), com som opcional quando suportado pelo checkpoint).

```python
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]
```

Você também pode carregar por meio de [ModularPipeline](/docs/diffusers/v0.43.0/pt/api/modular_diffusers/pipeline#diffusers.ModularPipeline) e deixar que a configuração do repositório selecione a classe dos blocos:

```python
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"
)
```

Para inspecionar ou personalizar um workflow modular específico do Cosmos, use `available_workflows` + `get_workflow()`:

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

### Exemplos modulares para todos os fluxos de trabalho existentes

O pipeline modular suporta as mesmas assinaturas de chamada que o pipeline de tarefa. Os trechos abaixo espelham todos os exemplos de geração mostrados acima (`text2video`, `text2image`, `image2video`, `video2video`, `video2video_sound`, `text2video_sound` e `action_policy`). O Transfer (controle estrutural) possui entradas próprias e é mostrado separadamente em [Transfer modular](#modular-transfer-structural-control) abaixo.

```python
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ência modular (controle estrutural)

A transferência segue um **vídeo de controle pré-computado** (borda, desfoque, profundidade, segmentação ou um mapa de cenário de mundo) passado por meio de `control_videos=` como um mapeamento `{hint: video}`. É exclusivo para vídeo (sem `image` / `video` / `action` / `enable_sound`), o prompt é uma legenda JSON pré-ampleada (veja [Ampliação de prompt](#prompt-upsampling)) e clipes longos são gerados autoregressivamente em blocos de `num_video_frames_per_chunk` e costurados automaticamente. `guidance_scale` é o CFG de texto usual; `control_guidance` (`!= 1.0`) amplifica adicionalmente o sinal de controle. Valores iniciais recomendados por dica:

| Dica | `guidance_scale` | `control_guidance` | `flow_shift` | Geometria |
| --- | --- | --- | --- | --- |
| Borda / Desfoque / Profundidade | 3.0 | 1.5 | 10.0 | 121 quadros @ 30 FPS |
| Segmentação | 3.0 | 2.0 | 10.0 | 121 quadros @ 30 FPS |
| Cenário mundial (WSM) | 1.0 | 3.0 | 10.0 | 101 quadros @ 10 FPS |

O Diffusers não inclui os ativos de controle. Os prontos (um vídeo de controle + um `prompt.json` correspondente por dica, além de um `negative_prompt.json` compartilhado) estão no [Cosmos cookbook](https://github.com/NVIDIA/cosmos/tree/main/cookbooks/cosmos3/generator/transfer/assets). Para o exemplo de borda abaixo, baixe-os para uma pasta local `assets/`:

```bash
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
```

```python
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)
```

### Distilled texto-para-imagem (poucas etapas) e imagem-para-vídeo[[diffusers.Cosmos3OmniModularPipeline]]

Os checkpoints destilados de poucas etapas são servidos por [Cosmos3DistilledModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3DistilledModularPipeline) (blocos: `Cosmos3DistilledBlocks`); o [Cosmos3OmniModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniModularPipeline) base e o [Cosmos3OmniPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline) não os suportam. `num_inference_steps` é fixado no comprimento da configuração de pipeline `distilled_sigmas` (do `modular_model_index.json` do checkpoint) e `guidance_scale` é forçado para 1.0, pois o guidance está incorporado nos pesos — passar qualquer outro valor para qualquer um deles gera um erro, e `negative_prompt` é ignorado com um aviso.

Os checkpoints destilados em FP8 (`revision="fp8"`) não declaram uma política de precisão mista, portanto, cada etapa permanece no W8A8 nativo.

Os prompts seguem a mesma estrutura JSON descritiva dos modelos não destilados, portanto o texto curto deve ser ampliado primeiro — use `--mode text2image` (T2I) ou `--mode image2video` (I2V) conforme descrito em [Ampliação de prompt](#prompt-upsampling), e em seguida passe o JSON via `json.dumps(...)`.

```python
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)
```

#### diffusers.Cosmos3OmniModularPipeline[[diffusers.Cosmos3OmniModularPipeline]]

```python
diffusers.Cosmos3OmniModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/cosmos/modular_pipeline.py#L7)

Uma ModularPipeline para geração omni do Cosmos 3.

- todos
- __call__

## Cosmos3DistilledModularPipeline[[diffusers.Cosmos3DistilledModularPipeline]]

#### diffusers.Cosmos3DistilledModularPipeline[[diffusers.Cosmos3DistilledModularPipeline]]

```python
diffusers.Cosmos3DistilledModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/cosmos/modular_pipeline.py#L121)

Uma ModularPipeline para geração omni do Cosmos 3 destilado (poucas etapas).

Os checkpoints destilados incorporam o classifier-free guidance nos pesos e amostram em um agendamento fixo lido da configuração `distilled_sigmas` do pipeline (preenchida a partir de `modular_model_index.json`), de modo que `guidance_scale` e `num_inference_steps` são fixos e `negative_prompt` não é suportado.

- todos
- __call__

## CosmosActionCondition[[diffusers.CosmosActionCondition]]

#### diffusers.CosmosActionCondition[[diffusers.CosmosActionCondition]]

```python
diffusers.CosmosActionCondition(mode: typing.Literal['policy', 'forward_dynamics', 'inverse_dynamics'], chunk_size: int, domain_name: str, resolution_tier: int = 480, raw_actions: typing.Optional[torch.Tensor] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, NoneType] = None, video: typing.Union[list, numpy.ndarray, torch.Tensor, NoneType] = None, view_point: str = 'ego_view')
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L302)

**Parâmetros:**

mode (`str`) : A tarefa da ação. Uma de `"forward_dynamics"` (gerar o vídeo futuro a partir de um primeiro quadro e de uma sequência de `raw_actions`), `"inverse_dynamics"` (inferir as ações que conectam os quadros de condicionamento) ou `"policy"` (gerar conjuntamente o vídeo futuro e as ações a partir do primeiro quadro).

chunk_size (`int`) : Número de etapas de transição de ação no chunk. O vídeo de condicionamento correspondente abrange `chunk_size + 1` quadros.

domain_name (`str`) : Domínio de encarnação que seleciona os pesos de projeção de ação conscientes do domínio. Deve ser um dos domínios de encarnação registrados no Cosmos 3. Também fixa a largura de ação sem preenchimento usada para fatiar as ações previstas, resolvida internamente a partir deste nome (veja `_EMBODIMENT_TO_RAW_ACTION_DIM`).

resolution_tier (`int`, padrão `480`) : Nível de resolução *tier* para condicionamento de ação (um de `256`, `480`, `704`, `720`). O nível seleciona um canvas predefinido cuja proporção de aspecto é a mais próxima da entrada; a entrada é reduzida (nunca ampliada) e preenchida com padding para caber nesse canvas para o condicionamento. Isso não é o tamanho do quadro de saída, que acompanha o conteúdo da entrada. Alinhe o nível à resolução nativa da entrada: um nível mais baixo descarta detalhes, enquanto um nível mais alto não adiciona resolução (sem ampliação), desperdiça computação com padding e causa uma incompatibilidade entre treinamento e inferência que pode prejudicar a qualidade.

raw_actions (`torch.Tensor`, *opcional*) : Vetores de ação do domínio bruto com forma `[T, raw_action_dim]` que dirigem o `"forward_dynamics"`. Sequências mais curtas que `chunk_size` repetem a última ação; as mais longas são truncadas. Canais além do `action_dim` do modelo são rejeitados, e entradas mais estreitas são preenchidas com zeros até `action_dim`.

image (`PIL.Image.Image`, `np.ndarray` ou `torch.Tensor`, *opcional*) : Quadro de condicionamento para `"policy"` / `"forward_dynamics"`. Mutuamente exclusivo com `video`.

video (`list`, `np.ndarray` ou `torch.Tensor`, *opcional*) : Vídeo de condicionamento, obrigatório para `"inverse_dynamics"`. Para `"policy"` / `"forward_dynamics"`, apenas o primeiro quadro é utilizado. Exclusivo mutuamente com `image`.

view_point (`str`, padrão `"ego_view"`) : Rótulo de perspectiva da câmera usado para preencher o campo `cinematography.framing` da legenda da ação. Um dos valores `"ego_view"`, `"third_person_view"`, `"wrist_view"` ou `"concat_view"`. O modelo de ação foi treinado com legendas JSON estruturadas que carregam essa frase de ponto de vista; um rótulo não reconhecido remove o campo framing (com um aviso).

Agrupa todas as entradas necessárias para uma tarefa de geração condicionada a ações no Cosmos 3.

Passe isso para `Cosmos3OmniPipeline.__call__()` via o argumento `action` em vez dos argumentos de nível superior `image` / `height` / `width`, que são reservados para execuções t2v, i2v.

## Cosmos3OmniPipelineOutput[[diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput]]

#### diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput[[diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput]]

```python
diffusers.pipelines.cosmos.pipeline_cosmos3_omni.Cosmos3OmniPipelineOutput(video: Any, sound: typing.Optional[torch.Tensor] = None, action: list[torch.Tensor] | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/cosmos/pipeline_cosmos3_omni.py#L283)

**Parâmetros:**

video : O vídeo gerado. O tipo exato depende de `output_type` passado para o pipeline: uma lista de quadros PIL para `"pil"` (padrão), um `np.ndarray` de forma `[T, H, W, C]` para `"np"`, um `torch.Tensor` de forma `[T, C, H, W]` para `"pt"`, ou um tensor latente bruto quando `output_type="latent"`.

sound : Forma de onda de áudio decodificada com forma `[C, N]`. `None` quando `enable_sound=False`.

action : Tokens de ação previstos. `None` a menos que um modo de ação preveja ações.

Dataclass de saída para [Cosmos3OmniPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/cosmos3#diffusers.Cosmos3OmniPipeline).