# Whisper API Fallback Mechanism in Claude-Video: Groq Priority with OpenAI Backup

> Explore the Whisper API fallback in claude-video. Discover how Groq priority with OpenAI backup ensures seamless transcription for your video projects.

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

---

**Claude-Video implements a priority-first Whisper API fallback mechanism where Groq is preferred and OpenAI automatically serves as the backup when Groq credentials are unavailable.**

This open-source transcription tool handles API authentication through [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), implementing a seamless failover strategy that prioritizes speed and availability. Understanding this fallback behavior helps developers configure their environment correctly and predict which backend will handle their transcription requests.

## How the Fallback Mechanism Works

The `load_api_key` function in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) implements a hardcoded priority list. It iterates through backend candidates in order, returning the first valid API key it discovers.

```python

# Candidate list from whisper.py lines 98-100

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

```

The function stops at the first match found in environment variables or a local `.env` file. This design ensures zero-configuration operation for users who have either provider set up.

### Detection Flow in `transcribe_video`

When you call `transcribe_video()` without specifying `backend` or `api_key`, the function invokes `load_api_key()` at lines 24-28:

```python
def transcribe_video(video_path, audio_out, backend=None, api_key=None, model=None):
    # Auto-detect backend and API key if not provided

    if backend is None or api_key is None:
        detected_backend, detected_key = load_api_key()
        backend = backend or detected_backend
        api_key = api_key or detected_key

```

The returned `detected_backend` string—either `"groq"` or `"openai"`—determines which client initializes for the transcription job.

## Explicit Backend Control vs. Automatic Fallback

### Automatic Priority Selection (Recommended)

Leave parameters empty to let the system decide. This maximizes availability without manual intervention.

```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="sample.mp4",
    audio_out=Path("audio.mp3")
)

print(f"Used backend: {backend}")  # Output: "openai"

```

### Force Groq with Implicit OpenAI Fallback

Even when explicitly requesting Groq, the same `load_api_key` logic applies if the provided key is invalid or missing. However, the cleanest pattern is environment-based detection.

```python

# With GROQ_API_KEY defined in environment

segments, backend = transcribe_video(
    video_path="sample.mp4",
    audio_out=Path("audio.mp3"),
    backend="groq"  # Explicit request

)

```

### Bypass Priority: Force OpenAI Regardless

Override the Groq-first priority when you specifically need OpenAI's Whisper model—useful for testing consistency or accessing OpenAI-exclusive model variants.

```python
segments, backend = transcribe_video(
    video_path="sample.mp4",
    audio_out=Path("audio.mp3"),
    backend="openai"  # Skips Groq even if GROQ_API_KEY exists

)

```

## CLI Override for Backend Selection

The command-line interface exposes `--backend` at lines 76-78 in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py), allowing shell scripts and automation tools to force a specific provider:

```bash

# Use default priority (Groq first, OpenAI fallback)

python -m skills.watch.scripts.whisper sample.mp4

# Explicitly select provider

python -m skills.watch.scripts.whisper sample.mp4 --backend openai
python -m skills.watch.scripts.whisper sample.mp4 --backend groq

```

## Error Handling When No Keys Are Present

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` resolves to a valid credential, `transcribe_video` aborts with a clear instructional message. Lines 29-35 implement this guard clause:

```python
if api_key is None:
    raise ValueError(
        "No API key found. Please set either GROQ_API_KEY or "
        "OPENAI_API_KEY environment variable, or provide api_key directly."
    )

```

This fail-fast approach prevents confusing runtime errors from downstream HTTP failures.

## Environment Configuration Best Practices

Create a `.env` file in your project root for persistent configuration. The `load_api_key` function checks this file via standard dotenv loading:

```bash

# .env file - Groq priority (used first if present)

GROQ_API_KEY="gsk_..."

# Fallback option

OPENAI_API_KEY="sk-..."

```

According to the source code in `bradautomates/claude-video`, the [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) helper script can generate this configuration file programmatically for new installations.

## Summary

- **Groq is hardcoded as the priority backend** in the `candidates` tuple at lines 98-100 of [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py)
- **Automatic OpenAI fallback** occurs when `GROQ_API_KEY` is missing or empty
- **Manual override** via `backend=` parameter or `--backend` CLI flag bypasses priority logic
- **Clean error messages** guide users when neither API key is configured
- **Environment and .env file sources** are both supported for credential storage

## Frequently Asked Questions

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

Groq is selected because `load_api_key` iterates `("GROQ_API_KEY", "groq")` before `("OPENAI_API_KEY", "openai")`. To use OpenAI in this scenario, pass `backend="openai"` explicitly.

### Can I disable the fallback and require a specific provider?

Yes. Provide both `backend` and `api_key` parameters to `transcribe_video()`. This bypasses `load_api_key()` entirely, throwing an authentication error if your provided key fails rather than attempting the alternate provider.

### Does the fallback mechanism work for all Whisper models?

The fallback selects the API client, not the model. Each backend uses its own default model unless overridden via the `model=` parameter. Groq and OpenAI support different model variants, so verify your target model exists on your selected backend.

### Where is the fallback logic located in the codebase?

All fallback behavior is implemented in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). The `load_api_key` function (lines 65-78) contains the priority iteration, while `transcribe_video` (starting line 24) orchestrates the detection and error handling.