# How the Whisper API Fallback Works in Claude Video: Groq vs OpenAI

> Discover how the Whisper API fallback works in Claude Video. Learn how Groq is prioritized over OpenAI and how to select your backend.

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

---

**The Whisper API fallback mechanism in `bradautomates/claude-video` prioritizes Groq over OpenAI by checking for `GROQ_API_KEY` first in environment variables and `.env` files, only falling back to `OPENAI_API_KEY` if Groq is unavailable, while allowing explicit backend selection via the `--backend` CLI flag.**

The `bradautomates/claude-video` repository implements an intelligent **Whisper API fallback** system that automatically selects between Groq and OpenAI backends for video transcription. This prioritization logic ensures optimal performance by defaulting to Groq whenever its API key is detected, while maintaining OpenAI as a reliable secondary option. Understanding this selection mechanism is crucial for configuring your transcription pipeline correctly.

## The Fallback Logic in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)

The core of the Whisper API fallback 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). When `transcribe_video` is called without explicit backend parameters (lines 24-31), it invokes `load_api_key` (lines 64-71) to determine which provider to use.

### The Priority Order: Groq First, OpenAI Second

The function defines an ordered list of candidate backends at lines 93-99:

```python
candidates = [
    ("GROQ_API_KEY", "groq"),
    ("OPENAI_API_KEY", "openai")
]

```

This hardcoded sequence ensures that **Groq takes precedence** over OpenAI. The function iterates through this list, checking for the presence of each API key in the environment or designated `.env` files.

### Environment Variable Discovery Process

The `load_api_key` function searches for API keys in two distinct locations:

1. **Environment variables** via `os.environ`
2. **Configuration files**: `~/.config/watch/.env` or a local `.env` file in the project root

The first valid key discovered determines the backend. If `GROQ_API_KEY` exists anywhere in these locations, Groq is selected immediately. Only if this key is absent does the function proceed to check for `OPENAI_API_KEY`.

### Complete Fallback Chain

The selection flow follows this strict sequence:

1. Check for explicit `backend` parameter (bypasses the entire fallback)
2. Search for `GROQ_API_KEY` → Use Groq if found
3. Search for `OPENAI_API_KEY` → Use OpenAI if found
4. Return `(None, None)` if neither exists → Triggers a setup error in `transcribe_video`

## Overriding the Whisper API Fallback Behavior

Users can bypass the automatic selection logic through two explicit methods.

### Command Line Interface Override

When using the CLI, pass the `--backend` flag to force a specific provider:

```bash
python -m skills.watch.scripts.whisper video.mp4 audio.mp3 --backend openai

```

This flag causes `transcribe_video` to skip the `load_api_key` call entirely, ignoring any configured environment variables.

### Programmatic Override

When calling the function directly in Python, specify the backend parameter:

```python
from skills.watch.scripts import whisper
from pathlib import Path

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3"),
    backend="openai"  # Explicitly bypasses fallback logic

)
print(backend_used)  # → "openai"

```

## Practical Implementation Examples

### Automatic Selection with Groq Priority

When `GROQ_API_KEY` is present in your environment, the system automatically selects Groq without requiring explicit configuration:

```python

# Environment: GROQ_API_KEY=abc123

from skills.watch.scripts import whisper
from pathlib import Path

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3")
)
print(f"Used backend: {backend_used}")   # → "groq"

```

### Automatic Fallback to OpenAI

If only `OPENAI_API_KEY` is configured, the Whisper API fallback mechanism defaults to OpenAI:

```python

# Environment: OPENAI_API_KEY=def456 (no GROQ_API_KEY)

from skills.watch.scripts import whisper
from pathlib import Path

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3")
)
print(f"Used backend: {backend_used}")   # → "openai"

```

## Summary

- The **Whisper API fallback** in `bradautomates/claude-video` prioritizes Groq over OpenAI through an ordered key discovery process in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py).
- The `load_api_key` function checks for `GROQ_API_KEY` before `OPENAI_API_KEY`, ensuring Groq is selected whenever available.
- API keys are sourced from environment variables or `.env` files located at `~/.config/watch/.env` or the project root.
- Users can override the automatic selection by passing the `--backend` CLI flag or the `backend` parameter to `transcribe_video`.
- If neither API key is found, the function returns `(None, None)` and `transcribe_video` aborts with a configuration error.

## Frequently Asked Questions

### What happens if both Groq and OpenAI API keys are present?

Groq is selected automatically. The `load_api_key` function iterates through an ordered list where `("GROQ_API_KEY", "groq")` appears first, meaning Groq takes precedence whenever its key is detected, regardless of whether an OpenAI key also exists in the environment.

### Where does the script look for API keys?

The script searches environment variables first, then falls back to `.env` files. Specifically, it checks `~/.config/watch/.env` and the local project `.env` file. This search occurs within the `load_api_key` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py).

### Can I force OpenAI even if Groq is configured?

Yes. Pass the `--backend openai` flag when using the CLI, or set `backend="openai"` when calling `transcribe_video` programmatically. This explicitly bypasses the `load_api_key` function and forces the OpenAI backend regardless of which API keys are present.

### What error occurs if no API keys are found?

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is discovered, `load_api_key` returns `(None, None)`. This causes `transcribe_video` to abort execution and display a helpful setup message instructing you to configure one of the required API keys before proceeding.