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

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

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.

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 to prevent API quota exhaustion. You can instantiate this helper and pass it to the video generator to enforce throttling.

from utils.rate_limiter import RateLimiter

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

Pipeline Configuration

Edit 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.

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.

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

Alternatively, use 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 handles the API communication, retry logic for 429 rate-limit errors, and MP4 file downloading.

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.

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 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 to respect API quotas.
• Execute generation via CLI scripts (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, 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 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.

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