> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List dubbing voices

> Browse the same dubbing voice catalog as the app and your saved custom dubbing voices, including playable examples and your voice slot allowance. These IDs are for video dubbing; voices_list provides the separate text-to-speech library.

Browse the same dubbing voice catalog as the app and your saved custom dubbing voices, including playable examples and your voice slot allowance. These IDs are for video dubbing; voices\_list provides the separate text-to-speech library.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/dubbing_voices_list
```

## Authentication and permissions

<ParamField header="x-api-key" type="string" required>
  Send a VoiceCheap API key in this header. Authorization: Bearer with the same API key is also supported. OAuth access tokens are accepted only by
  MCP, not by this REST endpoint.
</ParamField>

Required permissions: `voices:read`.

An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.

## Parameters

<ParamField body="locale" type="string">
  Text value.

  Allowed values: "en", "fr", "es", "de", "it", "pt", "pl", "zh", "ja". Default: "en".
</ParamField>

<ParamField body="language" type="string">
  Text value.

  Minimum length: 2. Maximum length: 35.
</ParamField>

<ParamField body="search" type="string">
  Text value.

  Maximum length: 100.
</ParamField>

<Accordion title="Complete input schema">
  The JSON Schema below preserves the exact field names, nested types, defaults, bounds, and accepted values exposed by discovery. Additional cross-field rules are listed in the operation notes.

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "locale": {
        "default": "en",
        "type": "string",
        "enum": ["en", "fr", "es", "de", "it", "pt", "pl", "zh", "ja"]
      },
      "language": {
        "type": "string",
        "minLength": 2,
        "maxLength": 35
      },
      "search": {
        "type": "string",
        "maxLength": 100
      }
    },
    "additionalProperties": false
  }
  ```
</Accordion>

## Request examples

Replace example resource identifiers and media keys with values returned for your account. Keep the request identifier stable when retrying the same mutation.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/v1/actions/dubbing_voices_list' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"locale":"en","language":"en","search":"Studio narrator"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    locale: 'en',
    language: 'en',
    search: 'Studio narrator',
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/dubbing_voices_list', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VOICECHEAP_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.code + ': ' + body.message);
  console.log(body);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.voicecheap.ai/v1/actions/dubbing_voices_list",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"locale": "en", "language": "en", "search": "Studio narrator"},
      timeout=120,
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
  print(body)
  ```
</RequestExample>

## Response

A successful first execution returns HTTP 200 with the operation result under data. A replay may return saved request state instead. The example shows one supported response, not every optional field.

Matching catalog and owned custom video dubbing voices, plus the current saved dubbing voice allowance.

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "data": {
      "voices": [
        {
          "id": "dubbing_voice_R8q3k9Yp",
          "name": "Studio narrator",
          "source": "custom",
          "previewUrl": "https://files.example.com/dubbing-narrator.mp3"
        }
      ],
      "cloneUsage": {
        "limit": 7,
        "used": 1,
        "remaining": 6
      }
    }
  }
  ```
</ResponseExample>

## Result fields

| Field | Description |
| - | - |
| `data.voices` | Matching owned custom dubbing voices followed by catalog dubbing voices. |
| `data.voices[].id` | Opaque dubbing voice ID; use for dubbing operations, not tts\_generate. |
| `data.voices[].name` | Voice display name in the requested locale when localized metadata is available. |
| `data.voices[].source` | custom for owned saved dubbing voices, or catalog. |
| `data.voices[].previewUrl` | Optional absolute playable example URL. |
| `data.voices[].language` | Optional catalog language code. Custom voices generally omit language metadata. |
| `data.voices[].languages` | Optional list of catalog language codes. |
| `data.voices[].accent` | Optional localized catalog accent. |
| `data.voices[].description` | Optional localized catalog description. |
| `data.voices[].age` | Optional localized catalog age description. |
| `data.voices[].gender` | Optional localized catalog gender description. |
| `data.voices[].useCase` | Optional localized catalog use case. |
| `data.voices[].category` | Optional localized catalog category. |
| `data.cloneUsage.limit` | Current plan’s saved custom dubbing voice slot limit. |
| `data.cloneUsage.used` | Number of saved custom dubbing voices. |
| `data.cloneUsage.remaining` | Unused saved custom dubbing voice slots. |

## Operation notes

* This is the video dubbing library. Use voices\_list for the separate TTS catalog and clone:\<UUID> selections.
* locale defaults to en and accepts en, fr, es, de, it, pt, pl, zh, and ja. Missing localized text falls back to English or another available translation.
* Optional search is a case-insensitive substring match across the voice name and localized description, with a maximum of 100 trimmed characters.
* Optional language contains 2–35 characters and is matched exactly against catalog language or languages metadata. Voices without language metadata, including custom voices, remain included.
* The list is not paginated. Catalog and custom voices have different optional metadata. Clone slot usage counts saved custom dubbing voices only.
* The example filters to one owned custom voice. Its list field is previewUrl; cloning returns the same audio example under audioExampleUrl.
* Speech history and custom voices belong to the authenticated account. Team billing does not grant access to another member’s speech or voices.

## Usage

Each successful invocation consumes one monthly API/MCP call. Media credits and the operation's own generation allowances also apply.

## Errors

| HTTP status | Code | Meaning or recovery |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Credentials were supplied in an access\_token or api\_key query parameter. Send credentials in headers. |
| 400 | `VALIDATION_ERROR` | The input does not match the action schema; inspect details for field errors. |
| 401 | `API_KEY_EXPIRED` | The API key has expired. |
| 401 | `INVALID_API_KEY` | Provide a valid, unexpired API key. |
| 401 | `INVALID_CREDENTIAL` | The Authorization header is malformed or conflicts with x-api-key. |
| 401 | `MISSING_CREDENTIAL` | No usable header credential was supplied, or it exceeded 4096 characters. |
| 401 | `USER_NOT_FOUND` | The credential's account no longer exists. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | The credential's user belongs to more than one team, so the billing context is ambiguous. |
| 403 | `INSUFFICIENT_SCOPE` | Grant every required permission or choose another credential. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | The account's integration limits could not be verified. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use an active paid subscription. |
| 403 | `TEAM_OWNER_NOT_FOUND` | The effective team owner account could not be found. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Wait for the monthly reset or change plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Wait for Retry-After when present and use backoff. |
| 500 | `INTERNAL_ERROR` | Check saved request state and resource history before deciding to retry a mutation. |
| 503 | `SERVER_RESTARTING` | The server is restarting. Retry shortly and keep the same request identifier for a mutation. |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["voices:read"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.