> ## 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 słowa napisów ze znacznikami czasu > Przekształć przesłaną ścieżkę audio w słowa ze znacznikami czasu do edycji napisów. Ta operacja nie udostępnia renderowania animowanego wideo ani lokalnych sesji edycji w przeglądarce. Zwraca zwięzłe odwołanie do zapisanego wyniku; użyj jego getAction lub downloadAction, aby pobrać pełny wynik. Przekształć przesłaną ścieżkę audio w słowa ze znacznikami czasu do edycji napisów. Ta operacja nie udostępnia renderowania animowanego wideo ani lokalnych sesji edycji w przeglądarce. Zwraca zwięzłe odwołanie do zapisanego wyniku; użyj jego getAction lub downloadAction, aby pobrać pełny wynik. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/captions_transcribe ``` ## 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: `subtitles: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 Własny fileKey zwrócony po ukończonym przesłaniu lub imporcie multimediów. Każde generowanie zużywa przesłane źródło. Minimalna długość: 1. Maksymalna długość: 1024. Wartość tekstowa. Minimalna długość: 1. Maksymalna długość: 255. Wzorzec: `^[^/\\\r\n\0]+$`. Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych. Maksymalna liczba elementów: 100. 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}$`. 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": { "fileKey": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "An owned fileKey returned by a completed upload or media import. Each generation consumes its uploaded source." }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\\\r\\n\\0]+$" }, "keyterms": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "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}$" } }, "required": ["fileKey"], "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/captions_transcribe' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"fileKey":"uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.wav","fileName":"interview.wav","keyterms":["VoiceCheap"],"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}' ``` ```javascript JavaScript theme={null} const input = { fileKey: 'uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.wav', fileName: 'interview.wav', keyterms: ['VoiceCheap'], requestId: '13579bdf-2468-4ace-8bdf-0123456789ab', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/captions_transcribe', { 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/captions_transcribe", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"fileKey": "uploads/account-user/a1b2c3d4-e5f6-4789-8abc-def012345678-interview.wav", "fileName": "interview.wav", "keyterms": ["VoiceCheap"], "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"}, 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. Odwołanie do zapisanych słów użytych w napisach. Pełny JSON zawiera words, durationSeconds i opcjonalne detectedLanguage. Każde słowo zawiera text, startMs, endMs oraz speakerId dopuszczające null. ```json HTTP 202 theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "status": "running", "pollAction": "action_request_get", "pollAfterSeconds": 5 }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ```json HTTP 200 theme={null} { "data": { "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b", "operation": "captions_transcribe", "createdAt": 1792152000000, "fileName": "voicecheap-captions_transcribe-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json", "byteLength": 190, "contentType": "application/json; charset=utf-8", "status": "completed", "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "getAction": "subtitles_result_get", "downloadAction": "subtitles_result_download", "listAction": "subtitles_result_list" }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "captions_transcribe", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "captions_transcribe", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ## Pola wyniku | Pole | Opis | | - | - | | `data.resultId` | UUID należącego do wywołującego zapisanego wyjścia. Użyj go z getAction lub downloadAction; jest odrębny od requestId i każdego historyId. | | `data.operation` | Akcja generowania, która utworzyła ten zapisany JSON. | | `data.createdAt` | Znacznik czasu Unix w milisekundach, kiedy przygotowano zapisany wynik. | | `data.fileName` | Sugerowana nazwa pliku eksportu JSON. | | `data.byteLength` | Bajty UTF-8 pełnego zserializowanego wyniku, a nie skróconych metadanych. | | `data.contentType` | application/json; charset=utf-8. | | `data.status` | completed po pomyślnym generowaniu. Historia wyników może również udostępniać wpisy odzyskiwania w stanie pending. | | `data.requestId` | UUID oryginalnego żądania akcji, jeśli został zapisany. | | `data.getAction` | Akcja pobierania własnego wyniku; includeContent ma domyślnie wartość false i musi mieć wartość true, aby uzyskać pełny ustrukturyzowany wynik. | | `data.downloadAction` | Uwierzytelniona akcja eksportu zwracająca pełny JSON w postaci ciągu znaków. | | `data.listAction` | Akcja wyświetlania należących do użytkownika zapisanych wyników dla tej domeny uprawnień. | ## 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":"13579bdf-2468-4ace-8bdf-0123456789ab","operation":"captions_transcribe"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "captions_transcribe", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "resultId": "b3caf96f-5f2a-4619-832c-a12c0d57f78b", "operation": "captions_transcribe", "createdAt": 1792152000000, "fileName": "voicecheap-captions_transcribe-b3caf96f-5f2a-4619-832c-a12c0d57f78b.json", "byteLength": 190, "contentType": "application/json; charset=utf-8", "status": "completed", "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "getAction": "subtitles_result_get", "downloadAction": "subtitles_result_download", "listAction": "subtitles_result_list" } } } ``` ## Uwagi do operacji * Wymaga płatnej subskrypcji i uprawnienia do akcji. Osobisty plan narzędzi użytkownika wykonującego żądanie jest ponownie sprawdzany podczas wykonywania; zapisane narzędzia i referencje przesłanych plików należą do tego użytkownika, również gdy dane uwierzytelniające są powiązane z zespołem. * Pomyślna akcja zużywa jedno wspólne miesięczne wywołanie API/MCP. Beginner pozwala na 500, Starter na 5,000, a Creator na 25,000 wywołań miesięcznie; Pro, Scale i Enterprise nie mają miesięcznego limitu. Nadal obowiązują limity na minutę: odpowiednio 30, 60, 120, 180, 300 i 600. Limity generowania narzędzi są odrębne. * Użyj requestId w formacie UUID v4 lub identycznego nagłówka Idempotency-Key i przy ponawianiu zachowuj tę samą akcję, identyfikator i argumenty. Odtworzenie zapisanej odpowiedzi nie zużywa kolejnego miesięcznego wywołania. * To akcja asynchroniczna. Początkowy wynik transportu to żądanie w stanie running z pollAction; sprawdzaj action\_request\_get z tą operacją i pierwotnym requestId. Pokazany tutaj wynik ukończonej operacji to zwięzłe odwołanie do zapisanego wyjścia, a nie wygenerowana treść. * Pełny wynik jest zapisywany w zaszyfrowanym magazynie danych jako własność uwierzytelnionego użytkownika, niezależnie od ograniczonej pamięci podręcznej sprawdzania stanu akcji. Wywołaj zwrócone getAction z resultId i includeContent: true, aby pobrać ustrukturyzowany JSON, lub downloadAction z resultId, aby pobrać tekst JSON. listAction umożliwia odzyskanie wyniku, gdy znane jest tylko oryginalne żądanie. * Zapisany JSON jest ograniczony do 32 MiB. Metadane nigdy nie ujawniają klucza szyfrowania przechowywanej treści ani niewymagającego uwierzytelnienia adresu URL do pobrania transkrypcji. * Pomyślne generowanie rozlicza jedno użycie osobistego limitu narzędzia. Nieudane generowanie zwykle zwalnia rezerwację narzędzia. Jeśli zapisanie wyjścia jest niepewne, przed ponownym generowaniem sprawdź to samo żądanie i historię zapisanych wyników; serwer zachowuje rezerwację, aby zapobiec podwójnemu zużyciu limitu. * Wyższe plany bez miesięcznego limitu integracji nadal podlegają poniższym dziennym limitom narzędzi i limitom multimediów. Te samodzielne akcje korzystają z limitu swojego narzędzia zamiast z minut dubbingu lub znaków TTS. * Użyj fileKey z ukończonego, należącego do Ciebie przesyłania lub importu i traktuj go jako jednorazowy. Po rozpoczęciu przetwarzania multimediów mechanizm czyszczenia usuwa źródło po powodzeniu lub błędzie przetwarzania. Odrzucenie podczas walidacji lub z powodu limitu przed rozpoczęciem przetwarzania może pozostawić je bez zmian. Użyj ponownie pierwotnego requestId, aby odzyskać zaakceptowane generowanie przed rozpoczęciem kolejnego. * Prześlij wyłącznie wyodrębnioną ścieżkę audio: WAV, MP3, M4A, AAC, OGG, Opus lub FLAC, maksymalnie 250 MiB. Plik zawierający strumień wideo zostanie odrzucony, nawet jeśli jego nazwa ma rozszerzenie audio. * Beginner akceptuje do 30 minut; Starter, Creator, Pro, Scale i Enterprise akceptują do 60 minut, z dodatkową tolerancją kontenera wynoszącą 2 sekundy. * Dzienny limit transkrypcji napisów: Beginner 10, Starter 15, Creator 30, Pro 60, Scale 100 i Enterprise 100; współdzielony z internetowym narzędziem do napisów. * Przesunięcia czasowe słów są podawane w milisekundach; durationSeconds jest podawane w sekundach. Serwer zwraca słowa ze znacznikami czasu, a nie wyrenderowany film z animacją. Lokalna edycja i renderowanie napisów w przeglądarce nie są objęte tą akcją. * Transkrypcja napisów nie ma odrębnej rodziny akcji historii internetowej. Użyj subtitles\_result\_list/get/download, aby odzyskać jej pełny wynik integracji. ## 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 | `DURATION_TOO_LONG` | Czas trwania multimediów przekracza limit dla tej operacji. | | 400 | `DURATION_UNKNOWN` | Na etapie wykonania nie udało się ustalić dodatniego czasu trwania multimediów. | | 400 | `FILE_TOO_LARGE` | Zapisane źródło przekracza limit bajtów właściwy dla danej operacji. | | 400 | `IDEMPOTENCY_CONFLICT` | Identyfikatory żądania w nagłówku i treści różnią się. | | 400 | `INVALID_FILE_TYPE` | Rozszerzenie nazwy pliku nie jest obsługiwane dla tej operacji. | | 400 | `INVALID_MEDIA_DURATION` | Zbadany czas trwania źródła nie istnieje, jest nieprawidłowy lub przekracza limit czasu trwania planu. | | 400 | `INVALID_MEDIA_STREAM` | Źródło nie zawiera użytecznego strumienia audio do transkrypcji. | | 400 | `INVALID_REQUEST_ID` | requestId lub Idempotency-Key nie jest identyfikatorem UUID v4. | | 400 | `VALIDATION_ERROR` | Argumenty nie spełniają schematu akcji lub podano nieznany argument. | | 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` | Klucz API lub połączenie MCP nie ma uprawnienia wymaganego do wykonania tej akcji. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Nie udało się zweryfikować limitów integracji konta. | | 403 | `INVALID_FILE_REFERENCE` | fileKey nie jest prawidłowym odwołaniem do ukończonego przesyłania należącego do użytkownika wykonującego wywołanie. | | 403 | `PAID_SUBSCRIPTION_REQUIRED` | Uwierzytelniony wywołujący nie ma już płatnej subskrypcji w chwili wykonywania tej akcji narzędzia. | | 403 | `SUBSCRIPTION_REQUIRED` | Użyj aktywnej płatnej subskrypcji. | | 403 | `TEAM_OWNER_NOT_FOUND` | Nie znaleziono konta faktycznego właściciela zespołu. | | 404 | `MEDIA_NOT_FOUND` | Ukończony przesłany plik źródłowy nie istnieje lub jest pusty; mógł zostać zużyty przez wcześniejsze generowanie. | | 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. | | 410 | `TOOL_RESULT_ACCOUNT_UNAVAILABLE` | Konto wywołującego jest usuwane lub już nie istnieje, więc nie można zapisać trwałego wyniku. | | 413 | `TOOL_RESULT_TOO_LARGE` | Pełny wygenerowany JSON przekracza 32 MiB i nie może zostać zapisany jako wynik integracji. | | 422 | `TRANSCRIPTION_EMPTY` | Audio nie zawiera rozpoznanych wypowiedzianych słów. | | 429 | `ANIMATED_CAPTIONS_TOOL_DAILY_LIMIT_REACHED` | Użytkownik wykonujący żądanie wyczerpał limit transkrypcji na potrzeby animowanych napisów. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Wykorzystane i oczekujące wywołania osiągnęły wspólny miesięczny limit API/MCP. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Konto osiągnęło limit integracji na minutę; sprawdź retryAfterSeconds. | | 500 | `INTERNAL_ERROR` | Sprawdź stan zapisanego żądania i historię zasobu przed podjęciem decyzji o ponowieniu operacji zmieniającej dane. | | 502 | `INTERNAL_ERROR` | Generowanie lub zapis wyniku nie powiodły się. Sprawdź oryginalne żądanie i historię zapisanych wyników przed rozpoczęciem kolejnego generowania. | | 503 | `ACTION_RESULT_UNAVAILABLE` | Akcja została wykonana, ale nie udało się potwierdzić trwałego zapisania wyniku żądania. Sprawdzaj stan tej samej akcji i requestId oraz historię zasobu, zanim rozpoczniesz kolejny zapis. | | 503 | `INTERNAL_ERROR` | Wynik generowania lub trwałego zapisu wyniku jest niepewny albo tymczasowo niedostępny; użyj uwierzytelnionego odzyskiwania wyniku przed ponownym generowaniem. | | 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": ["subtitles:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.