# Whisper API Fallback Mechanism in Claude-Video: Prioritizing Groq Over OpenAI

> Discover the Whisper API fallback in claude-video. Learn how it prioritizes Groq over OpenAI, ensuring seamless operation by checking API keys.

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

---

**Claude-video automatically falls back from Groq to OpenAI Whisper by checking for `GROQ_API_KEY` first, then `OPENAI_API_KEY`, aborting with a clear error only if neither environment variable is configured.**

The bradautomates/claude-video repository implements a resilient transcription pipeline in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) that prioritizes Groq's Whisper API while maintaining OpenAI as a reliable backup. This priority-first **Whisper API fallback mechanism** ensures continuous video transcription capabilities without manual configuration changes when specific providers are unavailable.

## How the Priority-Based Fallback Works

The fallback logic centers on a sequential key detection strategy implemented in the `load_api_key` function. When `transcribe_video` is called without explicit backend credentials, the system automatically negotiates the best available provider.

### The load_api_key Function

At lines 65-78 and 98-100 in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), the `load_api_key` function iterates through a prioritized tuple of candidates:

```python

# Conceptual representation of the candidate priority

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

```

The function checks each candidate in order, stopping at the first key found in environment variables or a local `.env` file. If `GROQ_API_KEY` exists, the function immediately returns `"groq"` as the designated backend. Only when Groq's key is absent does the logic proceed to evaluate `OPENAI_API_KEY`.

### Automatic Backend Detection

The `transcribe_video` function (lines 24-28) orchestrates the fallback by calling `load_api_key()` when both `backend` and `api_key` parameters are omitted:

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

# Automatic selection: Groq preferred, OpenAI fallback

segments, backend = transcribe_video(
    video_path="lecture.mp4",
    audio_out=Path("temp_audio.mp3")
)

print(f"Active backend: {backend}")  # Outputs "groq" or "openai"

```

This automatic detection removes the need for manual backend specification while ensuring optimal cost and performance characteristics by preferring Groq.

### Error Handling When No Keys Exist

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is present in the environment, the script aborts with an informative error message (lines 29-35). This validation occurs before any API requests are attempted, preventing wasted compute cycles on authentication failures.

## Overriding the Fallback with Explicit Backends

While the default **Whisper API fallback mechanism** prioritizes Groq, the CLI and function parameters support explicit backend selection. The argument parser (around lines 76-78) accepts a `--backend` flag that bypasses automatic detection:

```bash

# Force OpenAI regardless of Groq key availability

python whisper.py --backend openai --video input.mp4

```

When explicitly specified, the system skips the `load_api_key` priority check and attempts to use the requested provider directly, failing only if the corresponding environment variable for that specific backend is missing.

## Implementation Examples

### Example 1: Automatic Fallback to OpenAI

When Groq is unavailable but OpenAI is configured, transcription proceeds seamlessly:

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

# Environment: GROQ_API_KEY unset, OPENAI_API_KEY set

segments, backend = transcribe_video(
    video_path="interview.mp4",
    audio_out=Path("audio.mp3")
)

assert backend == "openai"
print(segments[:3])  # First three transcript segments

```

### Example 2: Explicit Groq Request with OpenAI Backup

Even when specifying `"groq"` explicitly, the underlying error handling ensures the script fails gracefully if the key is missing, though the automatic fallback only triggers when no backend is specified:

```python

# Explicitly request Groq (requires GROQ_API_KEY to be set)

segments, backend = transcribe_video(
    video_path="podcast.mp4",
    audio_out=Path("audio.mp3"),
    backend="groq"
)

```

### Example 3: Force OpenAI Bypass

To bypass Groq even when both keys exist, provide explicit parameters:

```python

# Skip Groq priority, use OpenAI directly

segments, backend = transcribe_video(
    video_path="webinar.mp4",
    audio_out=Path("audio.mp3"),
    backend="openai"
)

```

## Key Source Files

The **Whisper API fallback mechanism** spans several files in the repository:

- **[`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)** – Core transcription logic containing `load_api_key`, `transcribe_video`, and the priority-based backend selection (lines 65-100)
- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)** – High-level orchestration layer that invokes `transcribe_video` during video processing workflows
- **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)** – Utility for generating `.env` files to store `GROQ_API_KEY` or `OPENAI_API_KEY` securely

## Summary

- **Priority order**: Groq (`GROQ_API_KEY`) is checked first, followed by OpenAI (`OPENAI_API_KEY`)
- **Automatic detection**: Calling `transcribe_video` without backend parameters triggers the fallback chain
- **Explicit override**: The `--backend` CLI argument or function parameter bypasses automatic selection
- **Fail-safe**: The script exits with a clear error if neither API key is configured, preventing silent failures
- **Source location**: All logic resides in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) within the bradautomates/claude-video repository

## Frequently Asked Questions

### What happens if both GROQ_API_KEY and OPENAI_API_KEY are set?

When both environment variables are present, the `load_api_key` function selects **Groq** because it appears first in the candidate list (lines 98-100). The OpenAI key remains available but unused unless explicitly requested via the `backend` parameter.

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

Yes. Pass `backend="openai"` to `transcribe_video` or use the `--backend openai` CLI flag. This bypasses the priority check and attempts to use the OpenAI API key directly, regardless of Groq's availability.

### Where does claude-video look for API keys?

The `load_api_key` function searches environment variables first, then checks a local `.env` file if available. This dual-source approach supports both containerized deployments and local development workflows without code changes.

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

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is found, `transcribe_video` raises a runtime error with a descriptive message prompting the user to configure one of the two keys (lines 29-35). This validation occurs during initialization, before any network requests are attempted.