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

Set the GROQ_API_KEY or OPENAI_API_KEY environment variable, or store the key in ~/.config/watch/.env—the transcription script automatically detects and uses the first available key, preferring Groq over OpenAI.

Claude Video relies on the Whisper transcription service to convert video audio into text using either Groq or OpenAI backends. According to the bradautomates/claude-video source code, the system searches for API credentials in a specific priority order defined in skills/watch/scripts/whisper.py. You can configure keys via environment variables or persistent dot-env files, with Groq serving as the preferred provider for faster, cheaper transcription.

Where Claude Video Looks for API Keys

The load_api_key() function in skills/watch/scripts/whisper.py (lines 65-100) implements a two-tier detection strategy:

Environment Variables

The script first checks your shell environment for either:

• GROQ_API_KEY — preferred provider
• OPENAI_API_KEY — fallback option

If either variable is set, the value is used immediately for transcription requests.

Dot-Env Configuration Files

If no environment variable is found, the script falls back to dot-env files in this order:

1. ~/.config/watch/.env — preferred persistent location
2. .env in the current working directory

The script parses these files and extracts the first available key, again preferring Groq over OpenAI.

Setting Up Your API Key

Choose one of the following methods to provide your credentials:

Option 1: Export in Your Shell (Temporary)

For single-session usage, export the variable directly:

# Groq (preferred, faster transcription)

export GROQ_API_KEY="gsk_XXXXXXXXXXXXXXXXXXXXXXXX"

# Or OpenAI (fallback)

export OPENAI_API_KEY="sk-YYYYYYYYYYYYYYYYYYYYYYYY"

Option 2: Create the Config File (Persistent)

Create the recommended config directory and edit the .env file:

mkdir -p ~/.config/watch
nano ~/.config/watch/.env

Add one of the following lines (uncomment the one you use):

GROQ_API_KEY=gsk_XXXXXXXXXXXXXXXXXXXXXXXX

# OPENAI_API_KEY=sk-YYYYYYYYYYYYYYYYYYYYYYYY

Save the file. Claude Video will read this automatically on subsequent runs.

Option 3: Run the Setup Script

The repository includes an interactive setup script at skills/watch/scripts/setup.py that scaffolds the configuration file:

python3 skills/watch/scripts/setup.py

This script creates ~/.config/watch/.env with placeholder entries for both providers (lines 38-55). After you manually edit the file to add your real key, the script writes SETUP_COMPLETE=true to prevent repeated setup prompts (lines 42-48).

How Key Detection Works

The load_api_key() function implements the following logic:

1. Check os.environ for GROQ_API_KEY — if found, return immediately
2. Check os.environ for OPENAI_API_KEY — if found, return immediately
3. Load ~/.config/watch/.env and check for both keys
4. Load ./.env (current directory) and check for both keys
5. If no key is found in any location, raise a SystemExit with a helpful error message (lines 29-34) directing you to run the setup script

When you trigger transcription via python3 skills/watch/scripts/whisper.py path/to/video.mp4, the script uses the detected key to call the appropriate backend API.

Summary

• Primary location: Set GROQ_API_KEY or OPENAI_API_KEY as environment variables for immediate effect
• Persistent storage: Place keys in ~/.config/watch/.env to avoid reconfiguration
• Priority order: Groq is preferred over OpenAI when both keys are present
• Setup helper: Run skills/watch/scripts/setup.py to scaffold the configuration file automatically
• Error handling: The script exits with clear instructions if no valid key is detected

Frequently Asked Questions

Does Claude Video support both Groq and OpenAI for Whisper transcription?

Yes. The whisper.py script supports both providers, with Groq serving as the default preferred option due to faster processing and lower costs. You only need to configure one key—either GROQ_API_KEY or OPENAI_API_KEY—and the script will automatically select the appropriate backend.

What happens if I don't configure an API key?

If load_api_key() cannot find credentials in environment variables or dot-env files, the script aborts with a SystemExit error (lines 29-34 in skills/watch/scripts/whisper.py). The error message includes instructions to run the setup script or manually configure the key in ~/.config/watch/.env.

Can I use a .env file in my project directory instead of ~/.config/watch/.env?

Yes, but the global config location takes precedence. The script checks ~/.config/watch/.env before looking for a local .env file in your current working directory. If you maintain project-specific keys, ensure the global file does not contain conflicting credentials.

Why does the setup script write SETUP_COMPLETE=true?

The SETUP_COMPLETE flag (written by skills/watch/scripts/setup.py at lines 42-48) acts as a sentinel to prevent the setup wizard from running repeatedly. Once this marker exists in your configuration, Claude Video assumes you have intentionally configured your API keys and will not prompt you again during transcription operations.

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