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

> Learn to configure Whisper API keys for Groq and OpenAI in Claude Video. Use GROQ_API_KEY or OPENAI_API_KEY environment variables for seamless audio transcription. Read now!

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py). Export the key in your terminal:

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

```

### Setting Up OpenAI

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

```bash
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`:

```dotenv
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) passes this selection to `load_api_key()`, which retrieves the matching credential.

Run transcription with Groq:

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

```

Run transcription with OpenAI:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)
- Switch providers at runtime using the `--whisper` flag parsed by [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.