# How to Configure ViMax to Use the Google AI Studio API for Video Generation

> Learn how to configure ViMax for Google AI Studio video generation. Install the Google GenAI package, set your API key, and update the config to use the VideoGeneratorVeoGoogleAPI class.

- Repository: [✨Data Intelligence Lab@HKU✨/ViMax](https://github.com/HKUDS/ViMax)
- Tags: how-to-guide
- Published: 2026-05-20

---

**Configure ViMax for Google AI Studio video generation by installing the `google-genai` package, setting your `GOOGLE_API_KEY` environment variable, and updating [`configs/script2video.yaml`](https://github.com/HKUDS/ViMax/blob/main/configs/script2video.yaml) to use the `VideoGeneratorVeoGoogleAPI` class.**

ViMax is an open-source video generation framework that supports multiple backend APIs. To leverage Google's AI Studio (Gemini) video generation capabilities, you must configure the `VideoGeneratorVeoGoogleAPI` class found in [`tools/video_generator_veo_google_api.py`](https://github.com/HKUDS/ViMax/blob/main/tools/video_generator_veo_google_api.py) with proper authentication and model settings.

## Installation Prerequisites

Before configuring the Google AI Studio integration, install the required Python client library. The `VideoGeneratorVeoGoogleAPI` class depends on the official Google GenAI SDK to communicate with the video generation endpoints.

```bash
pip install google-genai

```

## Configuration Steps

### Configure API Authentication

The `VideoGeneratorVeoGoogleAPI` class accepts a Google API key through two mechanisms. You can either export the `GOOGLE_API_KEY` environment variable or pass the key directly via the pipeline configuration.

```bash
export GOOGLE_API_KEY=your-google-api-key-here

```

When using the YAML configuration approach, the pipeline expands the `${GOOGLE_API_KEY}` placeholder using the environment variable. If you omit the key in the config, the class automatically reads from the `GOOGLE_API_KEY` environment variable.

### Select Generation Models

The implementation supports three distinct model configurations via initialization parameters:

- **`t2v_model`**: Text-to-video generation (default: `"veo-3.1-generate-preview"`)
- **`ff2v_model`**: First-frame-to-video generation (default: `"veo-3.1-generate-preview"`)
- **`flf2v_model`**: First-and-last-frame-to-video generation (default: `"veo-3.1-generate-preview"`)

These defaults point to the preview model that handles text-only, single-image, and two-image-based generation requests.

### Set Up Rate Limiting (Optional)

ViMax includes a generic `RateLimiter` utility in [`utils/rate_limiter.py`](https://github.com/HKUDS/ViMax/blob/main/utils/rate_limiter.py) to prevent API quota exhaustion. You can instantiate this helper and pass it to the video generator to enforce throttling.

```python
from utils.rate_limiter import RateLimiter

rate_limiter = RateLimiter(max_per_minute=2, max_per_day=50)

```

## Pipeline Configuration

Edit [`configs/script2video.yaml`](https://github.com/HKUDS/ViMax/blob/main/configs/script2video.yaml) to route video generation requests through the Google AI Studio API. The configuration block specifies the class path, initialization arguments, and optional rate limits.

```yaml
video_generator:
  class_path: tools.VideoGeneratorVeoGoogleAPI
  init_args:
    api_key: ${GOOGLE_API_KEY}   # Reads from env var if left empty

  max_requests_per_minute: 2
  max_requests_per_day: 50

```

The pipeline loader resolves the `${GOOGLE_API_KEY}` syntax automatically. If you hardcode the key directly in the YAML file, ensure you exclude the file from version control for security.

## Running Video Generation

### Command-Line Interface

Execute the standard ViMax CLI scripts after configuring the YAML file. The pipeline initializes `VideoGeneratorVeoGoogleAPI` and routes all video generation through Google's API.

```bash
python main_script2video.py \
    --config configs/script2video.yaml \
    --prompt "A futuristic city skyline at sunrise"

```

Alternatively, use [`main_idea2video.py`](https://github.com/HKUDS/ViMax/blob/main/main_idea2video.py) depending on your specific workflow.

### Programmatic Usage

Instantiate the generator directly in Python for custom workflows. The `generate_single_video` method in [`tools/video_generator_veo_google_api.py`](https://github.com/HKUDS/ViMax/blob/main/tools/video_generator_veo_google_api.py) handles the API communication, retry logic for 429 rate-limit errors, and MP4 file downloading.

```python
import os
import asyncio
from tools.video_generator_veo_google_api import VideoGeneratorVeoGoogleAPI
from interfaces.video_output import VideoOutput

async def generate():
    # Initialize with your API key

    generator = VideoGeneratorVeoGoogleAPI(
        api_key=os.getenv("GOOGLE_API_KEY"),
        t2v_model="veo-3.1-generate-preview",
        ff2v_model="veo-3.1-generate-preview",
        flf2v_model="veo-3.1-generate-preview",
    )
    
    # Generate video (empty list = text-to-video mode)

    video: VideoOutput = await generator.generate_single_video(
        prompt="A medieval dragon soaring over a valley",
        reference_image_paths=[],
        resolution="1080p",
        aspect_ratio="16:9",
        duration=8,
    )
    
    # Save the generated MP4 data

    with open("output.mp4", "wb") as f:
        f.write(video.data)

asyncio.run(generate())

```

The method automatically selects the appropriate model based on the number of reference images provided: zero images triggers text-to-video, one image triggers first-frame conditioning, and two images triggers first-and-last-frame conditioning.

## Advanced Configuration

### Custom Rate Limiters

For production deployments, pass a configured `RateLimiter` instance directly to the generator constructor. This approach provides more granular control than the YAML configuration alone.

```python
from utils.rate_limiter import RateLimiter
from tools.video_generator_veo_google_api import VideoGeneratorVeoGoogleAPI

rate_limiter = RateLimiter(max_per_minute=2, max_per_day=50)

generator = VideoGeneratorVeoGoogleAPI(
    api_key=os.getenv("GOOGLE_API_KEY"),
    rate_limiter=rate_limiter,
)

```

The generator checks the limiter before each call to `genai.Client.models.generate_videos`, implementing exponential back-off when encountering 429 responses.

## Summary

- Install the **Google GenAI SDK** (`pip install google-genai`) to enable API communication.
- Provide authentication via the **`GOOGLE_API_KEY`** environment variable or YAML configuration.
- Configure **`VideoGeneratorVeoGoogleAPI`** in [`configs/script2video.yaml`](https://github.com/HKUDS/ViMax/blob/main/configs/script2video.yaml) to route generation requests through Google's AI Studio.
- Support **three generation modes** (text-to-video, first-frame, first-and-last-frame) using the `"veo-3.1-generate-preview"` model by default.
- Implement **rate limiting** using the `RateLimiter` utility from [`utils/rate_limiter.py`](https://github.com/HKUDS/ViMax/blob/main/utils/rate_limiter.py) to respect API quotas.
- Execute generation via **CLI scripts** ([`main_script2video.py`](https://github.com/HKUDS/ViMax/blob/main/main_script2video.py)) or **direct Python instantiation** for custom pipelines.

## Frequently Asked Questions

### What Python package does ViMax require for Google AI Studio integration?

ViMax requires the **`google-genai`** package available on PyPI. This official Google SDK provides the `genai.Client` class that `VideoGeneratorVeoGoogleAPI` uses to call the video generation endpoints. Install it with `pip install google-genai` before running any Google-backed generation tasks.

### How does ViMax handle authentication with the Google AI Studio API?

The `VideoGeneratorVeoGoogleAPI` class accepts an `api_key` parameter during initialization. If omitted from the YAML configuration in [`configs/script2video.yaml`](https://github.com/HKUDS/ViMax/blob/main/configs/script2video.yaml), the class automatically searches for the `GOOGLE_API_KEY` environment variable. The recommended approach is exporting the key in your shell environment rather than hardcoding credentials in configuration files.

### Which video generation models does ViMax support through Google AI Studio?

ViMax defaults to **`"veo-3.1-generate-preview"`** for all three generation modes (text-to-video, first-frame-to-video, and first-and-last-frame-to-video). You can override these defaults by passing the `t2v_model`, `ff2v_model`, and `flf2v_model` parameters when instantiating `VideoGeneratorVeoGoogleAPI`, allowing you to target specific model versions as Google updates their API.

### How does ViMax manage rate limits from the Google API?

The implementation includes built-in retry logic with exponential back-off for HTTP 429 rate-limit errors. Additionally, you can configure a **`RateLimiter`** instance from [`utils/rate_limiter.py`](https://github.com/HKUDS/ViMax/blob/main/utils/rate_limiter.py) with custom `max_requests_per_minute` and `max_requests_per_day` values. When provided, the limiter checks quotas before each API call, preventing unnecessary request failures.