Skip to main content

​
Quick Example

curl -X POST "https://api.heygen.com/v3/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
    "gender": "male"
  }'
Response
{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "James",
        "language": "English",
        "gender": "male",
        "preview_audio_url": "https://files.heygen.ai/voice/preview/james.mp3",
        "support_pause": true,
        "support_locale": true,
        "type": "public"
      }
    ],
    "seed": 0
  }
}

​
Parameters

ParameterTypeRequiredDescription
promptstringYesText description of the desired voice. Max 1000 characters.
genderstringNoFilter results by "male" or "female".
localestringNoBCP-47 locale tag to filter by (e.g. "en-US", "pt-BR").
seedintegerNoControls which batch of results to return. 0 returns the top matches, 1 the next batch. Same prompt + seed always returns the same voices.

​
Response Fields

FieldTypeDescription
voicesarrayUp to 3 matching voices, ordered by relevance. Each has the same shape as voices returned by GET /v3/voices.
seedintegerThe seed used for this request. Increment to get a different batch of voices.

​
Getting Different Results

If the returned voices don’t fit, increment seed to get the next batch — same prompt, different voices: 
curl -X POST "https://api.heygen.com/v3/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warm, confident male voice with a slight British accent.",
    "gender": "male",
    "seed": 1
  }'
Prompting tips:
  • Specify gender and age ("young woman in her 20s", "mature male voice")
  • Describe the accent ("American Midwest", "slight French accent")
  • Set the tone ("warm and friendly", "authoritative", "playful")
  • Mention pacing ("measured and calm", "energetic and fast")
  • Reference a use case ("suitable for corporate training", "good for storytelling")