Get a voice preview

curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_preview_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"previewId":"44444444-4444-4444-8444-444444444444"}'

const input = {
  previewId: '44444444-4444-4444-8444-444444444444',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_preview_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);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/voices_preview_get",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"previewId": "44444444-4444-4444-8444-444444444444"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

{
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "kind": "clone",
    "name": "Studio narrator",
    "previewUrl": "https://files.example.com/narrator-preview.mp3",
    "expiresAt": 1792238400000,
    "durationSeconds": 10
  }
}

POST

actions

voices_preview_get

curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_preview_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"previewId":"44444444-4444-4444-8444-444444444444"}'

const input = {
  previewId: '44444444-4444-4444-8444-444444444444',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_preview_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);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/voices_preview_get",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"previewId": "44444444-4444-4444-8444-444444444444"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

{
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "kind": "clone",
    "name": "Studio narrator",
    "previewUrl": "https://files.example.com/narrator-preview.mp3",
    "expiresAt": 1792238400000,
    "durationSeconds": 10
  }
}

Get a playable temporary URL for your unsaved cloned or designed voice preview. Use voices_save_preview to keep it before it expires.

POST https://api.voicecheap.ai/v1/actions/voices_preview_get

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

Parameters

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})$.

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": {
    "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})$"
    }
  },
  "required": ["previewId"],
  "additionalProperties": false
}

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_preview_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"previewId":"44444444-4444-4444-8444-444444444444"}'

const input = {
  previewId: '44444444-4444-4444-8444-444444444444',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_preview_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);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/voices_preview_get",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"previewId": "44444444-4444-4444-8444-444444444444"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

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 active owned voice preview, with a refreshed temporary playback URL and its expiry.

{
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "kind": "clone",
    "name": "Studio narrator",
    "previewUrl": "https://files.example.com/narrator-preview.mp3",
    "expiresAt": 1792238400000,
    "durationSeconds": 10
  }
}

Result fields

Field	Description
`data.id`	Candidate UUID for voices_save_preview.
`data.kind`	clone or design.
`data.name`	Candidate display name.
`data.previewUrl`	Fresh temporary playable audio URL.
`data.expiresAt`	Candidate expiry as a Unix timestamp in milliseconds.
`data.durationSeconds`	Preview audio duration in seconds.

Operation notes

previewId is the candidate UUID returned in voicePreviews by voices_preview_clone, voices_design, or voices_list.
Only ready, unsaved, unexpired previews are visible. A saved candidate moves to voices_list as clone:<previewId>. Expired, saved, missing, and unowned candidates return VOICE_PREVIEW_NOT_FOUND here.
The URL is temporary and can expire before expiresAt. Save the chosen candidate with voices_save_preview before the preview itself expires.
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	`USER_NOT_FOUND`	The authenticated account no longer exists.
404	`VOICE_PREVIEW_NOT_FOUND`	The preview is missing, unowned, already saved, or expired.
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.

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

Overview

Discovery

Account

Usage and activity

Settings and notifications

Team

Projects

Translation and dubbing

Transcripts and editing

Text to speech

Speech voices

Dubbing voices

Transcription

Subtitles and captions

Images

Thumbnails

Folders

Glossary

Webhooks

Publishing

Request status

OAuth and MCP protocol

Authentication and permissions

Parameters

Request examples

Response

Result fields

Operation notes

Usage

Errors

​Authentication and permissions

​Parameters

​Request examples

​Response

​Result fields

​Operation notes

​Usage

​Errors

Authentication and permissions

Parameters

Request examples

Response

Result fields

Operation notes

Usage

Errors