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

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, 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 implements a hardcoded priority list. It iterates through backend candidates in order, returning the first valid API key it discovers.

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

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.

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.

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

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, allowing shell scripts and automation tools to force a specific provider:

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

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:

# .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 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
• 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. The load_api_key function (lines 65-78) contains the priority iteration, while transcribe_video (starting line 24) orchestrates the detection and error handling.

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