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

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

The core of the Whisper API fallback resides in the load_api_key function within 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:

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:

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:

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:

# 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:

# 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.
• 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}