Skip to main content
POST
Dodaj do kolejki ponowne generowanie mowy segmentu, opcjonalnie odśwież synchronizację ruchu ust i wykorzystaj zwykłe kredyty na multimedia. requestId musi być stałym UUID. Sprawdzaj stan przez segment_actions_list.

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: translations: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
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec: ^[^/\\]+$.
string
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec: ^[^/\\]+$.
string
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec: ^[^/\\]+$.
integer
wymagane
Liczba całkowita.Minimum: 0. Maksimum: 9007199254740991.
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
Wartość tekstowa.Maksymalna długość: 500.
boolean
Wartość logiczna.
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ź

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. Zwraca potwierdzenie przyjęcia do kolejki ponownego generowania jednego segmentu w przetłumaczonej wersji, do której wywołujący ma uprawnienia.

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 jednego requestId w formacie UUID v4 dla zamierzonej edycji i używaj go ponownie z identycznymi argumentami przy ponawianiu żądania. jobId jest równy temu requestId.
  • Przyjęcie do realizacji zwraca started lub queued, a nie potwierdzenie ukończenia. Sprawdzaj stan przez segment_actions_list i szukaj items[].id równego jobId aż do uzyskania completed, failed lub cancelled, a następnie odśwież dane przez transcripts_get i projects_get.
  • queue.revision śledzi stan kolejki; nie jest rewizją struktury segmentów źródłowych. Akcje kolejkowe rejestrują bieżącą strukturę w chwili przyjęcia do realizacji. Późniejsza niezgodna zmiana struktury może spowodować błąd elementu z kodem SEGMENT_STRUCTURE_CHANGED.
  • Przyjmowana jest tylko jedna oczekująca akcja dla tego samego logicznego celu segmentu. Nowy requestId nie omija SEGMENT_ACTION_ALREADY_PENDING.
  • Błędy wykonania w kolejce są widoczne jako items[].status o wartości failed wraz z errorCode i nie zmieniają wyniku pomyślnego zgłoszenia.
  • workId i translatedVersionId muszą należeć do wybranego projektu i być ze sobą powiązane. Proces roboczy ocenia aktualne multimedia, stan segmentów, uprawnienia i kredyty w chwili rozpoczęcia wykonania.
  • segmentTranslationInstructions jest opcjonalne i ograniczone do 500 znaków. regenerateLipSync true zleca ponowne wygenerowanie synchronizacji ruchu ust segmentu po wygenerowaniu mowy, z użyciem ostatniego trybu synchronizacji ruchu ust tej wersji.
  • Obowiązują standardowe kredyty na multimedia. Pomyślne przyjęcie nie oznacza, że ponowne generowanie lub opcjonalna synchronizacja ruchu ust zakończyły się pomyślnie.
  • Po zakończeniu elementu kolejki odśwież projects_get i transcripts_get; sama odpowiedź nie zawiera nowego adresu URL audio ani wideo.
  • Odpowiedzi kolejki, również przy przesyłaniu, anulowaniu, odpytywaniu i ponawianiu, zawierają tylko metadane działań. Odczytuj treść transkrypcji przez transcripts_get z wymaganym uprawnieniem transcription:read.

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