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

> Easily configure Groq and OpenAI API keys for Whisper transcription in Claude-Video. Follow simple steps to set your API keys in .env or as environment variables for seamless audio processing.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/config.py) helper module reads this file to expose configuration values to the transcription scripts.

### Installer Script Placeholders

Running [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/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:

   ```bash
   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:

   ```text
   # /watch API configuration

   GROQ_API_KEY=
   OPENAI_API_KEY=
   ```

   The template generation code is located in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) (lines 38-54).

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

   ```bash
   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:

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

   ```

3. **Verify the configuration** using the check mode:

   ```bash
   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:

   ```bash
   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`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) module implements key management through the `load_api_key()` function:

```python
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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.