> ## 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. # Clone a dubbing voice > Create a saved custom video-dubbing voice from an owned uploaded audio sample with explicit permission. Uses the app’s custom voice slot limit and includes an audio example. Reuse requestId to avoid duplicate creation. Create a saved custom video-dubbing voice from an owned uploaded audio sample with explicit permission. Uses the app’s custom voice slot limit and includes an audio example. Reuse requestId to avoid duplicate creation. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/dubbing_voices_clone ``` ## Authentication and permissions 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. Required permissions: `voices:write`. An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits. ## Parameters Optional at the transport boundary: the server injects an identifier before validation when omitted. Supply your own stable UUID v4 to recover safely from a lost response. Format: "uuid". Pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`. Text value. Minimum length: 1. Maximum length: 80. Text value. Minimum length: 1. Maximum length: 1024. Boolean value. Required value: true. 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": { "requestId": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "fileKey": { "type": "string", "minLength": 1, "maxLength": 1024 }, "hasPermission": { "type": "boolean", "const": true } }, "required": ["name", "fileKey", "hasPermission"], "additionalProperties": false } ``` ## Idempotency Use a UUID v4 in requestId or the Idempotency-Key HTTP header for each mutation. Reuse the same identifier and identical arguments after a network failure. If both are supplied, they must match. Replaying a saved request does not repeat the operation or charge another monthly call. Failed or interrupted requests are not restarted automatically. Every mutation can return HTTP 202 when a retry finds the same request still running, even when its first execution is normally synchronous. If execution completed but resultStored is false, a retry returns HTTP 200 with saved request state instead of the original result. Retrieve the output through its domain history, result, or download action. ## 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. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/dubbing_voices_clone' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","name":"Studio narrator","fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav","hasPermission":true}' ``` ```javascript JavaScript theme={null} const input = { requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91', name: 'Studio narrator', fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav', hasPermission: true, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/dubbing_voices_clone', { 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_clone", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "name": "Studio narrator", "fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav", "hasPermission": True}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## Response This operation returns HTTP 202 while running. Save requestId and poll action\_request\_get with that identifier and the original operation name. Polling states are running, completed, failed, and interrupted. A completed result can point to a separate media job; continue with the operation-specific status or output action. The saved custom dubbing voice, including its ID, name, and optional audio example. There is no TTS-style voice or cloneUsage envelope. ```json HTTP 202 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "status": "running", "pollAction": "action_request_get", "pollAfterSeconds": 5 }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 200 theme={null} { "data": { "id": "dubbing_voice_R8q3k9Yp", "name": "Studio narrator", "audioExampleUrl": "https://files.example.com/dubbing-narrator.mp3" }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ## Result fields | Field | Description | | - | - | | `data.id` | Opaque saved dubbing voice ID. | | `data.name` | Saved voice display name. | | `data.audioExampleUrl` | Optional playable example audio URL. List and get responses expose this as previewUrl. | ## Recover and poll this request Use the same identifier even after a lost connection. If resultStored is false, retrieve the output through the corresponding history, result, or download action. Never start a second generation merely to check progress. ```bash theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"dubbing_voices_clone"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "id": "dubbing_voice_R8q3k9Yp", "name": "Studio narrator", "audioExampleUrl": "https://files.example.com/dubbing-narrator.mp3" } } } ``` ## Operation notes * Use a UUID v4 requestId for this mutation and reuse it with identical arguments when retrying. Long-running actions first return a running request; this example is the completed handler result available from action\_request\_get. * This action accepts one owned completed audio upload and requires hasPermission: true as a JSON boolean. It does not accept a remote URL or another account’s fileKey. * Supported sample extensions are AAC, AC3, EAC3, FLAC, M4A, X-M4A, MP2, MP3, OGG, and WAV. The file must be nonempty, readable audio within the plan’s upload limit and at most 250,000,000 bytes (250 MB). * The dedicated voices*upload*\* family is stricter: MP3, WAV, M4A, OGG, or Opus and at most 20 MiB per upload. A file accepted by that upload family must still match this dubbing action’s supported sample types; Opus is not supported here. * name contains 1–80 trimmed characters and cannot contain control characters. * The 10–120 second combined-sample rule for TTS voice cloning does not apply to this action. Its sample must have a readable positive duration and must not exceed 45 minutes; audio is not automatically trimmed to that limit. * Uses the account’s saved custom dubbing voice slot allowance. Call dubbing\_voices\_list for updated cloneUsage; the clone result itself does not include it. * Use the returned opaque id for dubbing. It does not have a clone: prefix and cannot be used as a TTS voice selection. * 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 | `BAD_REQUEST` | The sample has no readable positive duration, exceeds the 45-minute dubbing clone duration limit, or is refused as too long. | | 400 | `CREDENTIAL_IN_QUERY` | Credentials were supplied in an access\_token or api\_key query parameter. Send credentials in headers. | | 400 | `IDEMPOTENCY_CONFLICT` | The Idempotency-Key header and requestId body field must match. | | 400 | `INVALID_REQUEST_ID` | Supply a UUID v4 requestId or Idempotency-Key. | | 400 | `VALIDATION_ERROR` | The input does not match the action schema; inspect details for field errors. | | 400 | `VOICE_NAME_INVALID` | The name is empty, too long, or contains a control character. | | 400 | `VOICE_SAMPLE_INVALID_SIZE` | The sample is empty, its actual bytes do not match its declared size, or it exceeds the current plan limit or 250 MB. | | 400 | `VOICE_SAMPLE_INVALID_TYPE` | The sample filename is not a supported dubbing audio format. | | 400 | `VOICE_SAMPLE_NOT_OWNED` | The uploaded sample is unsafe or does not belong to the authenticated account. | | 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 | `ACCOUNT_UNAVAILABLE` | The acting or billing account is unavailable or being deleted. | | 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. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | This account already has 10 integration actions running. Poll an existing request before starting another. | | 409 | `DUBBING_VOICE_LIMIT_REACHED` | All saved custom dubbing voice slots are occupied. | | 409 | `IDEMPOTENCY_CONFLICT` | This requestId was already used with different dubbing voice input. | | 409 | `VOICE_MUTATION_IN_PROGRESS` | Another dubbing voice mutation is running for this account. | | 409 | `VOICE_MUTATION_LEASE_LOST` | The mutation lost its execution claim. Inspect request status and saved voices before retrying. | | 409 | `VOICE_REQUEST_ALREADY_STARTED` | This voice request previously started but has no confirmed final result. List voices and inspect request status before starting another request. | | 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` | The voice action could not be completed. Inspect request status and saved voices before starting a new mutation. | | 502 | `INTERNAL_ERROR` | The action could not be completed or its outcome could not be confirmed. Inspect request status and resource history before starting another generation. | | 503 | `ACTION_RESULT_UNAVAILABLE` | The action ran but its result could not be saved. Inspect saved request state and resource history before starting a new generation. | | 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:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.