How to Configure Whisper API Keys for Groq vs OpenAI in Claude Video

To configure Whisper API keys for Groq vs OpenAI in Claude Video, set the GROQ_API_KEY or OPENAI_API_KEY environment variables (or store them in ~/.config/watch/.env), then select your backend using the --whisper flag when running the watch command.

The bradautomates/claude-video repository provides a flexible audio transcription system that supports both Groq's Whisper-large-v3 model and OpenAI's Whisper-1 endpoint. This guide explains how to configure the necessary API keys and switch between these backends based on the implementation in skills/watch/scripts/whisper.py.

Understanding the Backend Architecture

Claude Video routes audio transcription requests through a unified interface defined in skills/watch/scripts/whisper.py. The system supports two distinct backends:

• Groq – Uses the whisper-large-v3 model via Groq's API (preferred default)
• OpenAI – Uses the whisper-1 model via OpenAI's API

The load_api_key() function (defined at line 65 of whisper.py) determines which credential to load based on your selected backend. Both backends enforce the same upload size limit of approximately 25 MiB and are invoked through the private _post_whisper() helper at line 237.

Setting Up API Keys

Environment Variable Method

Set the appropriate variable for your chosen backend before running Claude Video:

# For Groq

export GROQ_API_KEY="your-groq-key-here"

# For OpenAI  

export OPENAI_API_KEY="your-openai-key-here"

Configuration File Method

Alternatively, store keys in ~/.config/watch/.env:

GROQ_API_KEY=your-groq-key-here
OPENAI_API_KEY=your-openai-key-here

The load_api_key() function checks environment variables first, then falls back to this configuration file. If the required key for your selected backend is missing, the application aborts with a descriptive error (handled at lines 256-258 of watch.py).

Selecting Your Whisper Backend

Control which API receives your audio using the --whisper flag parsed by skills/watch/scripts/watch.py:

# Use Groq (default, preferred)

watch /path/to/video.mp4 --whisper groq

# Use OpenAI

watch /path/to/video.mp4 --whisper openai

The default backend selection logic resides in skills/watch/scripts/setup.py, which configures Groq as the preferred default when no flag is specified.

Implementation Details

The configuration system relies on three key components:

• load_api_key() (line 65 of whisper.py) – Retrieves the appropriate key based on the active backend
• _post_whisper() (line 237 of whisper.py) – Handles the actual HTTP request to the selected API
• Error handling (lines 256-258 of watch.py) – Validates key presence before processing and provides clear failure messages

Both backends share identical function signatures and response handling, ensuring seamless switching without code changes.

Summary

• Set GROQ_API_KEY for Groq's Whisper-large-v3 or OPENAI_API_KEY for OpenAI's Whisper-1, either as environment variables or in ~/.config/watch/.env
• Use the --whisper flag to select your backend: groq (default) or openai
• The load_api_key() function in whisper.py manages credential resolution with fallback to the config file
• Missing keys trigger descriptive errors at lines 256-258 of watch.py before any audio processing begins
• Both backends respect the same 25 MiB file size limit enforced by _post_whisper()

Frequently Asked Questions

How do I switch between Groq and OpenAI without editing configuration files?

Use the --whisper command line flag when invoking the watch command. Pass --whisper openai to route requests to OpenAI, or --whisper groq (or omit the flag) to use Groq. This override works immediately without modifying your .env file or environment variables.

Can I store both API keys simultaneously and switch between them?

Yes. You can define both GROQ_API_KEY and OPENAI_API_KEY in your ~/.config/watch/.env file or environment. Claude Video only loads the key required for the currently selected backend, so keeping both configured allows you to switch instantly using the --whisper flag without reconfiguration.

What happens if I forget to set the API key for my chosen backend?

If the required key is missing, the application aborts during initialization with a clear error message indicating which environment variable is required. This validation occurs in watch.py (lines 256-258) before any audio files are processed, preventing wasted time on failed uploads.

Is there a performance difference between Groq and OpenAI backends?

Both backends use the same file size limit (approximately 25 MiB) and follow identical processing logic in _post_whisper(). However, Groq is configured as the preferred default in setup.py due to typically faster inference speeds and competitive pricing for the Whisper-large-v3 model.

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