> ## 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. # Sklonuj głos dubbingowy > Utwórz zapisany własny głos do dubbingu wideo z należącej do Ciebie przesłanej próbki audio, za wyraźną zgodą. Obowiązuje limit własnych głosów w aplikacji; wynik zawiera przykład audio. Używaj ponownie requestId, aby uniknąć utworzenia duplikatu. Utwórz zapisany własny głos do dubbingu wideo z należącej do Ciebie przesłanej próbki audio, za wyraźną zgodą. Obowiązuje limit własnych głosów w aplikacji; wynik zawiera przykład audio. Używaj ponownie requestId, aby uniknąć utworzenia duplikatu. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/dubbing_voices_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. Wartość tekstowa. Minimalna długość: 1. Maksymalna długość: 1024. Wartość logiczna. Wymagana wartość: true. 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": { "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}$", "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "fileKey": { "type": "string", "minLength": 1, "maxLength": 1024 }, "hasPermission": { "type": "boolean", "const": true } }, "required": ["name", "fileKey", "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/dubbing_voices_clone' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","name":"Studio narrator","fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav","hasPermission":true}' ``` ```javascript JavaScript theme={null} const input = { requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91', name: 'Studio narrator', fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav', hasPermission: true, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/dubbing_voices_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/dubbing_voices_clone", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "name": "Studio narrator", "fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav", "hasPermission": True}, 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. Zapisany własny głos dubbingowy, w tym jego identyfikator, nazwa i opcjonalna próbka audio. Nie ma opakowania voice ani cloneUsage w stylu TTS. ```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": { "id": "dubbing_voice_R8q3k9Yp", "name": "Studio narrator", "audioExampleUrl": "https://files.example.com/dubbing-narrator.mp3" }, "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_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": "dubbing_voices_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.id` | Nieprzezroczysty identyfikator zapisanego głosu dubbingowego. | | `data.name` | Nazwa wyświetlana zapisanego głosu. | | `data.audioExampleUrl` | Opcjonalny adres URL przykładowego audio do odtworzenia. Odpowiedzi akcji wyświetlania listy i pobierania udostępniają go jako previewUrl. | ## 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":"dubbing_voices_clone"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "operation": "dubbing_voices_clone", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "id": "dubbing_voice_R8q3k9Yp", "name": "Studio narrator", "audioExampleUrl": "https://files.example.com/dubbing-narrator.mp3" } } } ``` ## 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. * Ta akcja akceptuje jeden własny ukończony przesłany plik audio i wymaga hasPermission: true jako wartości logicznej JSON. Nie akceptuje zdalnego adresu URL ani fileKey innego konta. * Obsługiwane rozszerzenia próbek to AAC, AC3, EAC3, FLAC, M4A, X-M4A, MP2, MP3, OGG i WAV. Plik musi być niepustym, możliwym do odczytania audio mieszczącym się w limicie przesyłania planu i mieć najwyżej 250,000,000 bajtów (250 MB). * Dedykowana rodzina voices*upload*\* jest bardziej restrykcyjna: MP3, WAV, M4A, OGG lub Opus i najwyżej 20 MiB na przesłanie. Plik przyjęty przez tę rodzinę przesyłania nadal musi odpowiadać obsługiwanym typom próbek tej akcji dubbingu; Opus nie jest tutaj obsługiwany. * name zawiera 1–80 znaków po usunięciu skrajnych białych znaków i nie może zawierać znaków sterujących. * Reguła łącznego czasu próbek 10–120 sekund dla klonowania głosu TTS nie dotyczy tej akcji. Jej próbka musi mieć możliwy do odczytania dodatni czas trwania i nie może przekraczać 45 minut; audio nie jest automatycznie przycinane do tego limitu. * Korzysta z limitu miejsc na zapisane własne głosy dubbingowe na koncie. Wywołaj dubbing\_voices\_list, aby uzyskać zaktualizowane cloneUsage; sam wynik klonowania go nie zawiera. * Użyj zwróconego nieprzezroczystego id do dubbingu. Nie ma on prefiksu clone: i nie można go użyć do wyboru głosu TTS. * 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 | `BAD_REQUEST` | Próbka nie ma możliwego do odczytania dodatniego czasu trwania, przekracza limit 45 minut dla klonowania głosu do dubbingu lub została odrzucona jako zbyt długa. | | 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_NAME_INVALID` | Nazwa jest pusta, zbyt długa lub zawiera znak sterujący. | | 400 | `VOICE_SAMPLE_INVALID_SIZE` | Próbka jest pusta, jej rzeczywiste bajty nie odpowiadają zadeklarowanemu rozmiarowi lub przekracza limit bieżącego planu albo 250 MB. | | 400 | `VOICE_SAMPLE_INVALID_TYPE` | Nazwa pliku próbki nie wskazuje obsługiwanego formatu audio do dubbingu. | | 400 | `VOICE_SAMPLE_NOT_OWNED` | Przesłana próbka jest niebezpieczna 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. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Na tym koncie działa już 10 akcji integracji. Sprawdzaj stan istniejącego żądania przed rozpoczęciem kolejnego. | | 409 | `DUBBING_VOICE_LIMIT_REACHED` | Wszystkie miejsca na zapisane niestandardowe głosy do dubbingu są zajęte. | | 409 | `IDEMPOTENCY_CONFLICT` | Ten requestId został już użyty z innymi danymi wejściowymi głosu dubbingowego. | | 409 | `VOICE_MUTATION_IN_PROGRESS` | Dla tego konta trwa inna mutacja głosu do dubbingu. | | 409 | `VOICE_MUTATION_LEASE_LOST` | Mutacja utraciła rezerwację wykonania. Przed ponowieniem sprawdź stan żądania i zapisane głosy. | | 409 | `VOICE_REQUEST_ALREADY_STARTED` | To żądanie dotyczące głosu zostało wcześniej rozpoczęte, ale nie ma potwierdzonego wyniku końcowego. Pobierz listę głosów i sprawdź stan żądania przed rozpoczęciem kolejnego. | | 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` | Nie udało się ukończyć akcji dotyczącej głosu. Sprawdź stan żądania i zapisane głosy przed rozpoczęciem nowej operacji modyfikującej. | | 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.