> ## 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.
# Utwórz podgląd sklonowanego głosu
> Utwórz tymczasowy podgląd klonu głosu z 1–3 należących do Ciebie przesłanych plików audio, za wyraźną zgodą. Wykorzystuje limit prób klonowania w aplikacji. Zapisz wybrany podgląd przed wygaśnięciem, aby go zachować.
Utwórz tymczasowy podgląd klonu głosu z 1–3 należących do Ciebie przesłanych plików audio, za wyraźną zgodą. Wykorzystuje limit prób klonowania w aplikacji. Zapisz wybrany podgląd przed wygaśnięciem, aby go zachować.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/voices_preview_clone
```
## Uwierzytelnianie i uprawnienia
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.
Wymagane uprawnienia: `voices:write`.
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
Opcjonalne na poziomie transportu: jeśli identyfikator zostanie pominięty, serwer doda go przed walidacją. Podaj własny, stały UUID v4, aby bezpiecznie odzyskać wynik po utracie odpowiedzi.
Format: "uuid". Wzorzec: `^[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}$`.
Wartość tekstowa.
Minimalna długość: 1. Maksymalna długość: 80.
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.
Minimalna liczba elementów: 1. Maksymalna liczba elementów: 3.
Potwierdź, że masz zgodę na sklonowanie głosu osoby, której głos znajduje się w każdej próbce.
Wymagana wartość: true.
Wartość logiczna.
Wartość domyślna: false.
Wartość tekstowa.
Maksymalna długość: 35. Wzorzec: `^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$`.
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.
```json theme={null}
{
"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}$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"samples": {
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"type": "object",
"properties": {
"fileKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "An uploaded audio fileKey returned by voices_upload_complete for this account."
}
},
"required": ["fileKey"],
"additionalProperties": false
}
},
"hasPermission": {
"type": "boolean",
"const": true,
"description": "Confirm that you have permission to clone the person whose voice is in every sample."
},
"trimToMaxDuration": {
"default": false,
"type": "boolean"
},
"language": {
"type": "string",
"maxLength": 35,
"pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$"
}
},
"required": ["name", "samples", "hasPermission"],
"additionalProperties": false
}
```
## Idempotencja
Dla każdej operacji zmieniającej dane użyj UUID v4 w requestId lub w nagłówku HTTP Idempotency-Key. Po awarii sieci użyj ponownie tego samego identyfikatora i identycznych argumentów. Jeśli podasz oba, muszą być zgodne. Ponowienie zapisanego żądania nie powtarza operacji ani nie zużywa kolejnego wywołania z miesięcznego limitu. Żądania zakończone błędem lub przerwane nie są automatycznie uruchamiane ponownie.
Każda operacja zmieniająca dane może zwrócić HTTP 202, gdy ponowienie napotka to samo żądanie nadal w stanie running, nawet jeśli jej pierwsze wykonanie zwykle jest synchroniczne. Jeśli wykonanie się zakończyło, ale resultStored ma wartość false, ponowienie zwraca HTTP 200 z zapisanym stanem żądania zamiast pierwotnego wyniku. Pobierz wynik za pomocą akcji historii, wyniku lub pobierania właściwej dla danej domeny.
## 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.
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_preview_clone' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","name":"Studio narrator","samples":[{"fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}],"hasPermission":true,"trimToMaxDuration":false,"language":"en"}'
```
```javascript JavaScript theme={null}
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
name: 'Studio narrator',
samples: [
{
fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav',
},
],
hasPermission: true,
trimToMaxDuration: false,
language: 'en',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_preview_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/voices_preview_clone",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "name": "Studio narrator", "samples": [{"fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}], "hasPermission": True, "trimToMaxDuration": False, "language": "en"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## Odpowiedź
Ta operacja zwraca HTTP 202 podczas przetwarzania. Zapisz requestId i odpytuj action\_request\_get, podając ten identyfikator oraz nazwę pierwotnej operacji. Stany odpytywania to running, completed, failed i interrupted. Zakończony wynik może wskazywać osobne zadanie przetwarzania multimediów; kontynuuj za pomocą akcji stanu lub wyniku właściwej dla tej operacji.
Wszystkie aktywne niezapisane podglądy głosów i zaktualizowane limity tworzenia, w tym nowy głos kandydujący utworzony przez klonowanie.
```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": {
"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
}
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_preview_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": "voices_preview_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"
}
```
## Pola wyniku
| Pole | Opis |
| - | - |
| `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. |
## Odzyskaj żądanie i sprawdź jego stan
Używaj tego samego identyfikatora także po utracie połączenia. Jeśli resultStored ma wartość false, pobierz wynik za pomocą odpowiedniej akcji historii, wyniku lub pobierania. Nigdy nie uruchamiaj drugiego generowania tylko po to, aby sprawdzić postęp.
```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":"voices_preview_clone"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_preview_clone",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"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
}
}
}
}
```
## Uwagi do operacji
* Użyj requestId w formacie UUID v4 dla tej mutacji i używaj go ponownie z identycznymi argumentami przy ponawianiu żądania. Długotrwałe akcje najpierw zwracają żądanie w stanie running; ten przykład przedstawia ukończony wynik procedury obsługi dostępny przez action\_request\_get.
* Prześlij 1–3 własne próbki audio i użyj ich wartości fileKey po ukończeniu przesyłania. Obsługiwane formaty próbek to MP3, WAV, M4A, OGG i Opus; każdy plik musi być niepusty i mieć rozmiar najwyżej 20 MiB (20,971,520 bajtów). Zdalne adresy URL i pliki przesłane przez inne konta są odrzucane.
* Próbki muszą łącznie zawierać co najmniej 10 sekund i co najwyżej 120 sekund możliwego do odczytania audio. trimToMaxDuration ma domyślną wartość false; ustaw true, aby proporcjonalnie przyciąć próbki o łącznym czasie przekraczającym 120 sekund.
* hasPermission musi mieć wartość logiczną JSON true, potwierdzającą zgodę dla każdej próbki. Wartość tekstowa taka jak "true" jest odrzucana.
* name musi zawierać 1–80 znaków po usunięciu skrajnych białych znaków. Opcjonalne language akceptuje kod złożony z 2–3 liter z opcjonalnymi podtagami, o maksymalnej długości 35 znaków.
* Wykorzystuje jednorazową próbę podglądu klonowania dostępną przez cały okres istnienia konta. Utworzenie tego podglądu nie zapisuje głosu TTS wielokrotnego użytku ani nie zajmuje miejsca na zapisany głos.
* Nowy kandydat klonowania ma kind: clone i jest dostępny przez 24 godziny. Jego odtwarzanie jest ograniczone do około 10 sekund.
* Odpowiedź zawiera wszystkie aktywne niezapisane podglądy. Użyj voices\_preview\_get, aby odświeżyć odtwarzanie, a następnie voices\_save\_preview, aby zachować wybranego kandydata w płatnym planie.
* language wybiera skrypt podglądu, jeśli istnieje obsługiwany skrypt; nie jest żądaniem przetłumaczenia przesłanej próbki.
* 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 | `IDEMPOTENCY_CONFLICT` | Nagłówek Idempotency-Key i pole requestId w treści żądania muszą być zgodne. |
| 400 | `INVALID_REQUEST_ID` | Podaj requestId lub Idempotency-Key w formacie UUID v4. |
| 400 | `VALIDATION_ERROR` | Dane wejściowe nie odpowiadają schematowi akcji; sprawdź details, aby poznać błędy pól. |
| 400 | `VOICE_CLONE_INVALID_AUDIO` | Przesłana próbka nie ma możliwego do odczytania dodatniego czasu trwania audio. |
| 400 | `VOICE_CLONE_INVALID_FILE_SIZE` | Zapisana próbka jest pusta lub przekracza 20 MiB. |
| 400 | `VOICE_CLONE_INVALID_FILE_TYPE` | Próbka nie jest plikiem audio MP3, WAV, M4A, OGG ani Opus. |
| 400 | `VOICE_CLONE_SAMPLE_TOO_LONG` | Łączny czas próbek przekracza 120 sekund, a przycinanie nie zostało włączone. |
| 400 | `VOICE_CLONE_SAMPLE_TOO_SHORT` | Łączny czas nagrań próbek wynosi mniej niż 10 sekund. |
| 400 | `VOICE_SAMPLE_NOT_OWNED` | Klucz próbki jest niebezpieczny lub nie należy do uwierzytelnionego konta. |
| 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 | `ACCOUNT_UNAVAILABLE` | Konto wykonujące operację lub konto rozliczeniowe jest niedostępne albo jest w trakcie usuwania. |
| 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. |
| 404 | `VOICE_PREVIEW_NOT_FOUND` | Żądanie należy do innego konta. |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Na tym koncie działa już 10 akcji integracji. Sprawdzaj stan istniejącego żądania przed rozpoczęciem kolejnego. |
| 409 | `IDEMPOTENCY_CONFLICT` | Używaj ponownie identyfikatora wyłącznie z tą samą operacją i tymi samymi argumentami. |
| 409 | `VOICE_CREATION_IN_PROGRESS` | Podgląd jest nadal tworzony lub usuwanie konta blokuje nowe operacje dotyczące głosów. |
| 409 | `VOICE_CREATION_REQUEST_MISMATCH` | Ten requestId został użyty dla innego rodzaju głosu, innych ustawień lub innych próbek. |
| 409 | `VOICE_TRIAL_LIMIT_REACHED` | Konto wykorzystało już jednorazową próbę podglądu klonowania. |
| 410 | `VOICE_PREVIEW_EXPIRED` | Podgląd głosu tego żądania wygasł lub nie jest już dostępny. |
| 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. |
| 502 | `INTERNAL_ERROR` | Nie udało się ukończyć akcji lub potwierdzić jej wyniku. Sprawdź stan żądania i historię zasobu przed rozpoczęciem kolejnego generowania. |
| 503 | `ACTION_RESULT_UNAVAILABLE` | Akcja została wykonana, ale nie udało się zapisać jej wyniku. Sprawdź zapisany stan żądania i historię zasobu przed rozpoczęciem nowego generowania. |
| 503 | `SERVER_RESTARTING` | Serwer jest uruchamiany ponownie. Spróbuj ponownie wkrótce i zachowaj ten sam identyfikator żądania dla operacji zmieniającej dane. |
```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.