Voices

List and manage available voices for speech synthesis.

List Voices

Endpoint

GET /v1/audio/voices

Authentication

Authorization: Bearer gw_prod_...

Query Parameters

Parameter	Type	Required	Description
provider	string	No	Filter by provider: openai, elevenlabs
language	string	No	Filter by language code (e.g., en, es)

Example

curl https://api.gateflow.ai/v1/audio/voices \
  -H "Authorization: Bearer gw_prod_..."

Python

import requests

response = requests.get(
    "https://api.gateflow.ai/v1/audio/voices",
    headers={"Authorization": "Bearer gw_prod_..."}
)

voices = response.json()
for voice in voices["voices"]:
    print(f"{voice['id']}: {voice['name']} ({voice['provider']})")

Response

{
  "voices": [
    {
      "id": "alloy",
      "name": "Alloy",
      "provider": "openai",
      "gender": "neutral",
      "languages": ["en"],
      "preview_url": null,
      "gateflow_standard": "friendly"
    },
    {
      "id": "21m00Tcm4TlvDq8ikWAM",
      "name": "Rachel",
      "provider": "elevenlabs",
      "gender": "female",
      "languages": ["en", "es", "fr", "de", "it", "pt", "pl", "hi", "ar"],
      "preview_url": "https://api.elevenlabs.io/v1/voices/21m00Tcm4TlvDq8ikWAM/preview",
      "gateflow_standard": "friendly"
    }
  ],
  "standard_voices": [
    {
      "id": "professional",
      "description": "Clear, authoritative, confident",
      "mappings": {
        "openai": "onyx",
        "elevenlabs": "josh"
      }
    },
    {
      "id": "friendly",
      "description": "Warm, approachable, welcoming",
      "mappings": {
        "openai": "alloy",
        "elevenlabs": "rachel"
      }
    },
    {
      "id": "calm",
      "description": "Measured, relaxed, reassuring",
      "mappings": {
        "openai": "nova",
        "elevenlabs": "bella"
      }
    },
    {
      "id": "energetic",
      "description": "Enthusiastic, dynamic, engaging",
      "mappings": {
        "openai": "shimmer",
        "elevenlabs": "antoni"
      }
    },
    {
      "id": "serious",
      "description": "Deliberate, precise, professional",
      "mappings": {
        "openai": "fable",
        "elevenlabs": "adam"
      }
    },
    {
      "id": "casual",
      "description": "Natural, informal, easy-going",
      "mappings": {
        "openai": "echo",
        "elevenlabs": "domi"
      }
    }
  ]
}

Get Voice Details

Endpoint

GET /v1/audio/voices/{voice_id}

Example

curl https://api.gateflow.ai/v1/audio/voices/21m00Tcm4TlvDq8ikWAM \
  -H "Authorization: Bearer gw_prod_..."

Response

{
  "id": "21m00Tcm4TlvDq8ikWAM",
  "name": "Rachel",
  "provider": "elevenlabs",
  "description": "A warm, friendly American female voice",
  "gender": "female",
  "age": "young_adult",
  "accent": "american",
  "languages": ["en", "es", "fr", "de", "it", "pt", "pl", "hi", "ar"],
  "use_cases": ["narration", "conversational", "customer_service"],
  "preview_url": "https://api.elevenlabs.io/v1/voices/21m00Tcm4TlvDq8ikWAM/preview",
  "settings": {
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.0,
    "use_speaker_boost": true
  }
}

Custom Voice Mappings

Create custom voice mappings that work across providers.

Create Mapping

POST /v1/management/voice-mappings

curl -X POST https://api.gateflow.ai/v1/management/voice-mappings \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "description": "Voice for customer support interactions",
    "mappings": {
      "openai": "nova",
      "elevenlabs": "21m00Tcm4TlvDq8ikWAM"
    },
    "default_settings": {
      "stability": 0.6,
      "speed": 1.0
    }
  }'

Response

{
  "id": "voice_map_abc123",
  "name": "customer-support",
  "description": "Voice for customer support interactions",
  "mappings": {
    "openai": "nova",
    "elevenlabs": "21m00Tcm4TlvDq8ikWAM"
  },
  "created_at": "2026-02-16T10:00:00Z"
}

Use Custom Mapping

response = client.audio.speech.create(
    model="auto",
    input="How can I help you today?",
    voice="customer-support"  # Your custom mapping
)

List Custom Mappings

curl https://api.gateflow.ai/v1/management/voice-mappings \
  -H "Authorization: Bearer gw_prod_..."

Delete Mapping

curl -X DELETE https://api.gateflow.ai/v1/management/voice-mappings/voice_map_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key"

Voice Preview

Get a preview audio sample for a voice.

Endpoint

GET /v1/audio/voices/{voice_id}/preview

Example

curl https://api.gateflow.ai/v1/audio/voices/21m00Tcm4TlvDq8ikWAM/preview \
  -H "Authorization: Bearer gw_prod_..." \
  --output preview.mp3

Provider-Specific Voices

OpenAI Voices

Voice	Gender	Description
alloy	Neutral	Balanced, conversational
echo	Male	Casual, relaxed
fable	Male	British, narrative
onyx	Male	Deep, authoritative
nova	Female	Warm, professional
shimmer	Female	Expressive, dynamic

ElevenLabs Voices

Voice ID	Name	Gender	Description
21m00Tcm4TlvDq8ikWAM	Rachel	Female	Warm, conversational
29vD33N1CtxCmqQRPOHJ	Drew	Male	Professional, clear
2EiwWnXFnvU5JabPnv8n	Clyde	Male	Deep, narrative
5Q0t7uMcjvnagumLfvZi	Paul	Male	News anchor style
AZnzlk1XvdvUeBnXmlld	Domi	Female	Young, energetic
CYw3kZ02Hs0563khs1Fj	Dave	Male	British, conversational
D38z5RcWu1voky8WS1ja	Fin	Male	Irish, friendly
EXAVITQu4vr4xnSDxMaL	Bella	Female	Soft, soothing
ErXwobaYiN019PkySvjV	Antoni	Male	Energetic, youthful
MF3mGyEYCl7XYWbV9V6O	Elli	Female	Young, clear
TxGEqnHWrfWFTfGW9XjX	Josh	Male	Deep, professional

Errors

Code	Description
400	Invalid parameters
401	Invalid API key
404	Voice not found
429	Rate limit exceeded

See Also

• Speech Synthesis - Generate speech
• Voice Mapping - Voice configuration guide
• Audio Providers - Provider setup