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

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 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, the load_api_key function iterates through a prioritized tuple of candidates:

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

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:

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

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:

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

# 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 – Core transcription logic containing load_api_key, transcribe_video, and the priority-based backend selection (lines 65-100)
• skills/watch/scripts/watch.py – High-level orchestration layer that invokes transcribe_video during video processing workflows
• 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 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.

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