Fix for proper ElevenLabs support

Author: edumansky

README.md

@@ -43,7 +43,8 @@ New accounts get $300 in free credits. TTS pricing is ~$4 per 1M characters for
 
 1. Sign up at [elevenlabs.io](https://elevenlabs.io/)
 2. Go to [Profile + API Key](https://elevenlabs.io/app/settings/api-keys)
-3. Copy your API key
+3. Create an API key with these permissions: **Text to Speech > Access**, **Voices > Read**, **Models > Access**
+4. Copy your API key
 
 Free tier includes limited characters per month. Paid plans start at $5/mo.
 
@@ -98,8 +99,6 @@ prompt-tools transcribe --file recording.wav
 
 400+ voices across multiple model families. Default provider.
 
-| Model | Quality | Example Voice | Notes |
-|-------|---------|---------------|-------|
 | Model | Quality | Example Voice | API Used | Notes |
 |-------|---------|---------------|----------|-------|
 | Gemini | Highest | `Achernar`, `Kore`, `Puck` | Generative Language | Bare names, auto-selects best model |
@@ -117,10 +116,19 @@ prompt-tools speak "Hello" --voice Kore --model gemini-2.5-flash-preview-tts -o
 
 ### ElevenLabs
 
-Premium natural voices. Output is converted to IVR-compatible formats (mu-law/A-law WAV) automatically.
+Premium natural voices. Output is converted to IVR-compatible formats (mu-law/A-law WAV) automatically. Voices can be specified by name (e.g., `Sarah`, `Roger`) or voice ID.
+
+| Model | Quality | Notes |
+|-------|---------|-------|
+| `eleven_v3` | Highest | Latest model (default) |
+| `eleven_multilingual_v2` | High | Multilingual |
+| `eleven_flash_v2_5` | Good | Fast, low latency |
+| `eleven_turbo_v2_5` | Good | Low latency, multilingual |
 
 ```bash
-prompt-tools speak "Hello" --provider elevenlabs --voice <voice-id> -o hello.wav
+prompt-tools speak "Hello" --provider elevenlabs --voice Sarah -o hello.wav
+prompt-tools speak "Hello" --provider elevenlabs --voice Sarah --model eleven_multilingual_v2 -o hello.wav
+prompt-tools voices --provider elevenlabs --output table
 ```
 
 ## STT Providers

cmd/config_cmd.go

@@ -193,9 +193,15 @@ var configSetEncodingCmd = &cobra.Command{
 }
 
 var configSetAPIKeyCmd = &cobra.Command{
-	Use:   "set-api-key <provider>",
+	Use:   "set-api-key <google|elevenlabs|assemblyai>",
 	Short: "Store API key in OS keyring (interactive)",
 	Args:  cobra.ExactArgs(1),
+	ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(args) != 0 {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+		return []string{"google", "elevenlabs", "assemblyai"}, cobra.ShellCompDirectiveNoFileComp
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		provider := strings.ToLower(args[0])
 		valid := map[string]bool{"google": true, "elevenlabs": true, "assemblyai": true}
@@ -225,9 +231,15 @@ var configSetAPIKeyCmd = &cobra.Command{
 }
 
 var configClearAPIKeyCmd = &cobra.Command{
-	Use:   "clear-api-key <provider>",
+	Use:   "clear-api-key <google|elevenlabs|assemblyai>",
 	Short: "Remove API key from keyring",
 	Args:  cobra.ExactArgs(1),
+	ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(args) != 0 {
+			return nil, cobra.ShellCompDirectiveNoFileComp
+		}
+		return []string{"google", "elevenlabs", "assemblyai"}, cobra.ShellCompDirectiveNoFileComp
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		provider := strings.ToLower(args[0])
 		valid := map[string]bool{"google": true, "elevenlabs": true, "assemblyai": true}

cmd/speak.go

@@ -29,12 +29,21 @@ Gemini voices automatically use the Generative Language API. Override model with
   gemini-2.5-pro-preview-tts    Highest quality (default for Gemini voices)
   gemini-2.5-flash-preview-tts  Fast, good quality
 
+ElevenLabs voices can be specified by name (e.g., Sarah, Roger) or voice ID.
+ElevenLabs models (override with --model):
+  eleven_v3                     Latest, highest quality (default)
+  eleven_multilingual_v2        High quality, multilingual
+  eleven_flash_v2_5             Fast, low latency
+  eleven_turbo_v2_5             Low latency, multilingual
+
 Examples:
   prompt-tools speak "Hello world" -o hello.wav
   prompt-tools speak "Hello world" --voice Achernar -o hello.wav
   prompt-tools speak --ssml "<speak>Hello<break time='500ms'/>world</speak>" -o hello.wav
   prompt-tools speak --file script.txt --voice en-US-Studio-O -o prompt.wav
-  prompt-tools speak "Hello" --voice Kore --model gemini-2.5-flash-preview-tts -o hello.wav`,
+  prompt-tools speak "Hello" --voice Kore --model gemini-2.5-flash-preview-tts -o hello.wav
+  prompt-tools speak --provider elevenlabs --voice Sarah -o hello.wav
+  prompt-tools speak --provider elevenlabs --voice Sarah --model eleven_v3 -o hello.wav`,
 	Args:  cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		text, _ := cmd.Flags().GetString("text")
@@ -200,7 +209,7 @@ func init() {
 	speakCmd.Flags().Float64("speaking-rate", 0, "Speaking rate multiplier")
 	speakCmd.Flags().Float64("pitch", 0, "Pitch in semitones")
 	speakCmd.Flags().Float64("volume-gain-db", 0, "Volume gain in dB")
-	speakCmd.Flags().String("model", "", "Gemini model (gemini-2.5-pro-preview-tts, gemini-2.5-flash-preview-tts)")
+	speakCmd.Flags().String("model", "", "TTS model (Gemini: gemini-2.5-pro-preview-tts; ElevenLabs: eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5)")
 
 	rootCmd.AddCommand(speakCmd)
 }

cmd/voices.go

@@ -33,10 +33,14 @@ Google voice models (highest to lowest quality):
 Gemini voices use the same star/moon names as Chirp3-HD but are a distinct model
 requiring a model_name parameter (handled automatically by the speak command).
 
+ElevenLabs voices show friendly names (e.g., Sarah, Roger) and voice IDs.
+Either can be used with --voice in the speak command.
+
 Examples:
   prompt-tools voices --language en-US --output table
   prompt-tools voices --language en-US --gender FEMALE
-  prompt-tools voices --provider elevenlabs`,
+  prompt-tools voices --provider elevenlabs
+  prompt-tools voices --provider elevenlabs --gender FEMALE --output table`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		providerName, _ := cmd.Flags().GetString("provider")
 		language, _ := cmd.Flags().GetString("language")

internal/provider/provider.go

@@ -3,6 +3,7 @@ package provider
 // Voice represents a TTS voice.
 type Voice struct {
 	Name              string   `json:"name"`
+	VoiceID           string   `json:"voice_id,omitempty"`
 	Model             string   `json:"model"`
 	LanguageCodes     []string `json:"language_codes"`
 	Gender            string   `json:"gender"`

internal/tts/elevenlabs.go

@@ -31,8 +31,11 @@ func init() {
 func (e *ElevenLabsTTS) Name() string { return "elevenlabs" }
 
 func (e *ElevenLabsTTS) Synthesize(req *provider.TTSRequest) (*provider.TTSResult, error) {
-	// ElevenLabs voice ID — the req.Voice field contains the voice ID
-	voiceID := req.Voice
+	// Resolve voice: accept either a voice ID or a friendly name
+	voiceID, err := e.resolveVoiceID(req.Voice)
+	if err != nil {
+		return nil, err
+	}
 
 	text := req.Text
 	if req.SSML != "" {
@@ -46,9 +49,15 @@ func (e *ElevenLabsTTS) Synthesize(req *provider.TTSRequest) (*provider.TTSResul
 		outputFormat = "mp3_44100_128"
 	}
 
+	// Default to eleven_v3; allow override via --model
+	modelID := "eleven_v3"
+	if req.Model != "" {
+		modelID = req.Model
+	}
+
 	body := map[string]any{
 		"text":     text,
-		"model_id": "eleven_multilingual_v2",
+		"model_id": modelID,
 		"voice_settings": map[string]any{
 			"stability":        0.5,
 			"similarity_boost": 0.75,
@@ -128,6 +137,42 @@ func (e *ElevenLabsTTS) Synthesize(req *provider.TTSRequest) (*provider.TTSResul
 	}, nil
 }
 
+// resolveVoiceID resolves a voice name or ID to an ElevenLabs voice ID.
+// If the input matches a voice ID directly, it's returned as-is.
+// Otherwise, it searches by name (case-insensitive).
+func (e *ElevenLabsTTS) resolveVoiceID(voice string) (string, error) {
+	// ElevenLabs voice IDs are 20-char alphanumeric strings.
+	// If it looks like one, use it directly.
+	if len(voice) == 20 && isAlphanumeric(voice) {
+		return voice, nil
+	}
+
+	// Look up by friendly name (match full name or short name before " - ")
+	voices, err := e.ListVoices("")
+	if err != nil {
+		return "", fmt.Errorf("resolving voice name %q: %w", voice, err)
+	}
+	for _, v := range voices {
+		if strings.EqualFold(v.Name, voice) {
+			return v.VoiceID, nil
+		}
+		// Match short name (e.g., "Sarah" matches "Sarah - Mature, Reassuring")
+		if short, _, ok := strings.Cut(v.Name, " - "); ok && strings.EqualFold(short, voice) {
+			return v.VoiceID, nil
+		}
+	}
+	return "", fmt.Errorf("ElevenLabs voice %q not found — use 'prompt-tools voices --provider elevenlabs' to list available voices", voice)
+}
+
+func isAlphanumeric(s string) bool {
+	for _, r := range s {
+		if !((r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9')) {
+			return false
+		}
+	}
+	return true
+}
+
 func (e *ElevenLabsTTS) ListVoices(languageCode string) ([]provider.Voice, error) {
 	url := fmt.Sprintf("%s/voices", elevenlabsEndpoint)
 
@@ -175,7 +220,8 @@ func (e *ElevenLabsTTS) ListVoices(languageCode string) ([]provider.Voice, error
 		}
 
 		voice := provider.Voice{
-			Name:          v.VoiceID,
+			Name:          v.Name,
+			VoiceID:       v.VoiceID,
 			Model:         "ElevenLabs",
 			LanguageCodes: []string{"multilingual"},
 			Gender:        gender,

skill/SKILL.md

@@ -75,6 +75,21 @@ Gemini voices auto-select the best available model. Override with `--model`:
 2. [Generative Language API](https://console.cloud.google.com/apis/library/generativelanguage.googleapis.com) (for Gemini voices)
 3. [Cloud Speech-to-Text API](https://console.cloud.google.com/apis/library/speech.googleapis.com) (for transcription)
 
+## Voice Types (ElevenLabs)
+
+ElevenLabs voices can be specified by friendly name (e.g., `Sarah`, `Roger`) or voice ID. Names are resolved automatically via the API.
+
+| Model | Quality | Notes |
+|---|---|---|
+| **eleven_v3** | Highest | Latest model (default) |
+| **eleven_multilingual_v2** | High | Multilingual |
+| **eleven_flash_v2_5** | Good | Fast, low latency |
+| **eleven_turbo_v2_5** | Good | Low latency, multilingual |
+
+Override model with `--model`. List voices with `prompt-tools voices --provider elevenlabs`.
+
+**ElevenLabs API key requires these permissions:** Text to Speech > Access, Voices > Read, Models > Access.
+
 ## Speak Examples
 
 ```bash
@@ -99,8 +114,11 @@ prompt-tools speak "Hello" --sample-rate 16000 --encoding linear16 -o hello.wav
 # MP3 output
 prompt-tools speak "Hello" --format mp3 -o hello.mp3
 
-# ElevenLabs provider
-prompt-tools speak "Hello" --provider elevenlabs --voice <voice-id> -o hello.wav
+# ElevenLabs provider (by voice name)
+prompt-tools speak "Hello" --provider elevenlabs --voice Sarah -o hello.wav
+
+# ElevenLabs with specific model
+prompt-tools speak "Hello" --provider elevenlabs --voice Sarah --model eleven_multilingual_v2 -o hello.wav
 ```
 
 ## Voice Listing Examples