How to Use the Transcribe Command with Groq versus OpenAI in Agent-Reach

Agent-Reach's transcribe command supports both Groq and OpenAI as Whisper providers, with automatic fallback from Groq to OpenAI when using --provider auto (the default).

The transcribe command in the Panniantong/Agent-Reach repository provides a unified interface for converting YouTube videos or local audio files into text using OpenAI-compatible Whisper APIs. You can explicitly choose between Groq and OpenAI as the backend provider, or let the tool automatically handle failover between them. This article explains how to configure, select, and troubleshoot both providers based on the actual implementation in the source code.

Provider Configuration and Authentication

Before invoking the transcribe command, you must store the appropriate API keys using the built-in configuration system. The keys are persisted to ~/.agent-reach/config.yaml and read at runtime via Config().get() in agent_reach/config.py.

Configuring API Keys

Use the configure command to store your credentials:

# Required for Groq provider or auto fallback

agent-reach configure groq-key YOUR_GROQ_API_KEY

# Required for OpenAI provider or auto fallback

agent-reach configure openai-key YOUR_OPENAI_API_KEY

If you attempt to use a provider without configuring its key, the command aborts early with a NoProviderConfigured error, as validated in tests/test_transcribe.py (lines 22-26).

Selecting Between Groq and OpenAI

The provider selection logic resides in agent_reach/transcribe.py and supports three distinct modes of operation.

Explicit Provider Selection

Force a specific backend by passing the --provider flag:

# Use Groq's whisper-large-v3 model

agent-reach transcribe https://youtu.be/abc123 --provider groq

# Use OpenAI's whisper-1 model

agent-reach transcribe /path/to/audio.m4a --provider openai

When explicitly selected, the command attempts only that provider and fails if the corresponding API key is missing or the request errors out.

Automatic Fallback (Default)

The default mode (--provider auto) tries Groq first, then falls back to OpenAI if the initial request fails:

# Tries Groq first; on HTTP error (e.g., 429), falls back to OpenAI

agent-reach transcribe https://youtu.be/abc123

This behavior is implemented in _transcribe_with_fallback() (lines 49-61 of agent_reach/transcribe.py), which walks the provider list returned by _provider_order() until one succeeds.

Configuration-Driven Validation

Even in automatic mode, a provider is skipped if its API key is absent from the config file. The _provider_order() function (lines 99-105) returns ["groq", "openai"] for auto mode, but _transcribe_with_fallback() checks key existence before attempting each endpoint.

How Provider Selection Works Internally

The routing logic spans three core files:

1. agent_reach/cli.py – Parses the --provider argument in _cmd_transcribe() (lines 1113-1122) and forwards it to the transcription engine.
2. agent_reach/transcribe.py – Contains the provider definitions, fallback orchestration, and HTTP posting logic.
3. agent_reach/config.py – Provides the Config().get() interface for retrieving groq_api_key and openai_api_key.

The provider table is defined as follows:

# agent_reach/transcribe.py (lines 30-41)

PROVIDERS = {
    "groq": {
        "endpoint": "https://api.groq.com/openai/v1/audio/transcriptions",
        "model": "whisper-large-v3",
        "key_field": "groq_api_key",
    },
    "openai": {
        "endpoint": "https://api.openai.com/v1/audio/transcriptions",
        "model": "whisper-1",
        "key_field": "openai_api_key",
    },
}

The fallback sequence is determined by _provider_order():

# agent_reach/transcribe.py (lines 99-105)

def _provider_order(provider: str) -> List[str]:
    if provider == "auto":
        return ["groq", "openai"]
    if provider in PROVIDERS:
        return [provider]
    raise TranscribeError(...)

And executed via _transcribe_with_fallback():

# agent_reach/transcribe.py (lines 49-61)

def _transcribe_with_fallback(chunk, order, config):
    for p in order:
        if not _provider_key(p, config):
            continue        # skip unconfigured providers

        try:
            return transcribe_chunk(chunk, p, config=config)
        except TranscribeError as e:
            last_err = e
    raise TranscribeError(...)

Usage Examples

Goal	Command	Behavior
Transcribe YouTube with Groq	agent-reach transcribe https://youtu.be/abc123 --provider groq	Downloads audio via yt-dlp, compresses if needed, posts to https://api.groq.com/openai/v1/audio/transcriptions
Transcribe local file with OpenAI	agent-reach transcribe /path/to/audio.m4a --provider openai	Compresses audio if required, posts to https://api.openai.com/v1/audio/transcriptions
Auto fallback	agent-reach transcribe audio.mp3	Attempts Groq first; on failure, automatically retries with OpenAI
Save output	agent-reach transcribe audio.mp3 -o transcript.txt	Writes transcription to transcript.txt and prints confirmation

Summary

• Configure keys first using agent-reach configure for groq_api_key and/or openai_api_key before running transcription jobs.
• Choose explicit providers with --provider groq or --provider openai, or rely on --provider auto (default) to try Groq then OpenAI.
• Understand the internals: agent_reach/transcribe.py defines the PROVIDERS table and _provider_order() logic, while agent_reach/cli.py handles argument parsing in _cmd_transcribe().
• Groq uses whisper-large-v3 and OpenAI uses whisper-1 according to the endpoint configurations in the source code.

Frequently Asked Questions

What happens if I don't configure an API key for my chosen provider?

The command raises a NoProviderConfigured error and exits immediately. As implemented in agent_reach/transcribe.py, the _transcribe_with_fallback() function checks for key existence via _provider_key() before attempting any HTTP request, and the CLI catches this in _cmd_transcribe() to display a user-friendly error message.

Can I use both providers interchangeably without changing my config?

Yes. By storing both groq_api_key and openai_api_key in ~/.agent-reach/config.yaml, you can switch between them using the --provider flag on a per-command basis, or use --provider auto to let the system handle failover automatically if one service is rate-limited.

Why does automatic mode try Groq before OpenAI?

The _provider_order() function in agent_reach/transcribe.py explicitly returns ["groq", "openai"] when the provider argument is set to auto. This ordering prioritizes Groq's typically faster inference and lower costs, falling back to OpenAI only if Groq returns an HTTP error or is unconfigured.

How do I save the transcription output to a file instead of stdout?

Use the -o or --output flag followed by your desired filename: agent-reach transcribe audio.mp3 -o transcript.txt. The CLI writes the text to the specified path and prints a success message upon completion, handling both YouTube URLs and local file paths identically.

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