Skip to main content
POST
Sklonuj i zapisz własny głos z 1–3 należących do Ciebie przesłanych plików audio. Wymagana jest wyraźna zgoda. Próbki muszą trwać łącznie 10–120 sekund, a każda może mieć najwyżej 20 MB. Obowiązują limity głosów w planie.

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

string
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}$.
string
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 80.
array
wymagane
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Minimalna liczba elementów: 1. Maksymalna liczba elementów: 3.
boolean
wymagane
Potwierdź, że masz zgodę na sklonowanie głosu osoby, której głos znajduje się w każdej próbce.Wymagana wartość: true.
boolean
Wartość logiczna.Wartość domyślna: false.
string
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.

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.

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. Zapisany niestandardowy głos TTS do ponownego użycia i zaktualizowany limit miejsc na zapisane głosy.

Pola wyniku

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

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.
  • Ta akcja bezpośrednio zapisuje sklonowany głos i zajmuje miejsce na zapisany głos TTS. Nie zużywa jednorazowej próby podglądu klonu.
  • Użyj zwróconego voice.id w tts_generate. Przy bezpośrednim klonowaniu jego UUID to requestId; voices_delete przyjmuje ten UUID bez prefiksu clone:.
  • Akceptowane pole language nie zmienia procesu klonowania z bezpośrednim zapisem. Wybierz voices_preview_clone, gdy potrzebujesz skryptu podglądu dla określonego języka.
  • 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