How to Configure the Whisper API with Groq vs. OpenAI Backends in Claude-video

Claude-video automatically selects between Groq and OpenAI Whisper backends based on available API keys, with Groq preferred by default, and supports explicit backend selection via the --backend CLI flag.

Claude-video uses a pure-stdlib Python script to handle audio transcription without installing the heavy openai-whisper package. Understanding how to configure the Whisper API with Groq vs. OpenAI backends lets you optimize for cost, latency, and availability while maintaining identical output formatting. The implementation in skills/watch/scripts/whisper.py provides seamless switching through environment variables and CLI flags.

Backend Selection Logic

The load_api_key function in skills/watch/scripts/whisper.py implements a deterministic three-tier hierarchy for choosing transcription providers:

1. CLI override: If you pass --backend groq or --backend openai, the script exclusively validates that provider's key.
2. Groq priority: Without an explicit flag, the function first checks for the GROQ_API_KEY environment variable.
3. OpenAI fallback: If no Groq key exists, it falls back to OPENAI_API_KEY.

This automatic detection mechanism ensures that simply setting a Groq key defaults you to that provider, while OpenAI remains available as a reliable backup.

Key Resolution Order

When searching for API credentials, the script checks these locations in order:

• Environment variables (export GROQ_API_KEY=... or export OPENAI_API_KEY=...)
• User-specific dotenv file at ~/.config/watch/.env
• Project-local .env file in the current working directory

If neither key is found, the script aborts with a guided error message referencing setup.py to create the configuration file.

Configuring API Keys

Setting Up Groq (Preferred Backend)

Create the configuration directory and store your Groq API key to enable automatic priority selection:

mkdir -p ~/.config/watch

cat >> ~/.config/watch/.env <<EOF
GROQ_API_KEY=your-groq-secret-key
EOF

chmod 600 ~/.config/watch/.env

Now running the transcription script automatically uses Groq:

python -m skills.watch.scripts.whisper /path/to/video.mp4

The output includes backend: groq confirming the selection.

Setting Up OpenAI (Fallback)

If you prefer OpenAI or lack Groq access, configure the fallback key:

cat >> ~/.config/watch/.env <<EOF
OPENAI_API_KEY=sk-your-openai-secret-key
EOF

chmod 600 ~/.config/watch/.env

Without a Groq key present, the script automatically falls back to OpenAI:

python -m skills.watch.scripts.whisper /path/to/video.mp4

The output indicates backend: openai.

Temporary Environment Testing

For one-off transcriptions without persisting keys to disk:

GROQ_API_KEY=your-key python -m skills.watch.scripts.whisper video.mp4

Or for OpenAI:

OPENAI_API_KEY=sk-your-key python -m skills.watch.scripts.whisper video.mp4

Forcing a Specific Backend

Override automatic detection using the --backend flag. This is useful when both keys exist but you need a specific provider:

Force OpenAI even if Groq is configured:

python -m skills.watch.scripts.whisper /path/to/video.mp4 --backend openai

Force Groq explicitly:

python -m skills.watch.scripts.whisper /path/to/video.mp4 --backend groq

The load_api_key function validates that the requested backend's key exists before proceeding.

Endpoint and Model Mapping

The script defines provider-specific constants that map to different infrastructure while maintaining API compatibility:

Groq Configuration:

• Endpoint: https://api.groq.com/openai/v1/audio/transcriptions
• Model: whisper-large-v3

OpenAI Configuration:

• Endpoint: https://api.openai.com/v1/audio/transcriptions
• Model: whisper-1

In _transcribe_file, the script constructs a multipart request via _build_multipart and posts it using _post_whisper. Regardless of backend, responses are normalized into the same {start, end, text} segment format, making downstream processing in watch.py completely backend-agnostic.

Configuration Helpers

The repository includes utilities to streamline setup:

• skills/watch/scripts/config.py: Exposes get_config() to read dotenv files and share the selected backend across the skill suite
• skills/watch/scripts/setup.py: Interactive helper that creates the ~/.config/watch/.env file with placeholder keys

Summary

• Groq takes precedence: The script checks GROQ_API_KEY before falling back to OPENAI_API_KEY when no --backend flag is provided
• Three key sources: Environment variables, ~/.config/watch/.env, and project-local .env files are checked in that order
• CLI override: Use --backend groq or --backend openai to force a specific provider regardless of available keys
• Backend-agnostic output: The _transcribe_file function normalizes both Groq and OpenAI responses into identical segment formats
• Model differences: Groq uses whisper-large-v3 while OpenAI uses whisper-1, though this is abstracted from the end user

Frequently Asked Questions

How does Claude-video decide which Whisper backend to use?

According to the load_api_key implementation in skills/watch/scripts/whisper.py, the script first checks for the --backend CLI flag. If absent, it searches for GROQ_API_KEY in environment variables and dotenv files. Only if Groq is unavailable does it fall back to OPENAI_API_KEY. This priority ensures you can utilize Groq's infrastructure by default when credentials are present.

Can I store both Groq and OpenAI keys simultaneously?

Yes. You can populate both GROQ_API_KEY and OPENAI_API_KEY in your ~/.config/watch/.env file. By default, the script will use Groq. To temporarily use OpenAI while both keys exist, explicitly pass --backend openai when running whisper.py.

What Whisper models are used for each backend?

As defined in the source constants, the Groq backend sends requests to whisper-large-v3, while the OpenAI backend uses whisper-1. These mappings are hardcoded in skills/watch/scripts/whisper.py and automatically applied based on the selected backend, ensuring optimal model availability for each provider.

Where is the safest place to store API keys for Claude-video?

The recommended location is ~/.config/watch/.env with permissions set to 600 (read/write for owner only). This user-specific configuration persists across project directories while keeping credentials out of version control. Alternatively, use environment variables for temporary or CI/CD scenarios.

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