How to Configure Groq and OpenAI API Keys for Whisper Transcription in Claude-Video

Set your GROQ_API_KEY or OPENAI_API_KEY in ~/.config/watch/.env or as environment variables; the /watch skill automatically prefers Groq when both are present.

The bradautomates/claude-video repository provides a /watch skill that transcribes video audio using OpenAI's Whisper API when native captions are unavailable. The transcription backend supports both Groq and OpenAI providers, with the system intelligently selecting the preferred service based on available API keys. Configuring these keys requires editing a per-user configuration file or setting environment variables recognized by the whisper.py module.

Understanding the Backend Selection

The claude-video project implements a cascading priority system for Whisper API providers. According to the source code in skills/watch/scripts/whisper.py, the system checks for API keys in a specific order:

• Groq (preferred): Uses endpoint https://api.groq.com/openai/v1/audio/transcriptions with model whisper-large-v3
• OpenAI (fallback): Uses endpoint https://api.openai.com/v1/audio/transcriptions with model whisper-1

When both keys are present, Groq takes precedence due to its faster inference and cost efficiency. The selection logic resides in the load_api_key() function (lines 65-73 in whisper.py), which returns a tuple containing the backend name and the key value.

Configuration Methods

You can supply API keys through three distinct methods, checked in the following order:

Environment Variables

Export keys directly in your shell session for immediate use without persistent storage:

export GROQ_API_KEY="gsk_abc123..."
export OPENAI_API_KEY="sk-def456..."

Per-User Config File

The recommended approach uses a dedicated .env file located at ~/.config/watch/.env. This file is created automatically by the installer script and persists across system restarts. The config.py helper module reads this file to expose configuration values to the transcription scripts.

Installer Script Placeholders

Running setup.py scaffolds the configuration directory and populates the .env file with placeholder entries. The installer prints guided instructions when it detects missing keys and writes a SETUP_COMPLETE=true marker once configuration is valid.

Step-by-Step Setup Guide

Follow these steps to configure your Whisper transcription API keys:

1. Run the installer script to create the configuration directory and template file:

   python3 skills/watch/scripts/setup.py

   If required binaries are missing, the script suggests installation commands. The installer creates ~/.config/watch/.env with the following template structure:

   # /watch API configuration
   
   GROQ_API_KEY=
   OPENAI_API_KEY=

   The template generation code is located in skills/watch/scripts/setup.py (lines 38-54).

2. Edit the configuration file to add your actual API keys:

   nano ~/.config/watch/.env

   Replace the empty values with keys obtained from your providers:

   • Groq: Generate at https://console.groq.com/keys
   • OpenAI: Generate at https://platform.openai.com/api-keys

   Example configuration:

   GROQ_API_KEY=gsk_abc123xyz789...
   #OPENAI_API_KEY=sk_def456uvw012...  # Optional fallback
   

3. Verify the configuration using the check mode:

   python3 skills/watch/scripts/setup.py --check

   A return code of 0 indicates successful configuration. If the script reports "no Whisper API key", verify your .env file syntax or environment variable exports.

4. Execute transcription to confirm the backend selection:

   python3 skills/watch/scripts/whisper.py path/to/video.mp4

   The script internally calls load_api_key() to retrieve the backend and key, then routes the request to the appropriate API endpoint.

Code Implementation Details

The whisper.py module implements key management through the load_api_key() function:

def load_api_key(preferred: str | None = None) -> tuple[str, str] | tuple[None, None]:
    # Reads from environment variables first, then ~/.config/watch/.env

    candidates = (("GROQ_API_KEY", "groq"), ("OPENAI_API_KEY", "openai"))
    # Returns (backend_name, api_key) or (None, None) if not found

The transcription workflow in transcribe_video() automatically detects credentials when not explicitly passed:

def transcribe_video(
    video_path: str,
    audio_out: Path,
    backend: str | None = None,
    api_key: str | None = None,
) -> tuple[list[dict], str]:
    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
    # Proceeds with HTTP request to selected backend

Summary

• The /watch skill supports Groq and OpenAI Whisper backends, preferring Groq when both keys are available.
• Store API keys in ~/.config/watch/.env (created by setup.py) or export them as GROQ_API_KEY and OPENAI_API_KEY environment variables.
• Run python3 skills/watch/scripts/setup.py to scaffold configuration and setup.py --check to validate.
• The selection logic in skills/watch/scripts/whisper.py (lines 65-73) handles backend resolution automatically.

Frequently Asked Questions

What happens if I configure both Groq and OpenAI keys?

The system prioritizes Groq as the backend when both GROQ_API_KEY and OPENAI_API_KEY are present. According to the implementation in whisper.py, Groq appears first in the candidate tuple, making it the preferred choice for transcription tasks.

Where does the installer create the configuration file?

The setup.py installer creates the configuration file at ~/.config/watch/.env on Unix-like systems. This path provides per-user isolation and persists across terminal sessions, making it more reliable than environment variables for long-running Claude-Video operations.

Can I use OpenAI exclusively without Groq?

Yes. Simply provide only the OPENAI_API_KEY in your .env file or environment variables. The load_api_key() function falls back to OpenAI when Groq credentials are absent, ensuring the /watch skill functions with either provider independently.

How do I troubleshoot "no Whisper API key" errors?

First, verify that ~/.config/watch/.env exists and contains valid key assignments without quotation marks or trailing spaces. Second, ensure you have exported environment variables in your current shell session if not using the config file. Finally, run python3 skills/watch/scripts/setup.py --check to validate that the configuration loader can read your credentials.

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