# How to Configure Whisper API Using Groq or OpenAI in Claude-Video

> Easily configure the Whisper API in Claude-Video. Set GROQ_API_KEY or OPENAI_API_KEY environment variables and leverage Groq for faster processing. Learn how now.

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

---

**Configure the Whisper API in Claude-Video by setting either `GROQ_API_KEY` or `OPENAI_API_KEY` as environment variables or in `~/.config/watch/.env`, with Groq automatically preferred when both keys are present.**

The Claude-Video repository's `/watch` skill transcribes video audio using OpenAI's Whisper model through either the Groq or OpenAI API endpoints. Configuring the Whisper API using Groq or OpenAI requires setting specific environment variables that the system automatically detects and prioritizes according to the logic in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py).

## Backend Selection Logic

The transcription backend is determined by the `load_api_key` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) (lines 65-112), which implements a cascading priority system to select between providers.

### How the API Key Loader Works

The `load_api_key()` function first checks for `GROQ_API_KEY` and `OPENAI_API_KEY` in the process environment, then falls back to `.env` files located at `~/.config/watch/.env` and the project root. It returns a tuple containing the backend name (`"groq"` or `"openai"`) and the corresponding API key.

When `transcribe_video()` is called without explicit `backend` or `api_key` parameters (lines 24-30), it automatically invokes `load_api_key()` to determine which provider to use.

### Priority Order and Fallback

Groq is the preferred provider. The system checks for `GROQ_API_KEY` first, and only falls back to `OPENAI_API_KEY` if the Groq key is absent. If neither key is found, the `/watch` skill operates in video-frame-only mode without transcription capabilities.

## Configuration Methods

You can configure the API credentials through three methods, listed in order of precedence.

### Environment Variables

Setting variables in your shell provides the highest priority configuration and overrides any `.env` file settings:

```bash
export GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# or

export OPENAI_API_KEY=sk-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

```

### The .env File Location

The persistent configuration lives in `~/.config/watch/.env`. This file is created automatically by the setup script with mode `0600` (read/write owner only) for security. The template includes commented placeholders for both providers as defined in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) (lines 38-55):

```text

# /watch API configuration

# ...

GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
#OPENAI_API_KEY=sk-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

```

### Using the Setup Script

Run the installer to scaffold the configuration directory and `.env` file:

```bash
python3 skills/watch/scripts/setup.py

```

The script checks for existing keys using the `_have_api_key()` helper (lines 16-22) and writes `SETUP_COMPLETE=true` once a valid key is detected. If the `.env` file is missing, the script creates one with the template above.

## Implementation Details

Understanding the internal mechanics ensures reliable configuration across different deployment scenarios.

### Automatic Backend Detection

The `_have_api_key()` function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) returns a tuple `(bool, str)` indicating whether a key exists and which backend it corresponds to. This detection drives both the setup wizard and runtime backend selection in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py).

### Security and Permissions

When the setup script creates `~/.config/watch/.env`, it explicitly sets file permissions to `0600` (owner read/write only). This prevents other users on the system from accessing your API credentials.

## Usage Examples

Practical implementations demonstrating the configuration in action.

### Command Line Setup

Initialize the configuration and run a transcription:

```bash

# Scaffold the config file

python3 skills/watch/scripts/setup.py

# Edit ~/.config/watch/.env to add your key

# Then run:

export GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
watch https://www.youtube.com/watch?v=dQw4w9WgXcQ

```

### Programmatic Python Usage

Import and use the transcription function directly from [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py):

```python
import os
from pathlib import Path
from skills.watch.scripts.whisper import transcribe_video

# Optional: set key programmatically

os.environ["GROQ_API_KEY"] = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

segments, backend = transcribe_video(
    video_path="example.mp4",
    audio_out=Path("example_audio.mp3")
)

print(f"Transcribed with {backend}:")
for seg in segments:
    print(f"{seg['start']:.2f}-{seg['end']:.2f}: {seg['text']}")

```

## Summary

- Configure the Whisper API by setting `GROQ_API_KEY` or `OPENAI_API_KEY` in `~/.config/watch/.env` or as environment variables
- Groq is automatically preferred over OpenAI when both keys are present according to the logic in `load_api_key()`
- Run [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) to generate the configuration template automatically with secure permissions
- The system falls back to video-frame-only mode if neither API key is configured
- File permissions are set to `0600` to protect API credentials from unauthorized access

## Frequently Asked Questions

### Which provider is preferred when configuring the Whisper API?

Groq is the preferred provider. The `load_api_key()` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) checks for `GROQ_API_KEY` before falling back to `OPENAI_API_KEY`. If both environment variables are present, Groq is selected automatically for the transcription session.

### Can I use both Groq and OpenAI simultaneously?

No, the system uses a single backend per transcription. The `_have_api_key()` helper in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) detects the first available key and commits to that provider for the session. You must choose one provider per environment configuration, though you can switch between them by changing which environment variable is set.

### What happens if no API key is configured?

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is found in the environment or `.env` files, the `/watch` skill continues to function but returns only video frames without audio transcription. The `transcribe_video()` function will skip the Whisper API call and return empty segments, while the backend detection returns `None`.

### Where is the configuration file stored?

The persistent configuration is stored in `~/.config/watch/.env`. This location is created by [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) with restricted permissions (mode `0600`) to ensure your API keys remain secure and readable only by the file owner.