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

# Get a dubbing voice

> Get metadata and a playable example for one catalog or owned custom dubbing voice.

Get metadata and a playable example for one catalog or owned custom dubbing voice.

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

## 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="voiceId" type="string" required>
  Text value.

  Minimum length: 1. Maximum length: 255. Pattern: `^[A-Za-z0-9_-]+$`.
</ParamField>

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

  Allowed values: "en", "fr", "es", "de", "it", "pt", "pl", "zh", "ja". Default: "en".
</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": {
      "voiceId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "pattern": "^[A-Za-z0-9_-]+$"
      },
      "locale": {
        "default": "en",
        "type": "string",
        "enum": ["en", "fr", "es", "de", "it", "pt", "pl", "zh", "ja"]
      }
    },
    "required": ["voiceId"],
    "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_get' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"voiceId":"dubbing_voice_R8q3k9Yp","locale":"en"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    voiceId: 'dubbing_voice_R8q3k9Yp',
    locale: 'en',
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/dubbing_voices_get', {
    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_get",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"voiceId": "dubbing_voice_R8q3k9Yp", "locale": "en"},
      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.

One catalog or owned custom dubbing voice with its public metadata and optional playable example.

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "data": {
      "id": "dubbing_voice_R8q3k9Yp",
      "name": "Studio narrator",
      "source": "custom",
      "previewUrl": "https://files.example.com/dubbing-narrator.mp3"
    }
  }
  ```
</ResponseExample>

## Result fields

| Field | Description |
| - | - |
| `data.id` | Opaque dubbing voice ID; use for dubbing operations, not tts\_generate. |
| `data.name` | Voice display name in the requested locale when localized metadata is available. |
| `data.source` | custom for owned saved dubbing voices, or catalog. |
| `data.previewUrl` | Optional absolute playable example URL. |
| `data.language` | Optional catalog language code. Custom voices generally omit language metadata. |
| `data.languages` | Optional list of catalog language codes. |
| `data.accent` | Optional localized catalog accent. |
| `data.description` | Optional localized catalog description. |
| `data.age` | Optional localized catalog age description. |
| `data.gender` | Optional localized catalog gender description. |
| `data.useCase` | Optional localized catalog use case. |
| `data.category` | Optional localized catalog category. |

## Operation notes

* Use voiceId from dubbing\_voices\_list. It is an opaque 1–255 character ID containing only letters, digits, underscores, and hyphens.
* locale has the same defaults and accepted values as dubbing\_voices\_list. Catalog voices can include localized language, accent, description, age, gender, useCase, and category metadata.
* Owned custom voices return source: custom and optional previewUrl; they omit the catalog language fields. A raw clone response’s audioExampleUrl is represented as previewUrl here.
* 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. |
| 404 | `DUBBING_VOICE_NOT_FOUND` | The voice is not in the available catalog or the authenticated account’s saved dubbing voices. |
| 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.