API Key Management

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• commands/voice-config.md
• commands/speak.md
• commands/voices.md
• commands/create-voice.md
• commands/transcribe.md
• hooks/hooks.json

Introduction

API Key Management is a fundamental aspect of the voice-elevenlabs plugin. All features that interact with the ElevenLabs API, such as text-to-speech, voice creation, and transcription, require a valid API key for authentication. The key is managed as an environment variable, ELEVENLABS_API_KEY, which is used by the plugin's commands to make authorized requests to ElevenLabs services. Proper configuration of this key is the first and most critical setup step for using the plugin.

Sources: README.md:18-23, commands/speak.md:28-33, commands/voices.md:22-24

Configuration

The primary method for configuring the API key is by setting an environment variable in the user's shell configuration file. This ensures the key is available in the shell session where Claude Code and its plugins operate.

Sources: README.md:18-23

Setup Process

1. Obtain Key: The user must first get a free API key from the ElevenLabs website.
2. Set Environment Variable: The key is then added to the shell's configuration file (e.g., ~/.zshrc).
3. Load Variable: The shell configuration must be reloaded for the changes to take effect.

The following diagram illustrates the one-time setup flow for the API key.

A concrete example of the command to set the variable is:

echo 'export ELEVENLABS_API_KEY="your_key_here"' >> ~/.zshrc
source ~/.zshrc

Sources: README.md:21-22

Usage in API Calls

The ELEVENLABS_API_KEY environment variable is used in the xi-api-key header for all direct HTTP requests to the ElevenLabs API. The plugin's commands, such as /speak and /voices, wrap these API calls.

The sequence diagram below shows how a command uses the API key to fetch data from ElevenLabs.

Example API Calls

The following code snippets demonstrate how the API key is used in curl commands to interact with different ElevenLabs endpoints.

Fetching available voices:
This command lists all voices associated with the user's account.

curl -s "https://api.elevenlabs.io/v1/voices" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" | jq '.voices[] | {name, voice_id}'

Sources: commands/voices.md:22-24

Generating speech:
This command converts text to speech using a specific voice ID.

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "TEXT_HERE", "model_id": "eleven_v3_alpha"}' \
  --output /tmp/speech.mp3 && afplay /tmp/speech.mp3

Sources: commands/speak.md:28-33

Verification and Management

The plugin provides the /voice-config command to help users manage and verify their API key setup.

Sources: commands/voice-config.md

Key Status Check

The show action (default) of the /voice-config command checks for the presence of the ELEVENLABS_API_KEY environment variable and reports its status.

Action	Description
show	Displays the current API key status (configured/not configured).
test	Plays a test message to confirm the API key is valid and working.

Sources: commands/voice-config.md:9-12, commands/voice-config.md:20-23

The command's instructions explicitly mention this verification step:

1. Check for ELEVENLABS_API_KEY environment variable

Sources: commands/voice-config.md:25

Dependent Components

Nearly all functionality of this plugin relies on a correctly configured API key. The following table lists the core commands and hooks that require the ELEVENLABS_API_KEY to function.

Component	Type	Description	Source File
/speak	Command	Speak text with emotion tags.	commands/speak.md
/dialogue	Command	Generate multi-speaker conversations.	commands/dialogue.md
/create-voice	Command	Create custom voice from text description.	commands/create-voice.md
/transcribe	Command	Convert audio to text.	commands/transcribe.md
/voices	Command	List available ElevenLabs voices.	commands/voices.md
/voice-config	Command	View and modify voice settings, including testing the key.	commands/voice-config.md
Hooks	Automation	Automatically speak notifications for events like Stop and SubagentStop.	hooks/hooks.json

Sources: README.md:29-35

Summary

The ELEVENLABS_API_KEY is the cornerstone of the voice-elevenlabs plugin's authentication system. It is configured once by the user as an environment variable and subsequently used by all commands and hooks that communicate with the ElevenLabs API. The /voice-config command provides a simple utility for users to verify that their key is correctly set up, ensuring seamless operation of the plugin's voice synthesis and transcription features.