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

Claude Video routes audio transcription to either Groq's Whisper-large-v3 or OpenAI's whisper-1 API by reading the GROQ_API_KEY or OPENAI_API_KEY environment variables, with automatic fallback to ~/.config/watch/.env.

The bradautomates/claude-video repository provides a flexible transcription system that supports multiple Whisper backends. Configuring API keys correctly ensures seamless switching between Groq and OpenAI providers without code modifications. This guide covers the specific source files and functions that handle credential management.

Backend Configuration Architecture

Claude Video centralizes API key management in skills/watch/scripts/whisper.py. The load_api_key() function (defined at line 65) implements a tiered lookup strategy that checks shell environment variables first, then falls back to the local configuration file.

The system supports two transcription backends:

• Groq – Uses the whisper-large-v3 model (default)
• OpenAI – Uses the whisper-1 model

The private _post_whisper() helper (line 237 in whisper.py) handles the actual HTTP POST request to the selected provider's endpoint, enforcing the standard 25 MiB upload size limit for both services.

Required Environment Variables

Each backend requires a specific environment variable. The validation logic in skills/watch/scripts/watch.py (lines 256-258) aborts execution with a descriptive error if the selected backend's key is missing.

Backend	Primary Variable	Fallback Location
Groq	GROQ_API_KEY	~/.config/watch/.env entry GROQ_API_KEY
OpenAI	OPENAI_API_KEY	~/.config/watch/.env entry OPENAI_API_KEY

Step-by-Step Configuration

Setting Up Groq (Default)

Groq serves as the preferred default backend, configured during initialization in skills/watch/scripts/setup.py. Export the key in your terminal:

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

Setting Up OpenAI

To use OpenAI's endpoint instead, set the corresponding variable:

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

Using a Persistent Environment File

For permanent configuration without exporting variables in each session, create the file ~/.config/watch/.env:

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

Both variables can coexist in this file; Claude Video selects the appropriate key based on the active backend.

Switching Between Backends

Use the --whisper command-line flag to override the default. The argument parsing logic in skills/watch/scripts/watch.py passes this selection to load_api_key(), which retrieves the matching credential.

Run transcription with Groq:

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

Run transcription with OpenAI:

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

Troubleshooting API Key Errors

If the chosen backend's key is unavailable, Claude Video exits immediately. The error handling at lines 256-258 of watch.py validates the return value of load_api_key() before invoking _post_whisper(). Ensure the variable is exported in the same shell session where you execute the watch command, or verify the entries in ~/.config/watch/.env.

Summary

• Claude Video selects Whisper backends via the load_api_key() function in skills/watch/scripts/whisper.py (line 65)
• Groq requires GROQ_API_KEY and OpenAI requires OPENAI_API_KEY, either as environment variables or in ~/.config/watch/.env
• The default backend is Groq, configured in skills/watch/scripts/setup.py
• Switch providers at runtime using the --whisper flag parsed by skills/watch/scripts/watch.py
• The _post_whisper() helper (line 237) manages uploads and retries for both services

Frequently Asked Questions

What is the default Whisper backend in Claude Video?

Groq is the default provider according to the setup logic in skills/watch/scripts/setup.py. If you omit the --whisper flag, the application automatically attempts to use Groq's Whisper-large-v3 model and expects the GROQ_API_KEY environment variable to be set.

Can I store both API keys simultaneously for easy switching?

Yes. You can define both GROQ_API_KEY and OPENAI_API_KEY in ~/.config/watch/.env or your shell profile. Claude Video reads only the key associated with the backend specified via the --whisper flag, ignoring the other variable until explicitly requested.

Why does Claude Video report a missing API key error when I have set environment variables?

The error handling logic in skills/watch/scripts/watch.py (lines 256-258) validates the specific key required for the selected backend. Ensure you are using the exact variable name required by your chosen provider (GROQ_API_KEY for Groq, OPENAI_API_KEY for OpenAI) and that the variable is exported in the same terminal session where you run the watch command.

How does Claude Video handle audio uploads to these Whisper services?

The _post_whisper() function at line 237 of skills/watch/scripts/whisper.py manages the HTTP POST request to the active provider's endpoint. This helper enforces the approximately 25 MiB upload limit shared by both Groq and OpenAI, and handles retry logic and error reporting internally without requiring manual intervention.

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