Design a Voice

cURL

curl --request POST \
  --url https://api.heygen.com/v3/voices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '\n{\n  "prompt": "<string>",\n  "gender": "<string>",\n  "locale": "<string>",\n  "seed": 0\n}\n' 

Responses

• 200
• 400
• 401
• 429

{
  "data": {
    "voices": [
      {
        "voice_id": "<string>",
        "name": "<string>",
        "language": "<string>",
        "gender": "<string>",
        "support_pause": true,
        "support_locale": true,
        "type": "public",
        "preview_audio_url": "https://files.heygen.ai/voice/preview_sara.mp3"
      }
    ],
    "seed": 123
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key

• Type: string
• Location: header
• Required: Yes
  HeyGen API key. Obtain from your HeyGen dashboard.

Body

Request body for POST /v3/voices—design a voice via semantic search.

• prompt

  • Type: string
  • Required: Yes
    Natural language description of the desired voice (e.g., 'warm, confident female narrator').
    Required string length: 1 - 1000

• gender

  • Type: string | null
  • Options: 'male' or 'female'.

• locale

  • Type: string | null
  • Description: BCP-47 locale tag to filter by (e.g., 'en-US', 'pt-BR').

• seed

  • Type: integer
  • Default: 0
    Controls which batch of results to return. seed=0 returns the top matches, seed=1 the next batch, etc. Same prompt + seed always returns the same voices.
    Required range: x >= 0

Response

• 200
• Content-Type: application/json
  Successful response
  Data: DesignVoiceResponseData · object
  Response payload for POST /v3/voices.