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

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 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, 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:

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 module accepts explicit command-line arguments that override environment defaults:

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 – Benchmark documentation showing resolution tiers and generation profiles (lines 39-40).
• cosmos_framework/scripts/inference.py – CLI argument parsing for --num-frames, --resolution, and --fps.
• cosmos_framework/config/defaults.py – Default values for NUM_FRAMES, RESOLUTION, and FPS constants.

Verification Script

Verify your active configuration before running inference:

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, 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 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 specifies the supported resolution tiers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}