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

> Learn to configure the Whisper API with Groq vs OpenAI backends in Claude-video. Automatically switch or explicitly select your preferred API for faster transcriptions.

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

---

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

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

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

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

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

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

```

Or for OpenAI:

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

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

```

Force Groq explicitly:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) completely backend-agnostic.

## Configuration Helpers

The repository includes utilities to streamline setup:

- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.