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

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 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 (lines 104-107) writes the key directly to your user configuration file:

# 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) 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:

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:

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

# 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):

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

Python API Usage

For custom workflows, import the transcribe function directly:

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 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) 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}