curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_save_preview' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","previewId":"44444444-4444-4444-8444-444444444444","name":"Studio narrator"}'
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
previewId: '44444444-4444-4444-8444-444444444444',
name: 'Studio narrator',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_save_preview', {
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);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/voices_save_preview",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "previewId": "44444444-4444-4444-8444-444444444444", "name": "Studio narrator"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"voicePreviews": [],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
},
"voice": {
"accent": "original",
"id": "clone:44444444-4444-4444-8444-444444444444",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
}
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"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"
}
Speech voices
Save a voice preview
Save an owned, unexpired cloned or designed voice preview as a reusable voice. Repeated saves of the same preview reuse the saved voice.
POST
/
v1
/
actions
/
voices_save_preview
curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_save_preview' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","previewId":"44444444-4444-4444-8444-444444444444","name":"Studio narrator"}'
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
previewId: '44444444-4444-4444-8444-444444444444',
name: 'Studio narrator',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_save_preview', {
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);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/voices_save_preview",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "previewId": "44444444-4444-4444-8444-444444444444", "name": "Studio narrator"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"voicePreviews": [],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
},
"voice": {
"accent": "original",
"id": "clone:44444444-4444-4444-8444-444444444444",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
}
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"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"
}
Save an owned, unexpired cloned or designed voice preview as a reusable voice. Repeated saves of the same preview reuse the saved voice.
Required permissions:
POST https://api.voicecheap.ai/v1/actions/voices_save_preview
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.
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.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.
Complete input schema
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.
{
"type": "object",
"properties": {
"requestId": {
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
"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}$"
},
"previewId": {
"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})$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": ["previewId", "name"],
"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.curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_save_preview' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","previewId":"44444444-4444-4444-8444-444444444444","name":"Studio narrator"}'
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
previewId: '44444444-4444-4444-8444-444444444444',
name: 'Studio narrator',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_save_preview', {
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);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/voices_save_preview",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "previewId": "44444444-4444-4444-8444-444444444444", "name": "Studio narrator"},
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 reusable TTS voice, updated saved-slot allowance, and remaining active unsaved previews and creation allowances.{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"voicePreviews": [],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
},
"voice": {
"accent": "original",
"id": "clone:44444444-4444-4444-8444-444444444444",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
}
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"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.voicePreviews | All currently active, unsaved previews for this account, including candidates from earlier requests. |
data.voicePreviews[].id | Preview UUID v4 used by voices_preview_get and voices_save_preview. |
data.voicePreviews[].kind | clone or design. |
data.voicePreviews[].name | Preview display name; designed candidates append a number to the requested name. |
data.voicePreviews[].previewUrl | Temporary playable audio URL. Request a fresh URL with voices_preview_get while the preview remains active. |
data.voicePreviews[].expiresAt | Preview expiry as a Unix timestamp in milliseconds. |
data.voicePreviews[].durationSeconds | Preview audio duration in seconds. |
data.creationUsage.cloneTrial | Lifetime clone preview trial allowance with limit, used, and remaining. |
data.creationUsage.design | Daily voice design allowance with limit, used, remaining, and resetsAt in Unix milliseconds. |
data.creationUsage.previewExpiresAfterHours | Lifetime of an unsaved preview in hours, currently 24. |
data.voice.id | Reusable TTS selection ID clone:<UUID>. Use the whole value for tts_generate and only the UUID for voices_delete. |
data.voice.name | Saved voice display name. |
data.voice.accent | Saved custom voices use original. |
data.voice.source | Saved custom voices use clone. |
data.voice.previewUrl | Temporary audio preview URL for the saved voice. |
data.cloneUsage.canClone | Whether the current plan permits saved custom TTS voices; inspect remaining for available slots. |
data.cloneUsage.limit | Plan limit for saved custom TTS voice slots. |
data.cloneUsage.used | Occupied TTS voice slots, including reserved creations. |
data.cloneUsage.remaining | Available saved TTS voice slots. |
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.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":"voices_save_preview"}'
HTTP 200
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_save_preview",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"voicePreviews": [],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
},
"voice": {
"accent": "original",
"id": "clone:44444444-4444-4444-8444-444444444444",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
}
}
}
}
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.
- previewId is the owned candidate UUID returned by voices_preview_clone or voices_design. name contains 1–80 trimmed characters.
- Saving requires a paid plan, an available saved TTS voice slot, and an unexpired ready preview. This action works for cloned and designed candidates.
- The reusable selection ID is clone:<previewId>. A saved candidate disappears from voicePreviews; voices_list includes it among saved voices.
- Repeated saves of the same already-saved candidate reuse the saved voice. The original saved name is retained on a repeated save.
- voice can be omitted if the saved voice is not present in the refreshed voice list. Retrieve current saved voices through voices_list.
- 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 | 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. |
| 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. |
| 403 | VOICE_CLONING_REQUIRES_PAID_PLAN | The current plan cannot save and reuse custom TTS voices. |
| 404 | USER_NOT_FOUND | The authenticated account no longer exists. |
| 404 | VOICE_PREVIEW_NOT_FOUND | The preview is missing or belongs to another account. |
| 409 | CONCURRENT_ACTION_LIMIT_REACHED | This account already has 10 integration actions running. Poll an existing request before starting another. |
| 409 | IDEMPOTENCY_CONFLICT | Reuse an identifier only with the same operation and arguments. |
| 409 | VOICE_CLONE_LIMIT_REACHED | All saved custom TTS voice slots are occupied. |
| 409 | VOICE_CREATION_IN_PROGRESS | This candidate is still being saved or account deletion blocks new voice work. |
| 410 | VOICE_PREVIEW_EXPIRED | The candidate is expired, is not ready, or no longer has usable preview audio. |
| 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. |
| 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. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["voices:write"]
}
}
Was this page helpful?

