# How to Configure Video Resolution, Frame Rate, and Aspect Ratio in Cosmos 3

> Learn to configure video resolution, frame rate, and aspect ratio in NVIDIA Cosmos 3. Control these settings using environment variables or CLI arguments for optimal video generation.

- Repository: [NVIDIA Corporation/cosmos](https://github.com/NVIDIA/cosmos)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Cosmos 3 generates video by producing a fixed number of latent frames that are rescaled to target dimensions, with the resolution, frame count, and frame rate controlled via environment variables like `I2V_NUM_FRAMES` and `I2V_RESOLUTION` or CLI arguments passed to `cosmos_framework.scripts.inference`.**

Cosmos 3 is the third-generation omni-model for video generation developed by NVIDIA and available in the `NVIDIA/cosmos` repository. The generation pipeline produces video clips by sampling a fixed number of frames at a specified rate, then rescaling the square latent representations to the target resolution. Understanding how to manipulate these parameters enables precise control over output duration, quality, and aspect ratio.

## Understanding Cosmos 3 Video Generation Parameters

The Cosmos 3 inference pipeline relies on three core parameters that determine the temporal and spatial characteristics of generated videos.

### Frame Count and Duration (`I2V_NUM_FRAMES`)

The `I2V_NUM_FRAMES` environment variable controls the total number of frames, including the conditioning image. According to `evaluation/cosmos3/generator/rbench/run_with_cosmos_framework.ipynb` (lines 23-24), the default targets **120 generated frames at 24 FPS** (totaling 121 frames including the conditioning image), producing approximately 5 seconds of video. The [`inference_benchmarks.md`](https://github.com/NVIDIA/cosmos/blob/main/inference_benchmarks.md) file (lines 39-40) also references a standard profile of 189 frames at 24 FPS for benchmark workloads. Calculate output duration using:

```

Duration (seconds) = I2V_NUM_FRAMES / FPS

```

### Spatial Resolution (`I2V_RESOLUTION`)

The `I2V_RESOLUTION` parameter accepts preset values that determine both the output dimensions and aspect ratio. Cosmos 3 supports three resolution tiers:

- **`256p`**: 320×192 pixels (4:3 aspect ratio)
- **`480p`**: 832×480 pixels (4:3 aspect ratio)
- **`720p`**: 1280×720 pixels (16:9 aspect ratio)

Cosmos 3 internally generates square latent images, then rescales them to the target resolution during post-processing. The default value is `720p` for high-definition output.

### Frame Rate Configuration (`COSMOS3_FPS`)

While the default frame rate is hard-coded to **24 FPS** in [`cosmos_framework/scripts/inference.py`](https://github.com/NVIDIA/cosmos/blob/main/cosmos_framework/scripts/inference.py), you can override this value using the `COSMOS3_FPS` environment variable or the `--fps` CLI flag. The frame rate determines playback smoothness and affects total duration when combined with the frame count.

## Configuration Methods

You can adjust these parameters using environment variables or by passing arguments directly to the inference module.

### Environment Variable Setup

The notebook `run_with_cosmos_framework.ipynb` reads configuration from the process environment. Set these variables before launching the script:

```bash
export I2V_NUM_FRAMES=161
export I2V_RESOLUTION=480p
export COSMOS3_FPS=30

```

This configuration generates approximately 6.7 seconds of video at 480p resolution with 30 FPS output.

### Direct CLI Arguments

The [`cosmos_framework/scripts/inference.py`](https://github.com/NVIDIA/cosmos/blob/main/cosmos_framework/scripts/inference.py) module accepts explicit command-line arguments that override environment defaults:

```bash
python -m cosmos_framework.scripts.inference \
    --prompt "a robot dancing on a stage" \
    --num-frames 241 \
    --resolution 256p \
    --fps 30

```

This approach bypasses the notebook wrapper and provides direct control over the generation pipeline.

## Aspect Ratio Handling in Cosmos 3

Cosmos 3 does not expose a dedicated "aspect ratio" flag. Instead, the aspect ratio is determined implicitly by the `I2V_RESOLUTION` selection. The 256p and 480p presets produce 4:3 aspect ratio outputs, while 720p produces 16:9 widescreen output. The model generates square latent tensors internally, then rescales them to the target width and height during the final rendering phase. This architecture means you cannot specify arbitrary aspect ratios independently of the resolution presets.

## Source Code Reference

The configuration logic is distributed across these files in the `NVIDIA/cosmos` repository:

- **`evaluation/cosmos3/generator/rbench/run_with_cosmos_framework.ipynb`** – Jupyter notebook that launches the generator; lines 23-24 contain the default generation target comments and variable definitions.
- **[`inference_benchmarks.md`](https://github.com/NVIDIA/cosmos/blob/main/inference_benchmarks.md)** – Benchmark documentation showing resolution tiers and generation profiles (lines 39-40).
- **[`cosmos_framework/scripts/inference.py`](https://github.com/NVIDIA/cosmos/blob/main/cosmos_framework/scripts/inference.py)** – CLI argument parsing for `--num-frames`, `--resolution`, and `--fps`.
- **[`cosmos_framework/config/defaults.py`](https://github.com/NVIDIA/cosmos/blob/main/cosmos_framework/config/defaults.py)** – Default values for `NUM_FRAMES`, `RESOLUTION`, and `FPS` constants.

## Verification Script

Verify your active configuration before running inference:

```python
import os

print("Cosmos 3 Configuration")
print(f"  Frames:     {os.getenv('I2V_NUM_FRAMES', '121')}")
print(f"  Resolution: {os.getenv('I2V_RESOLUTION', '720p')}")
print(f"  FPS:        {os.getenv('COSMOS3_FPS', '24')}")

```

## Summary

- **Frame count** is controlled by `I2V_NUM_FRAMES` (default 121 including the conditioning image), which determines video duration when divided by the frame rate.
- **Resolution** is set via `I2V_RESOLUTION` with three preset tiers (256p, 480p, 720p) that implicitly define the aspect ratio.
- **Frame rate** defaults to 24 FPS but can be overridden via the `COSMOS3_FPS` environment variable or the `--fps` CLI argument in `cosmos_framework.scripts.inference`.
- **Configuration** can be applied through environment variables consumed by the notebook wrapper or directly via CLI arguments.
- **Aspect ratio** is determined by the resolution preset, as the model generates square latents that are rescaled to the target dimensions.

## Frequently Asked Questions

### What is the default video length generated by Cosmos 3?

The default configuration generates approximately 5 seconds of video. This is achieved by generating 120 frames (plus one conditioning image, totaling 121 frames as specified by `I2V_NUM_FRAMES`) at 24 FPS. You can calculate the duration by dividing your frame count by the frame rate.

### How do I change the aspect ratio in Cosmos 3?

Cosmos 3 does not support arbitrary aspect ratios. You must select the resolution preset that matches your desired aspect ratio: use `256p` or `480p` for 4:3 output, or `720p` for 16:9 widescreen. The model internally generates square latent representations and rescales them to these specific dimensions during post-processing.

### Can I set a custom frame rate other than 24 FPS?

Yes. While 24 FPS is the hard-coded default in [`cosmos_framework/scripts/inference.py`](https://github.com/NVIDIA/cosmos/blob/main/cosmos_framework/scripts/inference.py), you can override this by setting the `COSMOS3_FPS` environment variable or passing the `--fps` argument to the inference script. Note that the frame rate affects both the smoothness of playback and the total duration of the generated clip.

### Where are the default configuration values defined in the codebase?

Default values for video generation parameters are defined in [`cosmos_framework/config/defaults.py`](https://github.com/NVIDIA/cosmos/blob/main/cosmos_framework/config/defaults.py) within the `cosmos-framework` submodule. The notebook at `evaluation/cosmos3/generator/rbench/run_with_cosmos_framework.ipynb` (lines 23-24) documents the standard generation profile, while [`inference_benchmarks.md`](https://github.com/NVIDIA/cosmos/blob/main/inference_benchmarks.md) specifies the supported resolution tiers.