# How claude-video's Whisper Integration Switches Between Groq and OpenAI Backends

> Discover how claude-video's Whisper integration seamlessly switches between Groq and OpenAI backends using environment variables or CLI flags for unified transcription.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-25

---

**Claude-video uses a pure-stdlib Python script that automatically selects between Groq and OpenAI Whisper APIs based on environment variables or CLI flags, normalizing both responses into a unified transcription format.**

The `bradautomates/claude-video` repository provides a flexible Whisper integration that lets you choose between Groq and OpenAI transcription backends without modifying source code. This claude-video Whisper integration with Groq and OpenAI backends prioritizes Groq for cost-effectiveness while maintaining OpenAI as a seamless fallback. Understanding how the backend selection logic works in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) ensures you can optimize for latency, pricing, or availability.

## Backend Selection Hierarchy in `load_api_key`

The core logic resides in the `load_api_key` function within [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). This function implements a three-tier selection process:

1. **CLI Flag Override** – Passing `--backend groq` or `--backend openai` forces that specific provider regardless of environment variables.
2. **Automatic Detection** – Without a flag, the script checks for `GROQ_API_KEY` first; if absent, it falls back to `OPENAI_API_KEY`.
3. **Failure Mode** – If neither key is found, the script aborts with instructions to run the setup helper ([`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py)).

### Environment Variable Priority

Keys are sourced from three locations in order of precedence:

- Shell environment variables (`export GROQ_API_KEY=...` or `export OPENAI_API_KEY=...`)
- User-specific dotenv file at `~/.config/watch/.env`
- Project-local `.env` file in the working directory

## Endpoint and Model Configuration

The script hardcodes distinct endpoints and models for each provider in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py):

**Groq Configuration:**
- Endpoint: `https://api.groq.com/openai/v1/audio/transcriptions`
- Model: `whisper-large-v3`

**OpenAI Configuration:**
- Endpoint: `https://api.openai.com/v1/audio/transcriptions`
- Model: `whisper-1`

These constants feed into `_transcribe_file`, which constructs multipart uploads via `_build_multipart` and executes requests through `_post_whisper`.

## Unified Response Normalization

Regardless of which backend processes the audio, [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) normalizes the API response into a consistent segment format. Both Groq and OpenAI responses are transformed into dictionaries containing `start`, `end`, and `text` keys. This backend-agnostic approach means downstream consumers in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) receive identical data structures whether using Groq's `whisper-large-v3` or OpenAI's `whisper-1`.

## Configuration Examples

### Setting Up Groq as the Primary Backend

Create the configuration directory and store your Groq key:

```bash
mkdir -p ~/.config/watch
cat >> ~/.config/watch/.env <<EOF
GROQ_API_KEY=your-groq-secret-key
EOF
chmod 600 ~/.config/watch/.env

```

Run the transcription:

```bash
python -m skills.watch.scripts.whisper /path/to/video.mp4

# Output indicates: backend: groq

```

### Configuring OpenAI as Fallback

If no Groq key exists, the script automatically uses OpenAI:

```bash
cat >> ~/.config/watch/.env <<EOF
OPENAI_API_KEY=sk-your-openai-secret-key
EOF

```

### Forcing a Specific Backend via CLI

Override automatic detection with the `--backend` flag:

```bash

# Force OpenAI even if Groq key exists

python -m skills.watch.scripts.whisper /path/to/video.mp4 --backend openai

# Force Groq even if only OpenAI key is configured

python -m skills.watch.scripts.whisper /path/to/video.mp4 --backend groq

```

### Temporary Testing with Environment Variables

For one-off tests without persistent configuration:

```bash
GROQ_API_KEY=your-key python -m skills.watch.scripts.whisper video.mp4

```

## Integration with the Watch Skill

The [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) module exposes backend configuration to the broader skill suite through `get_config()`. This allows [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) and other entry points to respect the same dotenv files and backend preferences established in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py), ensuring consistent behavior across the claude-video codebase.

## Summary

- **Automatic fallback**: Groq is preferred; OpenAI serves as the automatic fallback when `GROQ_API_KEY` is absent.
- **CLI override**: Use `--backend groq|openai` to force a specific provider regardless of environment configuration.
- **Flexible configuration**: API keys can reside in environment variables, `~/.config/watch/.env`, or project-local `.env` files.
- **Normalized output**: Both backends return identical `{start, end, text}` segment formats via `_transcribe_file`.
- **Security**: Configuration files should use `chmod 600` permissions as shown in [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) helpers.

## Frequently Asked Questions

### Does claude-video require code changes to switch between Groq and OpenAI?

No. The `load_api_key` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) handles backend selection automatically based on available API keys or CLI arguments. You can switch providers by setting different environment variables or using the `--backend` flag without touching the Python source.

### Which Whisper model does claude-video use for each backend?

According to the source code in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py), Groq uses the `whisper-large-v3` model while OpenAI uses the standard `whisper-1` model. These are hardcoded constants passed to their respective endpoints (`https://api.groq.com/openai/v1/audio/transcriptions` and `https://api.openai.com/v1/audio/transcriptions`).

### How does claude-video handle authentication errors?

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is found in environment variables or dotenv files, the script aborts with a descriptive error message directing users to run [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py). This helper script creates the `~/.config/watch/.env` file with placeholder values for both providers.

### Can I use both Groq and OpenAI simultaneously in the same claude-video instance?

No. The architecture selects a single backend per invocation via `load_api_key`. While you could theoretically alternate calls by changing environment variables between executions, each individual transcription request targets only one provider as determined by the hierarchy: CLI flag > Groq key > OpenAI key.