What Happens When Whisper API Keys Are Missing or Invalid in bradautomates/claude-video

When Whisper API keys are missing or invalid, the bradautomates/claude-video repository immediately terminates execution with a SystemExit error, displaying specific instructions for configuring valid GROQ_API_KEY or OPENAI_API_KEY credentials before any network request is attempted.

The bradautomates/claude-video repository provides a watch skill that relies on Whisper transcription backends (Groq or OpenAI) to process video content. Understanding how the system handles authentication failures is critical for troubleshooting deployment issues. This guide examines the exact error handling behavior implemented in skills/watch/scripts/whisper.py when API keys are absent or rejected.

How API Keys Are Discovered

The load_api_key() function in skills/watch/scripts/whisper.py handles credential discovery by scanning environment variables and local .env configuration files. When no valid key is found, the function returns (None, None) to indicate the absence of both a backend selection and API credentials.

The function searches for GROQ_API_KEY (preferred) or OPENAI_API_KEY in the environment, falling back to ~/.config/watch/.env for persistent configuration storage. This discovery mechanism is tested in tests/test_whisper.py, which validates behavior for both missing keys and API error responses.

Missing API Key Behavior

Before attempting any network operations, the transcribe_video() function validates the presence of API credentials. When load_api_key() returns falsy values for either backend or api_key, the application aborts immediately with a SystemExit exception.

The error message provides specific remediation steps:

$ watch video.mp4
[watch] extracting audio for Whisper (None)…
SystemExit: No Whisper API key available. Set GROQ_API_KEY (preferred) or OPENAI_API_KEY in the environment or in ~/.config/watch/.env. Run `python3 /path/to/skills/watch/scripts/setup.py` to configure.

This guard clause prevents unnecessary audio extraction and upload attempts when authentication is impossible.

Invalid API Key Handling

When a key is present but rejected by the remote API, the _post_whisper() function handles HTTP error responses. Any 4xx status code (excluding 429 rate-limit responses) triggers immediate termination with a SystemExit that includes the HTTP status and server-provided error details.

Invalid keys typically generate 401 Unauthorized responses:

export GROQ_API_KEY=invalid-key
$ watch video.mp4
[watch] extracting audio for Whisper (groq)…
[watch] audio: 340 kB — uploading to groq Whisper…
SystemExit: Whisper request failed: <urlopen error 401 Unauthorized> — {"error":{"message":"Invalid API key"}}

Notably, the retry logic implemented in the module only activates for network errors, timeouts, and 429 rate-limit responses. Invalid authentication credentials never trigger retry attempts, ensuring rapid failure when credentials are misconfigured. The MAX_429_RETRIES constant defined in skills/watch/scripts/config.py controls retry behavior for rate limits only.

Configuring Valid Credentials

To avoid authentication errors, users can configure credentials through the provided setup script or manual environment configuration. The skills/watch/scripts/setup.py utility interactively creates the ~/.config/watch/.env file with proper API key storage.

Valid configuration examples:

# Environment variable method

export GROQ_API_KEY=sk-real-groq-key

# Or use the setup script

python3 skills/watch/scripts/setup.py

# Or manually edit ~/.config/watch/.env

echo "GROQ_API_KEY=sk-real-groq-key" > ~/.config/watch/.env

When properly configured, the transcription workflow proceeds through audio extraction, upload, and segment processing without interruption:

export GROQ_API_KEY=sk-real-groq-key
$ watch video.mp4
[watch] extracting audio for Whisper (groq)…
[watch] audio: 340 kB — uploading to groq Whisper…
[watch] transcribed 12 segments via groq

Summary

• Missing keys: Detected by load_api_key() in skills/watch/scripts/whisper.py, causing immediate SystemExit with configuration instructions before any audio processing begins.
• Invalid keys: Result in HTTP 401/4xx errors during _post_whisper() execution, triggering immediate termination with detailed error messages from the API provider.
• No retry for auth failures: Unlike rate-limit (429) responses, invalid credentials bypass the retry logic and fail fast to prevent wasted resources.
• Configuration support: The skills/watch/scripts/setup.py script provides guided configuration for persistent credential storage in ~/.config/watch/.env.

Frequently Asked Questions

What error message appears when Whisper API keys are missing?

The application displays: "No Whisper API key available. Set GROQ_API_KEY (preferred) or OPENAI_API_KEY in the environment or in ~/.config/watch/.env. Run python3 <setup.py> to configure." This message appears via SystemExit in the transcribe_video() function before any network requests are attempted.

Does the application retry when an invalid API key is rejected?

No. The retry logic in skills/watch/scripts/whisper.py only handles network errors, timeouts, and 429 rate-limit responses. Invalid keys generating 401 or other 4xx errors trigger immediate termination without retry attempts, as implemented in the _post_whisper() error handling block.

How do I configure Whisper API keys for the watch skill?

You can export GROQ_API_KEY or OPENAI_API_KEY as environment variables, or run python3 skills/watch/scripts/setup.py to create a persistent configuration file at ~/.config/watch/.env. The load_api_key() function automatically detects credentials in these locations when the watch skill initializes.

What is the difference between missing and invalid key handling?

Missing keys are caught during the initial validation phase in transcribe_video(), preventing any audio extraction or network activity. Invalid keys pass initial validation but fail during the _post_whisper() HTTP request phase, returning specific API error details (such as "Invalid API key") with the HTTP status code included in the terminal output.

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