# How to Configure the Groq API for Podcast Transcription in Agent-Reach

> Configure the Groq API for podcast transcription in Agent-Reach. Automatically use Groq's free whisper-large-v3 model for faster, more accurate transcriptions, with an OpenAI fallback.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Agent-Reach automatically routes podcast audio through Groq's free whisper-large-v3 model when you provide a Groq API key, falling back to OpenAI's whisper-1 only if Groq returns an error.**

Agent-Reach is an open-source podcast automation framework that prioritizes Groq's high-speed Whisper API for transcription tasks. To enable this capability, you must configure the `groq_api_key` in the project's YAML-based configuration system. This guide covers the complete setup process using the CLI, environment variables, or direct Python API calls, referencing the actual implementation in `Panniantong/Agent-Reach`.

## Storing the Groq API Key

The configuration management system in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles credential storage and validation. Agent-Reach stores the Groq API key in `~/.agent-reach/config.yaml` under the field name `groq_api_key`, while also checking for the `GROQ_API_KEY` environment variable as a fallback.

### Using the CLI Configuration Command

The fastest way to configure your Groq credentials is through the built-in CLI. The `configure` sub-command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 104-107) writes the key directly to your user configuration file:

```bash

# Store the key in ~/.agent-reach/config.yaml

agent-reach configure groq-key gsk_YourGroqKeyHere

```

After running this command, the `Config.is_configured("groq_whisper")` helper (lines 90-94 in [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py)) validates that the required key is present before allowing transcription operations.

### Environment Variable Alternative

Agent-Reach checks for the `GROQ_API_KEY` environment variable if the key is not found in the YAML file. Set it in your shell configuration:

```bash
export GROQ_API_KEY="gsk_YourGroqKeyHere"

```

### Programmatic Configuration

You can also set the key directly via Python. The `Config` class provides a `set()` method that persists values to the YAML file:

```python
from agent_reach.config import Config

cfg = Config()
cfg.set("groq_api_key", "gsk_YourGroqKeyHere")  # writes to ~/.agent-reach/config.yaml

```

## How the Transcription Pipeline Uses Groq

The transcription driver in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) implements a provider-agnostic architecture that prioritizes Groq while maintaining OpenAI as a backup.

### Provider Configuration and Endpoint Mapping

The `PROVIDERS` dictionary (lines 30-36) defines the Groq endpoint configuration:

- **Endpoint**: `https://api.groq.com/openai/v1/audio/transcriptions`
- **Model**: `whisper-large-v3`
- **Config field**: `groq_api_key`

This mapping tells the transcription engine where to route audio chunks and which credentials to use.

### Authentication and Key Retrieval

The `_provider_key()` function (lines 57-61) extracts the API key from your `Config` instance. When you initiate transcription, the system validates that at least one provider key is configured (lines 22-25) before processing audio.

### Automatic Fallback Logic

The `transcribe()` function (lines 107-118) builds a provider order list where `auto` resolves to `["groq", "openai"]`. The `_transcribe_with_fallback()` method (lines 49-61) attempts Groq first via `transcribe_chunk()` (lines 63-71), which POSTs the audio data to the Groq Whisper API. If Groq returns an error or the key is missing, the system automatically retries with OpenAI's `whisper-1` model.

## Transcribing Podcasts with Groq Whisper

Once configured, you can transcribe podcast episodes using either the CLI or Python API.

### Command-Line Usage

The default `auto` provider setting selects Groq first:

```bash

# Auto-selects Groq, falls back to OpenAI if needed

agent-reach transcribe https://example.com/podcast.mp3

```

To force Groq exclusively (which raises an error if the key is missing or Groq fails):

```bash
agent-reach transcribe https://example.com/podcast.mp3 --provider groq

```

### Python API Usage

For custom workflows, import the `transcribe` function directly:

```python
from agent_reach.transcribe import transcribe
from agent_reach.config import Config

cfg = Config()
text = transcribe(
    "https://example.com/podcast.mp3",
    provider="auto",  # default: Groq → OpenAI fallback

    config=cfg,
)
print(text)

```

## Integration with Podcast Channels

The Xiaoyuzhou podcast channel implementation in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) demonstrates how Agent-Reach declares Groq as a backend dependency using `backends = ["groq-whisper", "ffmpeg"]`. The CLI's `_install_xiaoyuzhou_deps()` function (lines 71-78 in [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)) prints a configuration reminder if the Groq key is missing when setting up this channel, directing users to run `agent-reach configure groq-key`.

## Summary

- **Configuration location**: Store your `groq_api_key` in `~/.agent-reach/config.yaml` using the CLI `configure` command or the `Config.set()` method.
- **Environment fallback**: Agent-Reach checks the `GROQ_API_KEY` environment variable if the config file entry is absent.
- **Provider priority**: The `transcribe()` function defaults to `auto` mode, which attempts Groq's `whisper-large-v3` first via the endpoint at `https://api.groq.com/openai/v1/audio/transcriptions`.
- **Automatic resilience**: The `_transcribe_with_fallback()` mechanism ensures OpenAI's `whisper-1` handles transcription only if Groq fails.
- **Validation**: The `Config.is_configured("groq_whisper")` helper verifies credentials before API calls to prevent runtime errors.

## Frequently Asked Questions

### What Groq model does Agent-Reach use for transcription?

Agent-Reach uses Groq's `whisper-large-v3` model, configured in the `PROVIDERS` mapping in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 30-36). This model is currently free on Groq's tier and offers significantly faster inference than standard OpenAI Whisper endpoints.

### What happens if my Groq API key is invalid or rate-limited?

The `_transcribe_with_fallback()` method (lines 49-61) catches Groq errors and automatically retries the transcription using OpenAI's `whisper-1` model, provided you have configured an OpenAI API key. If you force `--provider groq` via CLI, the process raises an error instead of falling back.

### Where does Agent-Reach store my Groq API key?

The key is stored in plain text in `~/.agent-reach/config.yaml` under the `groq_api_key` field. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages this file, reading from it on initialization and writing updates via the `set()` method.

### Can I use OpenAI Whisper instead of Groq?

Yes. While the default `auto` provider prioritizes Groq, you can bypass it entirely by specifying `--provider openai` in the CLI or `provider="openai"` in the Python API. However, Groq is preferred in the default configuration because it offers free access to the large-v3 model with lower latency.