---
title: "List the voices | GPT-Video API reference"
description: "Lists the synthetic voices of a language that a voiceover can use. Call it with GET /v1/reference/voices."
url: "https://www.gpt-video.com/developers/api/list-voices"
operation: "list_voices"
method: "GET"
path: "/v1/reference/voices"
scope: "clips:read"
---

Do not assume endpoints have parameters other than the ones explicitly specified.

# List the voices

Operation id `list_voices`. Request `GET /v1/reference/voices`.

Lists the synthetic voices of a language that a voiceover can use.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

## About

Call this before create_voiceover (`POST /v1/voiceovers`) to choose a voice: send the language of the script, and use the id of one of the voices returned. A voice speaks one language only. The list is short and the same for every account, so it is not paged. New voices can be added over time, so read the list instead of copying it into your code.

## Example use

A script that makes a voiceover for an English script asks list_voices (`GET /v1/reference/voices`) for that language, shows the voice names to a person or takes the first one, and sends its id to create_voiceover (`POST /v1/voiceovers`).

## Endpoint

```text
GET https://api.gpt-video.com/v1/reference/voices
```

- Scope `clips:read`.
- Rate limit 120 requests a minute for each key and 240 for each account, shared by every `read` call. See [rate limits](/developers/rate-limits.md).
- No `Idempotency-Key`.

## Parameters

### Query

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `language` | string | Required | The language of the voices: en for English, it for Italian. One of `en`, `it`. |

## Request

The English voices.

```bash title="curl"
curl "https://api.gpt-video.com/v1/reference/voices?language=en" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"
```

```ts title="TypeScript"
const res = await fetch("https://api.gpt-video.com/v1/reference/voices?language=en", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);
```

```python title="Python"
import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/reference/voices?language=en",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)
```

```json title="MCP (Full)"
{
  "method": "tools/call",
  "params": {
    "name": "list_voices",
    "arguments": {
      "language": "en"
    }
  }
}
```

## Response

A successful call answers HTTP 200.

### Fields to check

| Name | Type | Description |
| --- | --- | --- |
| `voices[].id` | string | The voice id, like en-aria. |

### Response example

```json title="HTTP 200"
{
  "voices": [
    {
      "id": "en-aria",
      "name": "Aria",
      "language": "en",
      "gender": "female"
    },
    {
      "id": "en-jenny",
      "name": "Jenny",
      "language": "en",
      "gender": "female"
    },
    {
      "id": "en-guy",
      "name": "Guy",
      "language": "en",
      "gender": "male"
    },
    {
      "id": "en-christopher",
      "name": "Christopher",
      "language": "en",
      "gender": "male"
    }
  ]
}
```

**All response fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `voices` | array of objects | Required | The voices of the language, in a fixed order. |
| `voices[].id` | string | Required | The voice id, like en-aria. |
| `voices[].name` | string | Required |   |
| `voices[].language` | string | Required | One of `en`, `it`. |
| `voices[].gender` | string | Required | One of `female`, `male`. |

**More examples**

#### The Italian voices

`GET /v1/reference/voices?language=it`

```json title="HTTP 200"
{
  "voices": [
    {
      "id": "it-elsa",
      "name": "Elsa",
      "language": "it",
      "gender": "female"
    },
    {
      "id": "it-isabella",
      "name": "Isabella",
      "language": "it",
      "gender": "female"
    },
    {
      "id": "it-diego",
      "name": "Diego",
      "language": "it",
      "gender": "male"
    },
    {
      "id": "it-giuseppe",
      "name": "Giuseppe",
      "language": "it",
      "gender": "male"
    }
  ]
}
```

## Errors

Every call can also answer these errors. [`VALIDATION_FAILED`](/developers/errors.md#VALIDATION_FAILED), [`UNKNOWN_PARAMETER`](/developers/errors.md#UNKNOWN_PARAMETER), [`UNAUTHORIZED`](/developers/errors.md#UNAUTHORIZED), [`SCOPE_MISSING`](/developers/errors.md#SCOPE_MISSING), [`RATE_LIMITED`](/developers/errors.md#RATE_LIMITED), [`INTERNAL`](/developers/errors.md#INTERNAL), [`UNAVAILABLE`](/developers/errors.md#UNAVAILABLE).

## Cost

No credits are used.

## Related operations

- [`get_setting_options`](/developers/api/get-setting-options.md) (`GET /v1/reference/setting-options`) Get the setting options
- [`create_voiceover`](/developers/api/create-voiceover.md) (`POST /v1/voiceovers`) Create a voiceover
- [`create_reddit_story_project`](/developers/api/create-reddit-story-project.md) (`POST /v1/projects/reddit-story`) Create a Reddit story project
- [`update_reddit_story_project`](/developers/api/update-reddit-story-project.md) (`PATCH /v1/projects/{projectId}/reddit-story`) Update a Reddit story project
- [`build_reddit_story_video`](/developers/api/build-reddit-story-video.md) (`POST /v1/projects/{projectId}/reddit-story/build`) Build a Reddit story video

## Questions

### Can I use a voice for a script in another language?

No. create_voiceover (`POST /v1/voiceovers`) answers VALIDATION_FAILED when the voice does not speak the language of the script, and nothing is used.

### Can the list change?

Voices can be added. Read the list when you need it instead of copying it into your code, and an id you already use keeps working.