# claude-video API Keys and Configuration: Complete Guide to config.py Setup

> Discover how claude-video uses Groq and OpenAI Whisper APIs, managing API keys and configuration via config.py for secure and efficient video transcription.

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

---

**The claude-video project supports two Whisper transcription APIs—Groq and OpenAI—and manages configuration through a [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) file that parses a user-maintained `.env` file while never writing secrets to disk automatically.**

The `claude-video` repository provides a video analysis skill that transcribes audio content using external Whisper services. Understanding which API keys are supported and how [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) orchestrates settings is essential for secure deployment. This guide breaks down the authentication options and the internal configuration architecture based on the actual source implementation.

## Supported API Keys for Whisper Transcription

`claude-video` integrates with two transcription providers, with automatic failover between them.

### Groq Whisper (Preferred)

- **Environment variable:** `GROQ_API_KEY`
- **Characteristics:** Cheaper pricing and faster inference
- **Implementation:** Checked first in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) before falling back to OpenAI

### OpenAI Whisper (Fallback)

- **Environment variable:** `OPENAI_API_KEY`
- **Characteristics:** Used only when `GROQ_API_KEY` is absent
- **Implementation:** Secondary check in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) if Groq authentication unavailable

The routing logic resides in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). At runtime, the skill detects which key is present and routes the transcription request accordingly. No key is ever persisted to version control or generated automatically—all values must be supplied manually by the user.

## How config.py Manages Configuration

The [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) module centralizes non-secret configuration for the watch skill. Located at [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), it handles environment parsing, variable merging, and frame-extraction tuning.

### Configuration File Location

The `.env` file lives in a dedicated configuration directory:

```python
from pathlib import Path

CONFIG_DIR = Path.home() / ".config" / "watch"
CONFIG_FILE = CONFIG_DIR / ".env"

```

This keeps secrets outside the project directory and follows XDG Base Directory conventions.

### Parsing the .env File

The `read_env_file()` function in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) parses `.env` line-by-line with specific rules:

- Ignores blank lines and comment lines starting with `#`
- Strips inline comments appearing after unquoted values (e.g., `WATCH_DETAIL=balanced  # note`)

- Preserves `#` characters inside quoted strings or API keys

This parsing approach prevents accidental truncation of API keys containing hash characters.

### Merging Environment Variables

The `get_config()` function implements a two-layer configuration strategy:

1. Load and parse the `.env` file
2. Overlay any environment variables from the shell

Environment variables take precedence, enabling temporary overrides without editing files.

### WATCH_DETAIL and Frame Extraction

The only tunable runtime setting exposed through [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) is `WATCH_DETAIL`, which controls how aggressively the skill extracts frames from videos:

| Setting | Behavior | Frame cap |
|---------|----------|-----------|
| `efficient` | Minimal frames, fastest processing | 50 |
| `balanced` | Moderate frame sampling (default) | 100 |
| `token-burner` | Maximum frame extraction | No limit (None) |
| `transcript` | Audio-only mode, no visual frames | No limit (None) |

The `frame_cap(detail)` function converts these string values into numeric limits consumed by the frame extraction pipeline.

## Initial Setup with setup.py

When the watch skill is first installed, [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) scaffolds a template `.env` file:

```dotenv

# /watch API configuration

GROQ_API_KEY=
OPENAI_API_KEY=
WATCH_DETAIL=balanced

```

Users must manually populate `GROQ_API_KEY` or `OPENAI_API_KEY` (or both) before the `/watch` command will function. The setup script never injects actual key values—it only creates the structural template.

## Practical Configuration Examples

### Populating the .env File

```dotenv

# ~/.config/watch/.env

GROQ_API_KEY=groq-your-key-here
OPENAI_API_KEY=sk-openai-fallback-key
WATCH_DETAIL=efficient

```

### Using Shell Exports for Temporary Overrides

```bash
export GROQ_API_KEY=groq-live-key
export WATCH_DETAIL=token-burner
watch https://youtu.be/example-video

```

### Accessing Configuration Programmatically

```python
from skills.watch.scripts.config import get_config, frame_cap

cfg = get_config()

print(cfg["WATCH_DETAIL"])           # → 'balanced' or overridden value

print(cfg.get("GROQ_API_KEY"))       # → None (not stored in config dict)

cap = frame_cap(cfg["WATCH_DETAIL"])
print(cap)                           # → 100 for balanced, 50 for efficient

```

Note that `get_config()` returns the processed `WATCH_DETAIL` value and other non-sensitive options. API keys are read directly from the environment by [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) rather than passing through the configuration dictionary.

## Security Architecture

The `claude-video` configuration design follows security best practices:

- **No automatic secret generation**—users must explicitly provide keys
- **No secrets in repository**—`.env` resides in `~/.config/watch`, outside version control
- **Environment variable precedence**—allows ephemeral overrides without file modification
- **Clean parsing**—preserves special characters in API keys while stripping comments

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point validates key presence before invoking transcription, failing early with a clear error if neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is available.

## Summary

- **Two API keys supported:** `GROQ_API_KEY` (preferred, faster/cheaper) and `OPENAI_API_KEY` (fallback)
- **Configuration location:** `~/.config/watch/.env`, scaffolded by [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) with blank placeholders
- **config.py responsibilities:** Parse `.env`, merge with environment, expose `WATCH_DETAIL` setting, map detail levels to frame caps
- **Security model:** Secrets never written automatically; environment variables take precedence; keys read directly by [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) rather than centralized config dictionary

## Frequently Asked Questions

### What happens if I provide both GROQ_API_KEY and OPENAI_API_KEY?

[`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) prioritizes Groq when both keys are present. The Groq service is checked first due to its cost and speed advantages. OpenAI serves only as a fallback mechanism.

### Can I run claude-video without any API keys?

No. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point validates that at least one Whisper API key exists before proceeding. Without either `GROQ_API_KEY` or `OPENAI_API_KEY`, the skill exits with an authentication error.

### Does WATCH_DETAIL affect transcription quality or just visual frame extraction?

`WATCH_DETAIL` controls only **visual frame extraction** aggressiveness. It does not modify audio transcription quality, bitrate, or Whisper model selection. The `transcript` value disables frame extraction entirely for audio-only analysis.

### Why doesn't config.py return API keys in the configuration dictionary?

[`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) intentionally excludes secrets from `get_config()` return values. API keys are accessed directly from `os.environ` within [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py). This separation prevents accidental logging or serialization of credentials while keeping the configuration surface minimal and auditable.