> ## 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. # Powiel zapisane napisy > Zapisz osobną edytowalną kopię napisów bez generowania kolejnej transkrypcji. Zapisz osobną edytowalną kopię napisów bez generowania kolejnej transkrypcji. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/subtitles_history_duplicate ``` ## 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 Wartość tekstowa. Minimalna długość: 1. Maksymalna długość: 160. Wzorzec: `^[A-Za-z0-9_-]+$`. Wartość tekstowa. Minimalna długość: 1. Maksymalna długość: 2097152. Obiekt JSON. Pola zagnieżdżone opisuje pełny schemat danych wejściowych. Obiekt JSON. Pola zagnieżdżone opisuje pełny schemat danych wejściowych. 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": { "historyId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9_-]+$" }, "currentSrtContent": { "type": "string", "minLength": 1, "maxLength": 2097152 }, "layoutOptions": { "type": "object", "properties": { "maxLinesPerCaption": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "maxCharactersPerLine": { "type": "integer", "minimum": 24, "maximum": 64 } }, "required": ["maxLinesPerCaption", "maxCharactersPerLine"], "additionalProperties": false }, "styleOptions": { "type": "object", "properties": { "fontFamily": { "type": "string", "enum": ["sans", "serif", "mono"] }, "fontSize": { "type": "string", "enum": ["small", "medium", "large"] }, "textColor": { "type": "string", "enum": ["white", "yellow", "cyan"] }, "backgroundStyle": { "type": "string", "enum": ["outline", "box", "shadow"] }, "position": { "type": "string", "enum": ["bottom", "middle"] } }, "required": ["fontFamily", "fontSize", "textColor", "backgroundStyle", "position"], "additionalProperties": false }, "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": ["historyId", "currentSrtContent"], "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/subtitles_history_duplicate' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"historyId":"history_20261016_001","currentSrtContent":"1\n00:00:00,000 --> 00:00:01,500\nHello world.\n","layoutOptions":{"maxLinesPerCaption":2,"maxCharactersPerLine":42},"styleOptions":{"fontFamily":"sans","fontSize":"medium","textColor":"white","backgroundStyle":"outline","position":"bottom"},"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}' ``` ```javascript JavaScript theme={null} const input = { historyId: 'history_20261016_001', currentSrtContent: '1\n00:00:00,000 --> 00:00:01,500\nHello world.\n', layoutOptions: { maxLinesPerCaption: 2, maxCharactersPerLine: 42, }, styleOptions: { fontFamily: 'sans', fontSize: 'medium', textColor: 'white', backgroundStyle: 'outline', position: 'bottom', }, requestId: '13579bdf-2468-4ace-8bdf-0123456789ab', }; const response = await fetch('https://api.voicecheap.ai/v1/actions/subtitles_history_duplicate', { 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/subtitles_history_duplicate", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"historyId": "history_20261016_001", "currentSrtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n", "layoutOptions": {"maxLinesPerCaption": 2, "maxCharactersPerLine": 42}, "styleOptions": {"fontFamily": "sans", "fontSize": "medium", "textColor": "white", "backgroundStyle": "outline", "position": "bottom"}, "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ź Pierwsze pomyślne wykonanie zwraca HTTP 200 z wynikiem operacji w data. Ponowienie może zamiast tego zwrócić zapisany stan żądania. Przykład przedstawia jedną obsługiwaną odpowiedź, bez wszystkich opcjonalnych pól. Nowy identyfikator niezależnie edytowalnej historii napisów, zaczynającej się od rewizji 1, wraz ze znormalizowanym SRT i znacznikiem czasu utworzenia. ```json HTTP 200 theme={null} { "data": { "historyId": "history_20261016_copy", "revision": 1, "updatedAt": 1792152010000, "currentSrtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n" }, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "subtitles_history_duplicate", "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": "subtitles_history_duplicate", "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.historyId` | Nowy zapisany element napisów, odrębny od wejściowego historyId. | | `data.revision` | 1 dla nowej edytowalnej kopii. | | `data.updatedAt` | Znacznik czasu Unix w milisekundach dla nowo utworzonej kopii. | | `data.currentSrtContent` | Znormalizowana przekazana treść napisów. | ## 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":"subtitles_history_duplicate"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab", "operation": "subtitles_history_duplicate", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "historyId": "history_20261016_copy", "revision": 1, "updatedAt": 1792152010000, "currentSrtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n" } } } ``` ## 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. * Wejściowy historyId wskazuje źródło należące do wywołującego. Podaj pełne currentSrtContent do skopiowania; nie jest ono automatycznie pobierane z zapisanego źródła. * Walidacja bloków napisów i limit 2 MiB są zgodne z subtitles\_history\_update. Pominięte layoutOptions/styleOptions używają standardowych wartości domyślnych. * Duplikat nie generuje nowej transkrypcji, nie zużywa przesłanego źródła ani dziennego limitu generowania narzędzia. Zużywa jedno udane miesięczne wywołanie 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 | `IDEMPOTENCY_CONFLICT` | Identyfikatory żądania w nagłówku i treści różnią się. | | 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. | | 400 | `VIDEO_TO_SRT_HISTORY_INVALID_SRT` | Tekst wpisu napisów SRT lub struktura znaczników czasu są nieprawidłowe. | | 400 | `VIDEO_TO_SRT_HISTORY_OUTSIDE_MEDIA` | Blok napisów kończy się po zapisanym czasie trwania źródła powiększonym o tolerancję 0.5 sekundy. | | 400 | `VIDEO_TO_SRT_HISTORY_OVERLAP` | Co najmniej dwa wpisy napisów nakładają się w czasie. | | 400 | `VIDEO_TO_SRT_HISTORY_SRT_TOO_LARGE` | Edytowany SRT przekracza limit 2 MiB w kodowaniu UTF-8. | | 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 | `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 | `VIDEO_TO_SRT_HISTORY_NOT_FOUND` | Edytowalny element historii napisów należący do użytkownika wykonującego żądanie nie istnieje. | | 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. | | 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. | | 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 | `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.