List the voices

Q: Can I use a voice for a script in another language?

No. create_voiceover answers VALIDATION_FAILED when the voice does not speak the language of the script, and nothing is used.

list_voicesGET/v1/reference/voicesBeta

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

Code

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.
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.

curl

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

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

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)

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

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

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, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

get_setting_options (GET /v1/reference/setting-options) Get the setting options
create_voiceover (POST /v1/voiceovers) Create a voiceover
create_reddit_story_project (POST /v1/projects/reddit-story) Create a Reddit story project
update_reddit_story_project (PATCH /v1/projects/{projectId}/reddit-story) Update a Reddit story project
build_reddit_story_video (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.

View as Markdown