# Whisper API Fallback Logic Between Groq and OpenAI: How It Works in claude-video

> Discover the Whisper API fallback logic in claude-video prioritizing Groq over OpenAI. Learn how API keys are securely managed via environment variables or .env files for seamless operation.

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

---

**The Whisper API fallback logic in claude-video prioritizes Groq over OpenAI by checking for `GROQ_API_KEY` first before falling back to `OPENAI_API_KEY`, with both discovered from environment variables or `.env` files.**

The `claude-video` project implements an intelligent backend selection system for speech-to-text transcription. Located in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), this logic ensures seamless operation even when one provider's credentials are unavailable.

## How the Fallback Mechanism Works

The `transcribe_video` function orchestrates backend selection. When no explicit backend is provided, it delegates discovery to `load_api_key()` ([source](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py#L24-L31), [source](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py#L64-L71)).

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

The `load_api_key` function defines candidate backends as an ordered list:

```python

# From skills/watch/scripts/whisper.py, lines 93-99

candidates = [
    ("GROQ_API_KEY", "groq"),      # Checked first

    ("OPENAI_API_KEY", "openai"),  # Fallback

]

```

This ordering guarantees **Groq → OpenAI** precedence. The function iterates through candidates, probing:

- Environment variables (`os.environ`)
- `~/.config/watch/.env`
- Local `.env` file in the working directory

The first match wins. If `GROQ_API_KEY` exists anywhere in these locations, Groq is selected immediately. Only when Groq is absent does the system evaluate OpenAI credentials.

### When No Keys Are Found

If neither key is discovered, `load_api_key` returns `(None, None)`. The `transcribe_video` function then aborts with a setup message directing the user to configure their environment.

## Overriding Automatic Selection

Users can bypass the automatic Whisper API fallback logic entirely via two mechanisms:

### Command-Line Flag

```bash

# Force OpenAI despite having Groq key available

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

```

### Direct Function 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"  # Explicit choice ignores key discovery

)

```

## Practical Code Examples

### Automatic Groq Selection

```python

# Environment: GROQ_API_KEY=abc123 (OPENAI_API_KEY may or may not exist)

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

segments, backend_used = whisper.transcribe_video(
    video_path="interview.mp4",
    audio_out=Path("interview.mp3")
)
assert backend_used == "groq"  # Groq prioritized

```

### Automatic OpenAI Fallback

```python

# Environment: Only OPENAI_API_KEY=def456 set (no GROQ_API_KEY)

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

segments, backend_used = whisper.transcribe_video(
    video_path="lecture.mp4",
    audio_out=Path("lecture.mp3")
)
assert backend_used == "openai"  # Falls back when Groq unavailable

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) | Core transcription logic with `load_api_key()` and `transcribe_video()` |
| [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) | Configuration defaults and path constants |
| [`tests/test_whisper.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_whisper.py) | Test coverage for fallback behavior |
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) | `/watch` slash-command interface specification |

## Summary

- **Priority order is hardcoded**: Groq always precedes OpenAI in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)
- **Discovery sources**: Environment variables and two `.env` file locations
- **Override capability**: `--backend` CLI flag or `backend=` parameter bypasses automatic selection
- **Graceful failure**: Clear error message when no API keys are configured

## Frequently Asked Questions

### Why does claude-video prioritize Groq over OpenAI for Whisper transcription?

The candidate list in `load_api_key` places `("GROQ_API_KEY", "groq")` first at lines 93-99 of [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). This design choice likely reflects Groq's competitive pricing or latency advantages for inference workloads, though the repository does not explicitly document the rationale.

### How can I force OpenAI when both API keys are present?

Pass `--backend openai` on the command line or supply `backend="openai"` as a keyword argument to `transcribe_video`. Either approach skips the `load_api_key` discovery logic entirely and uses your specified provider.

### What `.env` file locations does the fallback check?

The `load_api_key` function examines `~/.config/watch/.env` first, then a local `.env` in the current working directory. It also checks `os.environ` for directly exported variables. The search stops at the first valid key found.