curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}'
const input = {};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_list', {
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_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"voices": [
{
"accent": "original",
"id": "clone:33333333-3333-4333-8333-333333333333",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
{
"id": "933563129e564b19a115bedd57b7406a",
"name": "Sarah",
"accent": "english",
"gender": "female",
"style": "conversational",
"previewFileName": "sarah-en.mp3",
"source": "catalog"
}
],
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
},
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
Głosy do syntezy mowy
Wyświetl głosy i podglądy głosów
Wyświetl dostępne głosy do syntezy mowy, swoje zapisane własne głosy, niewygasłe podglądy do odtworzenia i limity tworzenia głosów.
POST
/
v1
/
actions
/
voices_list
curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}'
const input = {};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_list', {
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_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"voices": [
{
"accent": "original",
"id": "clone:33333333-3333-4333-8333-333333333333",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
{
"id": "933563129e564b19a115bedd57b7406a",
"name": "Sarah",
"accent": "english",
"gender": "female",
"style": "conversational",
"previewFileName": "sarah-en.mp3",
"source": "catalog"
}
],
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
},
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
Wyświetl dostępne głosy do syntezy mowy, swoje zapisane własne głosy, niewygasłe podglądy do odtworzenia i limity tworzenia głosów.
Wymagane uprawnienia:
POST https://api.voicecheap.ai/v1/actions/voices_list
Uwierzytelnianie i uprawnienia
string
wymagane
Wyślij klucz API VoiceCheap w tym nagłówku. Obsługiwany jest również nagłówek Authorization: Bearer z tym samym kluczem API. Tokeny dostępu OAuth są
akceptowane tylko przez MCP, a nie przez ten endpoint REST.
voices:read.
Wymagana jest aktywna płatna subskrypcja. Uprawnienia nie zmieniają ról w zespole, własności zasobów, kredytów na multimedia ani limitów planu.
Parametry
Wyślij pusty obiekt JSON. Ta akcja nie ma pól wejściowych.Pełny schemat danych wejściowych
Pełny schemat danych wejściowych
Poniższy JSON Schema zachowuje dokładne nazwy pól, typy zagnieżdżone, wartości domyślne, ograniczenia i akceptowane wartości udostępniane przez mechanizm wykrywania. Dodatkowe reguły zależności między polami znajdują się w uwagach do operacji.
{
"type": "object",
"properties": {},
"additionalProperties": false
}
Przykłady żądań
Zastąp przykładowe identyfikatory zasobów i klucze multimediów wartościami zwróconymi dla Twojego konta. Przy ponawianiu tej samej operacji zmieniającej dane zachowaj identyfikator żądania.curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{}'
const input = {};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_list', {
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_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
Odpowiedź
Pierwsze pomyślne wykonanie zwraca HTTP 200 z wynikiem operacji w data. Ponowienie może zamiast tego zwrócić zapisany stan żądania. Przykład przedstawia jedną obsługiwaną odpowiedź, bez wszystkich opcjonalnych pól. Dostępne głosy TTS z katalogu i własne zapisane głosy niestandardowe, limit miejsc na zapisane głosy, aktywne niezapisane podglądy i limity tworzenia głosów.{
"data": {
"voices": [
{
"accent": "original",
"id": "clone:33333333-3333-4333-8333-333333333333",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/saved-narrator.mp3",
"source": "clone"
},
{
"id": "933563129e564b19a115bedd57b7406a",
"name": "Sarah",
"accent": "english",
"gender": "female",
"style": "conversational",
"previewFileName": "sarah-en.mp3",
"source": "catalog"
}
],
"cloneUsage": {
"canClone": true,
"limit": 10,
"remaining": 9,
"used": 1
},
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
Pola wyniku
| Pole | Opis |
|---|---|
data.voices | Własne zapisane głosy TTS, a następnie dostępne głosy katalogowe. |
data.voices[].id | Identyfikator wyboru TTS dla tts_generate; wartości niestandardowe używają clone:<UUID>. |
data.voices[].name | Wyświetlana nazwa głosu. |
data.voices[].source | catalog lub clone. |
data.voices[].accent | Akcent głosu; original w przypadku głosów niestandardowych. |
data.voices[].gender | Opcjonalna płeć głosu z katalogu. |
data.voices[].style | Opcjonalny styl wypowiedzi głosu z katalogu. |
data.voices[].previewFileName | Opcjonalna nazwa dołączonego pliku podglądu z katalogu; nie jest adresem URL pobierania. |
data.voices[].previewUrl | Opcjonalny adres URL umożliwiający odtwarzanie; adresy URL głosów niestandardowych są tymczasowe. |
data.cloneUsage.canClone | Określa, czy bieżący plan zezwala na zapisywanie niestandardowych głosów TTS; sprawdź remaining, aby poznać liczbę dostępnych miejsc. |
data.cloneUsage.limit | Limit planu dotyczący miejsc na zapisane niestandardowe głosy TTS. |
data.cloneUsage.used | Zajęte miejsca na głosy TTS, w tym miejsca zarezerwowane na tworzone głosy. |
data.cloneUsage.remaining | Dostępne miejsca na zapisane głosy TTS. |
data.voicePreviews | Wszystkie obecnie aktywne niezapisane podglądy tego konta, w tym kandydaci z wcześniejszych żądań. |
data.voicePreviews[].id | UUID v4 podglądu używany przez voices_preview_get i voices_save_preview. |
data.voicePreviews[].kind | clone lub design. |
data.voicePreviews[].name | Nazwa wyświetlana podglądu; w przypadku projektowanych kandydatów do żądanej nazwy dodawany jest numer. |
data.voicePreviews[].previewUrl | Tymczasowy adres URL audio do odtwarzania. Pobierz nowy adres URL za pomocą voices_preview_get, dopóki podgląd pozostaje aktywny. |
data.voicePreviews[].expiresAt | Czas wygaśnięcia podglądu jako znacznik czasu Unix w milisekundach. |
data.voicePreviews[].durationSeconds | Czas trwania podglądu audio w sekundach. |
data.creationUsage.cloneTrial | Limit próbnych podglądów klonu na cały okres korzystania z konta, z polami limit, used i remaining. |
data.creationUsage.design | Dzienny limit projektowania głosów z limit, used, remaining i resetsAt w milisekundach Unix. |
data.creationUsage.previewExpiresAfterHours | Okres ważności niezapisanego podglądu w godzinach, obecnie 24. |
Uwagi do operacji
- Przykładowy katalog jest skrócony. Akcja zwraca dostępną bibliotekę TTS z zapisanymi głosami niestandardowymi przed wpisami katalogowymi.
- Użyj voices[].id w tts_generate. Zapisane głosy używają clone:<UUID>; identyfikatory katalogowe są nieprzezroczyste. Te identyfikatory są odrębne od identyfikatorów z dubbing_voices_list.
- Wpisy katalogowe zawierają accent, gender, style i previewFileName; previewUrl jest opcjonalne. Zapisane wpisy niestandardowe zawierają accent: original, source: clone i tymczasowe previewUrl.
- canClone określa, czy plan obsługuje zapisywanie niestandardowych głosów TTS; remaining wskazuje wolne miejsca. Zarezerwowane operacje tworzenia mogą być wliczane do used.
- voicePreviews zawiera tylko należące do użytkownika, niezapisane, gotowe głosy kandydujące, które nie wygasły. Podgląd jest ważny przez 24 godziny; jego adres URL umożliwiający odtwarzanie może wygasnąć wcześniej.
- cloneTrial to limit jednego podglądu klonu na cały okres korzystania z konta. Płatne plany obejmują pięć żądań projektowania głosu na dzień UTC; każde udane projektowanie tworzy dwa głosy kandydujące. creationUsage podaje aktualny limit i czas resetu.
- Historia mowy i głosy niestandardowe należą do uwierzytelnionego konta. Rozliczanie w ramach zespołu nie daje dostępu do mowy ani głosów innego członka.
Wykorzystanie
Każde pomyślne wywołanie zużywa jedno wywołanie z miesięcznego limitu API/MCP. Obowiązują również kredyty na multimedia oraz limity generowania danej operacji.Błędy
| Status HTTP | Kod | Znaczenie lub sposób rozwiązania |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | Dane uwierzytelniające zostały podane w parametrze zapytania access_token lub api_key. Wysyłaj dane uwierzytelniające w nagłówkach. |
| 400 | VALIDATION_ERROR | Dane wejściowe nie odpowiadają schematowi akcji; sprawdź details, aby poznać błędy pól. |
| 401 | API_KEY_EXPIRED | Klucz API wygasł. |
| 401 | INVALID_API_KEY | Podaj prawidłowy, niewygasły klucz API. |
| 401 | INVALID_CREDENTIAL | Nagłówek Authorization ma nieprawidłowy format lub jest sprzeczny z x-api-key. |
| 401 | MISSING_CREDENTIAL | Nie podano użytecznych danych uwierzytelniających w nagłówku lub przekroczyły one 4096 znaków. |
| 401 | USER_NOT_FOUND | Konto powiązane z poświadczeniem już nie istnieje. |
| 403 | AMBIGUOUS_TEAM_API_KEY | Użytkownik, do którego należą dane uwierzytelniające, należy do więcej niż jednego zespołu, więc kontekst rozliczeniowy jest niejednoznaczny. |
| 403 | INSUFFICIENT_SCOPE | Nadaj wszystkie wymagane uprawnienia lub wybierz inne dane uwierzytelniające. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | Nie udało się zweryfikować limitów integracji konta. |
| 403 | SUBSCRIPTION_REQUIRED | Użyj aktywnej płatnej subskrypcji. |
| 403 | TEAM_OWNER_NOT_FOUND | Nie znaleziono konta faktycznego właściciela zespołu. |
| 404 | USER_NOT_FOUND | Uwierzytelnione konto już nie istnieje. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Poczekaj na odnowienie miesięcznego limitu lub zmień plan. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Jeśli występuje nagłówek Retry-After, odczekaj wskazany czas i stosuj rosnące odstępy między ponowieniami. |
| 500 | INTERNAL_ERROR | Sprawdź stan zapisanego żądania i historię zasobu przed podjęciem decyzji o ponowieniu operacji zmieniającej dane. |
| 503 | SERVER_RESTARTING | Serwer jest uruchamiany ponownie. Spróbuj ponownie wkrótce i zachowaj ten sam identyfikator żądania dla operacji zmieniającej dane. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["voices:read"]
}
}
Czy ta strona była pomocna?

