Skip to main content
POST
Clone and save a custom voice from 1–3 owned audio uploads. Explicit permission is required. Samples must total 10–120 seconds and each be at most 20 MB. Plan voice limits apply.

​
Authentication and permissions

​
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.
Required permissions: voices:write. An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.

​
Parameters

​
string
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}$.
​
string
required
Text value.Minimum length: 1. Maximum length: 80.
​
array
required
List of values. See the complete input schema for its item structure.Minimum items: 1. Maximum items: 3.
​
boolean
required
Confirm that you have permission to clone the person whose voice is in every sample.Required value: true.
​
boolean
Boolean value.Default: false.
​
string
Text value.Maximum length: 35. Pattern: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$.
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.

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

​
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 reusable custom TTS voice and the updated saved-slot allowance.

​
Result fields

​
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.
HTTP 200

​
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.
  • Upload 1–3 owned audio samples and use their completed fileKey values. Supported sample formats are MP3, WAV, M4A, OGG, and Opus; each file must be nonempty and at most 20 MiB (20,971,520 bytes). Remote URLs and other accounts’ uploads are refused.
  • Samples must total at least 10 seconds and at most 120 seconds of readable audio. trimToMaxDuration defaults to false; set it to true to proportionally trim samples totaling more than 120 seconds.
  • hasPermission must be the JSON boolean true, confirming permission for every sample. A string value such as “true” is rejected.
  • name must contain 1–80 trimmed characters. Optional language accepts a 2–3 letter code with optional subtags and a maximum of 35 characters.
  • This action directly saves the cloned voice and occupies a saved TTS voice slot. It does not consume the one-time clone preview trial.
  • Use the returned voice.id in tts_generate. For a direct clone, its UUID is the requestId; voices_delete takes that UUID without the clone: prefix.
  • The accepted language field does not change the direct-save clone workflow. Choose voices_preview_clone when you need a language-specific preview script.
  • 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