## Design a Voice

### cURL

```bash
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`

```json
{
  "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`.