> ## 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. # Rozpocznij tłumaczenie > Prześlij plik wideo lub audio i rozpocznij nowy projekt tłumaczenia # Rozpocznij tłumaczenie Utwórz nowy projekt tłumaczenia, przesyłając plik wideo lub audio. Proces tłumaczenia przebiega asynchronicznie w tle. Użyj [punkt końcowy statusu](/docs/pl/api-reference/translation-status), aby śledzić postępy i pobierać wyniki. Użyj [Pobierz szczegóły projektu](/docs/pl/api-reference/project-details), gdy potrzebujesz historii przetłumaczonych wersji lub historii synchronizacji ruchu ust. ## Limit współbieżności Możesz uruchomić do 10 tłumaczeń jednocześnie na konto. Jeśli 10 tłumaczeń jest już w toku, nowe żądania zwrócą `CONCURRENT_TRANSLATION_LIMIT_REACHED` (HTTP 429). ## Żądanie Ten punkt końcowy akceptuje `multipart/form-data` z przesłaniem pliku. ### Nagłówki Twój klucz API VoiceCheap. Pobierz go z [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api). ### Parametry treści Plik wideo lub audio do przetłumaczenia. **Obsługiwane formaty wideo:** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg` **Obsługiwane formaty audio:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm` **Maksymalny rozmiar pliku według planu:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB oraz Enterprise 60 GB. Język, na który ma zostać przetłumaczona treść. Musi być zapisany małymi literami. **Dozwolone wartości (70+):** `afrikaans`, `albanian`, `amharic`, `arabic`, `armenian`, `assamese`, `azerbaijani`, `basque`, `belarusian`, `bengali`, `bosnian`, `bulgarian`, `catalan`, `croatian`, `czech`, `danish`, `dutch`, `english`, `british english`, `estonian`, `finnish`, `french`, `french canadian`, `galician`, `german`, `greek`, `gujarati`, `hebrew`, `hindi`, `hungarian`, `icelandic`, `indonesian`, `irish`, `italian`, `japanese`, `kannada`, `kazakh`, `khmer`, `korean`, `lao`, `latvian`, `lithuanian`, `macedonian`, `malay`, `malayalam`, `mandarin`, `marathi`, `mongolian`, `nepali`, `norwegian`, `persian`, `polish`, `portuguese`, `brazilian portuguese`, `punjabi`, `romanian`, `russian`, `serbian`, `slovak`, `slovenian`, `spanish`, `swahili`, `swedish`, `tagalog`, `tamil`, `telugu`, `thai`, `turkish`, `ukrainian`, `urdu`, `vietnamese`, `welsh`, `yoruba`, `zulu` Język źródłowy treści przy użyciu kodów językowych ISO (np. `en`, `es`, `fr`, `de`, `ja`, `zh`). **Zdecydowanie zalecane: Pozostaw to pole puste w celu automatycznego wykrywania.** Podaj ten parametr tylko wtedy, gdy masz 100% pewności, że kod języka jest poprawny i zgodny z formatem ISO. Nieprawidłowe kody języków spowodują błędy transkrypcji. Nasze automatyczne wykrywanie obsługuje ponad 80 języków i jest wysoce dokładne. **Domyślnie:** `auto-detect` Niestandardowa nazwa projektu. Przydatna do identyfikacji projektów w Twoim panelu. **Domyślnie:** Jeśli nie zostanie podana, użyty zostanie identyfikator projektu. Punkt końcowy https, który odbiera [zdarzenia webhook](/docs/pl/api-reference/webhooks) dla tego projektu, zastępując punkt końcowy skonfigurowany na Twoim koncie. **Domyślnie:** Punkt końcowy webhook konta, jeśli został skonfigurowany. `auto-detect` lub liczba całkowita od `1` do `32`. Znana liczba mówców może poprawić diaryzację. **Domyślnie:** `auto-detect` Tablica ciągów JSON zawierająca specyficzne dla żądania nazwy, marki, akronimy lub terminy specjalistyczne. Terminy te są łączone z zapisanym glosariuszem konta lub zespołu. Usuń typowe słowa wypełniacze z transkrypcji źródłowej przed tłumaczeniem. **Domyślnie:** `true` Istniejąca transkrypcja SRT w języku źródłowym. `originalLanguage` musi być jawnie określone, gdy podano to pole. Czy zachować dźwięk w tle w danych wyjściowych. Po włączeniu zachowuje muzykę w tle, otoczenie, śmiech, oklaski i dźwięki tłumu, usuwając jednocześnie tylko oryginalny głos (separacja ścieżek). Wyłącz, jeśli źródło nie zawiera dźwięku w tle. **Domyślnie:** `true` Zachowaj oryginalnego mówcę cicho pod przetłumaczonym głosem. **Domyślnie:** `false` Głośność oryginalnego głosu od `1` do `70`, gdy włączona jest opcja `keepOriginalVoice`. **Domyślnie:** `30` Tryb izolacji głosu, gdy włączona jest opcja `keepBackgroundMusic`. Kontroluje jakość i charakterystykę separacji głosu. Nasze domyślne przetwarzanie głosu, zaprojektowane z myślą o profesjonalnej jakości dźwięku: * Usuwa echa i pogłosy * Czyści niedoskonałości techniczne * Generuje czysty i wyraźny głos **Zalecane dla:** Większości projektów, w których jakość dźwięku jest najważniejsza. Idealne do samouczków, treści edukacyjnych, filmów marketingowych i wszelkich treści wymagających optymalnej czystości głosu. Zachowuje naturalne cechy środowiska nagrania: * Utrzymuje dźwięk zbliżony do oryginalnego nagrania * Zachowuje charakterystykę środowiskową **Zalecane dla:** Treści, w których autentyczność otoczenia jest ważna, takich jak vlogi plenerowe, filmy dokumentalne lub treści, w których atmosfera dźwiękowa jest integralną częścią doświadczenia. Ta opcja może w niektórych przypadkach powodować artefakty lub nieoczekiwane efekty ze względu na zachowanie elementów tła. **Dozwolone wartości:** `studio`, `realistic` **Domyślnie:** `studio` Czy generować napisy dla przetłumaczonego wideo. Po włączeniu dodaje czyste napisy w stylu Netflixa (czarno-białe). Użyj `subtitlesSource`, aby wybrać tekst oryginalny (język źródłowy) lub przetłumaczony (język docelowy). Napisy są automatycznie synchronizowane dla optymalnej czytelności. **Uwaga:** Napisy wtopione wymagają FFmpeg z filtrem `subtitles` (libass). Jeśli jest niedostępny, API zamiast twardego wypalenia stylu osadzi ścieżkę napisów. **Domyślnie:** `false` Wybierz źródło tekstu napisów, gdy włączona jest opcja `subtitles`. **Dozwolone wartości:** `translated`, `original` **Domyślnie:** `translated` **Uwaga:** Jeśli wybrano `original`, ale oryginalna transkrypcja jest niedostępna, napisy zostaną zastąpione przez `translated`. Uruchom przetwarzanie synchronizacji ruchu ust po zakończeniu tłumaczenia. * `standard` = Lip Sync * `pro` = Lip Sync Pro * `studio` = Lip Sync Studio Tryby premium wymagają spełnienia standardowych wymogów dotyczących planu, czasu trwania i kredytów. **Domyślnie:** pomiń pole, aby pominąć synchronizację ruchu ust. Włącz wykrywanie aktywnego mówcy dla żądanego procesu synchronizacji ruchu ust. **Domyślnie:** `false` Starszy selektor synchronizacji ruchu ust zachowany dla kompatybilności wstecznej. * `false` = Standardowa synchronizacja ruchu ust (**4 minuty kredytów na 1 minutę wideo**) * `true` = Lip Sync Pro (**9 minut kredytów na 1 minutę wideo**) Lip Sync Pro jest dostępna począwszy od planu Creator. **Maksymalny czas trwania:** 30 minut na wideo. **Opóźnienie:** Przetwarzanie synchronizacji ruchu ust zazwyczaj dodaje **2x-4x** czasu trwania oryginalnego wideo. E-maile o zakończeniu lub błędzie synchronizacji ruchu ust nie są wysyłane dla żądań wyzwalanych przez API. Użyj [punkt końcowy statusu](/docs/pl/api-reference/translation-status), aby śledzić postępy. **Domyślnie:** niewłączone (pomiń pole, aby pominąć synchronizację ruchu ust) **Form-data:** Wysyłaj wartości logiczne jako ciągi znaków `true` lub `false` (np. `-F "lipsyncPro=false"`). Nie łącz `lipsyncPro` z wykluczającym się `lipSyncMode`. Strategia głosowa: `cloning` lub `custom`. **Domyślnie:** `cloning` Wymagane, gdy `voiceMode` to `custom`. Głos musi należeć do faktycznego właściciela projektu. Dowolne lub nieprzypisane identyfikatory głosów są odrzucane. Dostosuj parametry klonowania głosu, aby uzyskać zaawansowaną kontrolę nad generowanym głosem. Przekaż jako ciąg JSON podczas używania form-data. Wszystkie wartości muszą mieścić się w zakresie od 0 do 1 (z krokiem 0,01). Te ustawienia mają zastosowanie tylko wtedy, gdy `voiceMode` to `cloning`. **Stabilność głosu (0,00 - 1,00)** Określa, jak stabilny jest głos i jaka jest losowość między poszczególnymi generacjami. * **Niższe wartości** pozwalają na szerszy zakres emocjonalny, ale mogą powodować dziwną lub przyspieszoną mowę * **Wyższe wartości** dają bardziej spójny wynik, ale mogą brzmieć monotonnie **Domyślnie:** `0.60` **Wskazówka:** Aby uniknąć odtwarzania akcentu, użyj `0.80` **Podobieństwo głosu (0,00 - 1,00)** Kontroluje, jak ściśle AI trzyma się oryginalnego głosu. * **Wyższe wartości** sprawiają, że sklonowany głos jest bardziej podobny do oryginału * Jeśli oryginalny dźwięk jest zaszumiony, a podobieństwo jest zbyt wysokie, artefakty lub szum w tle mogą przenieść się do wygenerowanego głosu **Domyślnie:** `0.85` **Wskazówka:** Aby uniknąć odtwarzania akcentu, użyj `0.20` **Wzmocnienie mówcy (0,00 - 1,00)** Zwiększa podobieństwo do oryginalnego mówcy. Jest to subtelne ulepszenie, które zwiększa podobieństwo do źródłowego głosu. **Uwaga:** Wyższe wartości zwiększają czas obliczeń i opóźnienie. **Domyślnie:** `0.60` **Wskazówka:** Aby uniknąć odtwarzania akcentu, użyj `0.00` **Wartości domyślne (zrównoważone):** ```json theme={null} { "stability": 0.6, "similarity": 0.85, "speakerBoost": 0.6 } ``` **Zalecane w celu uniknięcia odtwarzania akcentu:** ```json theme={null} { "stability": 0.8, "similarity": 0.2, "speakerBoost": 0.0 } ``` Tablica JSON zawierająca zakresy czasowe źródła, które powinny pozostać w oryginalnym języku. ```json theme={null} [ { "startTime": 10.2, "endTime": 12.8 } ] ``` Pominięcia czasowe wymagają wejścia wideo i `keepBackgroundMusic=true`. Nie można ich łączyć z `keepOriginalVoice` i nie mogą nakładać się na segmenty transkrypcji. ## Odpowiedź Zawsze `true` dla udanych żądań Czytelny dla człowieka komunikat opisujący wynik Unikalny identyfikator utworzonego projektu tłumaczenia. Użyj tego identyfikatora, aby sprawdzić status. Przybliżony szacowany czas przetwarzania w minutach. Obecny szacunek to pięć minut przetwarzania na każdą rozpoczętą minutę mediów źródłowych. ## Przykłady Zapisane reguły glosariusz oraz niestandardowe instrukcje tłumaczenia z aktywnego konta lub zespołu są stosowane automatycznie. ```bash cURL theme={null} curl -X POST https://api.voicecheap.ai/v1/translate \ -H "x-api-key: vc_your-api-key" \ -F "file=@video.mp4" \ -F "targetLanguage=spanish" \ -F "projectName=My Spanish Translation" \ -F "numberOfSpeakers=2" \ -F 'brandVocabulary=["VoiceCheap","SmartSync"]' \ -F "removeFillerWords=true" \ -F "keepBackgroundMusic=true" \ -F "keepOriginalVoice=false" \ -F "voiceIsolatorOption=studio" \ -F "subtitles=true" \ -F "subtitlesSource=translated" \ -F "lipSyncMode=standard" \ -F "activeSpeakerDetectionEnabled=true" ``` ```typescript TypeScript theme={null} interface StartTranslationResponse { success: boolean; message: string; projectId: string; estimatedDuration: number; } interface VoiceCloningSettings { stability: number; // 0.00 - 1.00 similarity: number; // 0.00 - 1.00 speakerBoost: number; // 0.00 - 1.00 } interface StartTranslationRequest { targetLanguage: string; originalLanguage?: string; projectName?: string; numberOfSpeakers?: 'auto-detect' | string; brandVocabulary?: string[]; removeFillerWords?: boolean; keepBackgroundMusic?: boolean; keepOriginalVoice?: boolean; originalVoiceVolume?: number; voiceMode?: 'cloning' | 'custom'; voiceId?: string; voiceIsolatorOption?: 'studio' | 'realistic'; subtitles?: boolean; subtitlesSource?: 'translated' | 'original'; lipSyncMode?: 'standard' | 'pro' | 'studio'; activeSpeakerDetectionEnabled?: boolean; voiceCloningSettings?: VoiceCloningSettings; translationTimeSkips?: Array<{ startTime: number; endTime: number }>; } async function startTranslation( file: File, targetLanguage: string, options?: { originalLanguage?: string; projectName?: string; numberOfSpeakers?: 'auto-detect' | string; brandVocabulary?: string[]; removeFillerWords?: boolean; keepBackgroundMusic?: boolean; keepOriginalVoice?: boolean; originalVoiceVolume?: number; voiceMode?: 'cloning' | 'custom'; voiceId?: string; voiceIsolatorOption?: 'studio' | 'realistic'; subtitles?: boolean; subtitlesSource?: 'translated' | 'original'; lipSyncMode?: 'standard' | 'pro' | 'studio'; activeSpeakerDetectionEnabled?: boolean; voiceCloningSettings?: VoiceCloningSettings; translationTimeSkips?: Array<{ startTime: number; endTime: number }>; }, ): Promise { const formData = new FormData(); formData.append('file', file); formData.append('targetLanguage', targetLanguage); if (options?.projectName) { formData.append('projectName', options.projectName); } if (options?.originalLanguage) { formData.append('originalLanguage', options.originalLanguage); } if (options?.numberOfSpeakers) { formData.append('numberOfSpeakers', options.numberOfSpeakers); } if (options?.brandVocabulary) { formData.append('brandVocabulary', JSON.stringify(options.brandVocabulary)); } if (options?.removeFillerWords !== undefined) { formData.append('removeFillerWords', String(options.removeFillerWords)); } if (options?.keepBackgroundMusic !== undefined) { formData.append('keepBackgroundMusic', String(options.keepBackgroundMusic)); } if (options?.keepOriginalVoice !== undefined) { formData.append('keepOriginalVoice', String(options.keepOriginalVoice)); } if (options?.originalVoiceVolume !== undefined) { formData.append('originalVoiceVolume', String(options.originalVoiceVolume)); } if (options?.voiceMode) { formData.append('voiceMode', options.voiceMode); } if (options?.voiceId) { formData.append('voiceId', options.voiceId); } if (options?.voiceIsolatorOption) { formData.append('voiceIsolatorOption', options.voiceIsolatorOption); } if (options?.subtitles !== undefined) { formData.append('subtitles', String(options.subtitles)); } if (options?.subtitlesSource) { formData.append('subtitlesSource', options.subtitlesSource); } if (options?.lipSyncMode) { formData.append('lipSyncMode', options.lipSyncMode); } if (options?.activeSpeakerDetectionEnabled !== undefined) { formData.append('activeSpeakerDetectionEnabled', String(options.activeSpeakerDetectionEnabled)); } if (options?.voiceCloningSettings) { formData.append('voiceCloningSettings', JSON.stringify(options.voiceCloningSettings)); } if (options?.translationTimeSkips) { formData.append('translationTimeSkips', JSON.stringify(options.translationTimeSkips)); } const response = await fetch('https://api.voicecheap.ai/v1/translate', { method: 'POST', headers: { 'x-api-key': 'vc_your-api-key', }, body: formData, }); if (!response.ok) { const error = await response.json(); throw new Error(error.message || 'Translation failed'); } return response.json(); } // Usage example const file = document.querySelector('#fileInput')?.files?.[0]; if (file) { const result = await startTranslation(file, 'spanish', { projectName: 'My Spanish Translation', keepBackgroundMusic: true, voiceIsolatorOption: 'studio', subtitles: true, subtitlesSource: 'translated', voiceCloningSettings: { stability: 0.6, similarity: 0.85, speakerBoost: 0.6, }, }); console.log('Project ID:', result.projectId); } ``` ```javascript JavaScript theme={null} const formData = new FormData(); formData.append('file', videoFile); formData.append('targetLanguage', 'spanish'); formData.append('projectName', 'My Spanish Translation'); formData.append('keepBackgroundMusic', 'true'); formData.append('voiceIsolatorOption', 'studio'); formData.append('subtitles', 'true'); formData.append('subtitlesSource', 'translated'); formData.append( 'voiceCloningSettings', JSON.stringify({ stability: 0.6, similarity: 0.85, speakerBoost: 0.6, }), ); const response = await fetch('https://api.voicecheap.ai/v1/translate', { method: 'POST', headers: { 'x-api-key': 'vc_your-api-key', }, body: formData, }); const data = await response.json(); console.log('Project ID:', data.projectId); ``` ```python Python theme={null} import requests import json files = {'file': open('video.mp4', 'rb')} data = { 'targetLanguage': 'spanish', 'projectName': 'My Spanish Translation', 'keepBackgroundMusic': 'true', 'voiceIsolatorOption': 'studio', 'subtitles': 'true', 'subtitlesSource': 'translated', 'voiceCloningSettings': json.dumps({ 'stability': 0.60, 'similarity': 0.85, 'speakerBoost': 0.60 }) } headers = {'x-api-key': 'vc_your-api-key'} response = requests.post( 'https://api.voicecheap.ai/v1/translate', headers=headers, files=files, data=data ) result = response.json() print(f"Project ID: {result['projectId']}") ``` ```php PHP theme={null} 0.60, 'similarity' => 0.85, 'speakerBoost' => 0.60 ]); $postFields = [ 'file' => new CURLFile('video.mp4'), 'targetLanguage' => 'spanish', 'projectName' => 'My Spanish Translation', 'keepBackgroundMusic' => 'true', 'voiceIsolatorOption' => 'studio', 'subtitles' => 'true', 'subtitlesSource' => 'translated', 'voiceCloningSettings' => $voiceCloningSettings ]; curl_setopt_array($curl, [ CURLOPT_URL => 'https://api.voicecheap.ai/v1/translate', CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $postFields, CURLOPT_HTTPHEADER => [ 'x-api-key: vc_your-api-key' ] ]); $response = curl_exec($curl); $result = json_decode($response, true); echo "Project ID: " . $result['projectId']; ``` ## Przykład odpowiedzi ```json theme={null} { "success": true, "message": "Translation started successfully. Use the status endpoint to track progress.", "projectId": "abc123-def456-ghi789", "estimatedDuration": 15 } ``` ## Błędy | Status | Kod | Opis | | ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------- | | 400 | `FILE_REQUIRED` | Nie przesłano żadnego pliku wraz z żądaniem | | 400 | `INVALID_FILE_TYPE` | Przesłany typ pliku nie jest obsługiwany | | 400 | `DURATION_DETECTION_FAILED` | Nie udało się wykryć czasu trwania przesłanego pliku | | 400 | `INVALID_MULTIPART_REQUEST` | Dane formularza wieloczęściowego są błędne lub przekraczają limity pól | | 400 | `INVALID_BOOLEAN_VALUE` | Parametr logiczny ma nieprawidłową wartość (użyj "true" lub "false") | | 400 | `INVALID_JSON_FORMAT` | JSON ustawień klonowanie głosu jest błędny | | 400 | `INVALID_BRAND_VOCABULARY` | Wpis słownikowy specyficzny dla żądania jest nieprawidłowy | | 400 | `INVALID_SOURCE_SRT` | Dostarczony plik SRT źródłowy jest błędny | | 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt wymaga jawnego określenia originalLanguage | | 400 | `VOICE_ID_REQUIRED` | Wybrano tryb niestandardowe głosy bez identyfikatora głosu | | 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | Identyfikator głosu został połączony z klonowanie głosu | | 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Ustawienia klonowania zostały połączone z trybem niestandardowe głosy | | 400 | `CONFLICTING_LIPSYNC_OPTIONS` | lipSyncMode jest w konflikcie z przestarzałym lipsyncPro | | 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Pominięcia czasu są w konflikcie z inną opcją audio | | 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Pominięcia czasu wymagają dźwięk w tle | | 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Pominięcie czasu wykracza poza czas trwania mediów | | 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Pominięcie czasu nakłada się na segment transkrypcji | | 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Zażądano wtopione napisy dla wejścia audio | | 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | Zażądano synchronizacja ruchu ust dla wejścia audio | | 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Zażądano pominięcia czasu dla wejścia audio | | 400 | `LIPSYNC_VIDEO_TOO_LONG` | Zażądano synchronizacja ruchu ust dla mediów dłuższych niż obsługiwany czas trwania | | 413 | `FILE_TOO_LARGE` | Przesłany plik przekracza limit planu użytkownika | | 401 | `MISSING_API_KEY` | Wymagany jest klucz API | | 401 | `INVALID_API_KEY_FORMAT` | Klucz API musi zaczynać się od `vc_` | | 401 | `INVALID_API_KEY` | Podany klucz API jest nieprawidłowy | | 403 | `API_ACCESS_REQUIRED` | Dostęp do API jest wymagany dla tego konta | | 403 | `SUBSCRIPTION_REQUIRED` | Dostęp do API wymaga płatnej subskrypcji | | 403 | `INSUFFICIENT_CREDITS` | Niewystarczająca liczba kredytów do przetworzenia tego pliku | | 403 | `CUSTOM_VOICE_ACCESS_DENIED` | Niestandardowe głosy nie należą do faktycznego właściciela projektu | | 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Tryb premium synchronizacja ruchu ust jest niedostępny w bieżącym planie | | 429 | `RATE_LIMIT_EXCEEDED` | Zbyt wiele żądań (limit: 10 żądań na minutę) | | 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Zbyt wiele tłumaczeń w toku (limit: 10 jednoczesnych tłumaczeń) |