- Wiedza
Integracja Speech to Text API: Przewodnik dla deweloperów
- Autor
- Jack Limebear
PosłuchajPosłuchaj tego artykułu
Speech to Text API pozwala deweloperom dodać rozpoznawanie mowy i transkrypcję bezpośrednio do aplikacji. Zanim jednak połączysz STT API, musisz podjąć kilka decyzji dotyczących architektury.
Jakiego trybu transkrypcji użyjesz? Jak obsłużysz długie pliki audio? Jak zadbasz o poprawną pisownię nazw produktów czy nazw własnych? Trochę planowania na tym etapie bardzo ułatwi stworzenie skalowalnej Speech to Text API w twojej aplikacji.
W tym przewodniku znajdziesz wszystko, czego potrzebujesz do integracji ElevenLabs Speech to Text API, wraz z jasnymi przykładami kodu gotowymi do użycia w produkcji. Przyda się też mieć pod ręką ElevenLabs Szybki start Speech to Text i przewodnik po API w osobnym oknie.
Podsumowanie
- Są dwa tryby ElevenLabs Speech to Text: batch (dla nagrań) i realtime (dla transmisji na żywo przez WebSocket).
- Scribe v2 obsługuje transkrypcję batch w ponad 90 językach z diarizacją, podpowiadaniem słów kluczowych, wykrywaniem encji, znacznikami czasowymi na poziomie słów i obsługą wielu kanałów.
- Scribe v2 Realtime obsługuje streaming na żywo z opóźnieniem ok. 150 ms, zwracając częściowe transkrypcje na bieżąco i finalne po zakończeniu wypowiedzi.
- Dla plików powyżej 8 minut Scribe v2 automatycznie dzieli je na części i transkrybuje równolegle. Przy długich zadaniach użyj webhooków zamiast czekać na odpowiedź synchroniczną.
- Podpowiadanie słów kluczowych kieruje model na konkretne terminy w kontekście – to skuteczniejsze niż lista słów kluczowych przy nazwach produktów, żargonie technicznym czy nietypowych nazwach własnych.
Integracja Speech to Text API: Batch czy realtime
Każda integracja ElevenLabs STT API zaczyna się od wyboru architektury: batch czy realtime. Oba tryby dają ci mocny model STT, ale wybór wpływa na dostępne funkcje i opóźnienia.
Oto porównanie obu trybów:
- Batch (Scribe v2): Przyjmuje cały plik audio lub wideo, transkrybuje go i zwraca pełną transkrypcję w jednej odpowiedzi. Obsługuje najwięcej funkcji: do 1 000 słów kluczowych, do 32 mówców (diaryzacja), wykrywanie encji, tryb wielokanałowy i webhooki do asynchronicznej dostawy. Pliki do 3 GB i 10 godzin są obsługiwane w trybie standardowym.
- Realtime (Scribe v2 Realtime): Przyjmuje strumień audio na żywo przez WebSocket i zwraca częściowe oraz finalne transkrypcje na bieżąco, z opóźnieniem ok. 150 ms. Obsługuje do 50 słów kluczowych i znaczniki czasowe na poziomie słów. To dobry wybór do asystentów głosowych, napisów na żywo czy wszędzie tam, gdzie użytkownik mówi i oczekuje szybkiej odpowiedzi.
Przyjrzyjmy się różnicom bliżej.
Prosta zasada: użyj batch, gdy masz już cały plik audio przed transkrypcją, a realtime, gdy transkrybujesz na bieżąco.
Kiedy wybrać Scribe v2, a kiedy Scribe v2 Realtime
Batch i realtime służą do różnych zadań – zły wybór na początku zwykle oznacza konieczność poprawek później.
Oto jak dobrać model do swojego zastosowania:
- Scribe v2 sprawdzi się, gdy audio jest gotowe przed przetwarzaniem – np. nagrania spotkań, podcasty, pliki multimedialne czy wszystko, co robisz offline. Obsługuje pełen zestaw funkcji: diarizację, wykrywanie encji i do 1 000 słów kluczowych.
- Scribe v2 Realtime jest stworzony do audio na żywo. Przyjmuje strumień WebSocket i zwraca transkrypcje na bieżąco, więc to dobry wybór do asystentów głosowych czy sytuacji, gdzie aplikacja musi odpowiedzieć zanim użytkownik skończy mówić.
Warto też pamiętać, że dokładność zależy od języka. Sprawdź wskaźnik błędów transkrypcji zanim zdecydujesz się na konkretny zestaw języków. Scribe v2 publikuje poziomy Word Error Rate (WER) dla wszystkich 90+ obsługiwanych języków.
Bardzo dobra dokładność (≤5% WER) obejmuje główne języki europejskie, japoński, indonezyjski, wietnamski i inne. Wysoka dokładność (5-10% WER) to m.in. hindi, bengalski, mandaryński, koreański i gruziński. Szczegóły znajdziesz w dokumentacji wsparcia językowego.
Konfiguracja ElevenLabs Speech to Text API
Aby uruchomić klienta, wystarczą dwa proste kroki. Najpierw instalujesz SDK. Potem bezpiecznie zapisujesz swoje dane dostępowe.
Oto jak zrobić oba kroki zanim wyślesz pierwsze żądanie transkrypcji.
Zainstaluj SDK i zapisz swój klucz API jako sekret w pliku .env lub menedżerze sekretów twojej platformy. Nigdy nie wpisuj klucza API bezpośrednio w kodzie.
Python
TypeScript
Utwórz plik .env:
Zainicjuj klienta:
Python
TypeScript
Pierwsza transkrypcja batch z ElevenLabs STT API
Po inicjalizacji klienta możesz wysłać pierwszy plik.
Batch API przyjmuje plik, transkrybuje go i zwraca pełny wynik synchronicznie. Przykład poniżej transkrybuje zdalny plik audio z włączoną diarizacją i tagowaniem zdarzeń dźwiękowych.
Python
Uruchom:
Obiekt odpowiedzi zawiera pełny tekst transkrypcji, słowa z czasami i ID mówców oraz wykryte zdarzenia dźwiękowe.
Każdy wpis słowa ma pole type z jedną z trzech wartości:
- słowo: Dla słów rozpoznanych w audio.
- odstęp: Spacje między słowami w językach, które ich używają. Ten typ nie dotyczy niektórych języków, np. japońskiego, kantońskiego czy birmańskiego.
- audio_event: Tag dla dźwięków innych niż mowa, np. śmiech czy kaszel.
Tak wygląda struktura odpowiedzi:
Pole language_probability pokazuje, jak bardzo model jest pewny wykrytego języka (skala 0.00–1.00).
Integracja STT API Realtime
STT na żywo API działa trochę inaczej. Zamiast jednego żądania i odpowiedzi, otwierasz połączenie WebSocket i odbierasz transkrypcje na bieżąco.
Realtime API używa WebSocket do odbierania strumienia audio na żywo i zwracania transkrypcji na bieżąco. Dostarcza dwa typy transkryptów:
- Częściowe transkrypcje: Tymczasowe wyniki, które aktualizują się w trakcie przetwarzania audio. Mogą się zmieniać.
- Finalne transkrypcje: Ostateczne wyniki dla zakończonego fragmentu mowy. Te już się nie zmienią. Mogą zawierać znaczniki czasowe, jeśli ustawisz opcję "include timestamps" na true.
Po stronie klienta używasz tokenu jednorazowego zamiast klucza API. To tymczasowe dane dostępowe ważne 15 minut, generowane po stronie serwera, więc klucz API nie trafia do przeglądarki.
Krok 1: Wygeneruj token jednorazowy (po stronie serwera)
Krok 2: Połącz się i transkrybuj (po stronie klienta, React)
Hook useScribe zarządza cyklem życia połączenia WebSocket, dostępem do mikrofonu i stanem transkrypcji. partialTranscript trzyma aktualny tekst, committedTranscripts to rosnąca lista finalnych fragmentów.
Aby transkrybować po stronie serwera (np. z URL lub pliku zamiast mikrofonu), zobacz przewodnik po streamingu po stronie serwera.
Współbieżność i skalowanie długich plików
Długie pliki wymagają innego podejścia do skalowania niż większość API. Warto to zrozumieć przed wdrożeniem.
Współbieżność dla batch działa inaczej niż w większości API. Zamiast ograniczać liczbę równoczesnych żądań, Scribe v2 sam dzieli długie pliki i przetwarza je równolegle.
Pliki powyżej 8 minut są dzielone na segmenty i transkrybowane jednocześnie. Liczba segmentów jest wyliczana tak:
Konkretne przykłady:
- Plik 15-minutowy użyje współbieżności 2
- Plik 120-minutowy użyje współbieżności 4 (maksimum)
Pliki do 10 godzin i 3 GB są obsługiwane w trybie standardowym. Uwaga: tryb wielokanałowy ma niższy limit czasu – szczegóły w sekcji o transkrypcji wielokanałowej.
Jeśli chodzi o formaty, STT API obsługuje najpopularniejsze formaty audio i wideo:
- Audio: AAC, AIFF, OGG, MP3, OPUS, WAV, FLAC, M4A, WebM.
- Wideo: MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP.
Możesz przesłać plik wideo i dostać transkrypcję ścieżki audio bez żadnego wstępnego przetwarzania.
Podpowiadanie słów kluczowych
Modele ogólne często mylą nazwy marek i żargon techniczny. Podpowiadanie słów kluczowych rozwiązuje ten problem.
Podpowiadanie słów kluczowych kieruje model na konkretne słowa lub frazy podczas transkrypcji. To dobre rozwiązanie, gdy w audio pojawiają się nazwy produktów, terminy techniczne czy nietypowe nazwy własne.
Co ważne, podpowiadanie korzysta z kontekstu, więc jest skuteczniejsze niż zwykła lista słów. Jeśli podasz "ElevenLabs" jako słowo kluczowe, model poprawnie zapisze nazwę firmy, gdy padnie w nagraniu. Bez tego możesz dostać błędną transkrypcję typu "I've worked at eleven labs for a year".
Bez podpowiadania słów kluczowych:
Z keyterms=["ElevenLabs"]:
Batch obsługuje do 1 000 słów kluczowych (po 50 znaków). Realtime – do 50 słów (po 20 znaków).
Transkrypcja batch ze słowami kluczowymi
Python
Streaming realtime ze słowami kluczowymi
Przekaż słowa kluczowe przy łączeniu z WebSocket realtime:
Python
Lub przekaż je jako parametry w URL WebSocket:
Podpowiadanie słów kluczowych wiąże się z dodatkowym kosztem. Szczegóły na stronie cennika API.
Funkcje zaawansowane
Powyższe kroki pokazują podstawowy przepływ transkrypcji STT API, ale jest kilka funkcji, które wzbogacają wynik. Oto zaawansowane opcje, które możesz wykorzystać:
- Diarizacja mówców – rozpoznawanie, kto mówi
- Tryb no-verbatim – czyszczenie transkrypcji
- Wykrywanie encji – oznaczanie wrażliwych danych
- Transkrypcja wielokanałowa – rozdzielanie kanałów audio
Rozwińmy to bardziej.
Diarizacja mówców
Ustaw diarize=True w żądaniu batch, by oznaczyć, kto mówi. Scribe v2 obsługuje do 32 mówców. Każde słowo w odpowiedzi ma pole speaker_id (np. speaker_0, speaker_1), dzięki czemu możesz rozdzielić fragmenty transkrypcji według mówcy.
Diarizacja przydaje się przy transkrypcji spotkań, wywiadów czy nagrań z wieloma osobami, gdzie ważne jest przypisanie słów do właściwego mówcy.
Tryb no-verbatim
Gdy no_verbatim=True, model usuwa wypełniacze, powtórzenia i niepłynności z transkrypcji. "Erm, M-maybe we should, uh, go with option A" zamienia się w "Maybe we should go with option A."
Dzięki temu otrzymujesz czystszy tekst do napisów, podsumowań czy tam, gdzie liczy się czytelność. Opcja dostępna w batch (scribe_v2) i realtime (scribe_v2_realtime).
Wykrywanie encji i anonimizacja
Scribe v2 wykrywa i oznacza encje w transkrypcji, z dokładnymi znacznikami czasu. Kategorie to m.in. PII (nazwy, numery kart, PESEL), PHI (dane medyczne), PCI (informacje o kartach płatniczych) i inne. Pełna lista typów encji w dokumentacji wykrywania encji.
To szczególnie przydatne przy zgodności z przepisami – możesz automatycznie wykryć i ukryć wrażliwe dane przed zapisaniem lub wyświetleniem transkrypcji.
Wykrywanie encji to dodatkowy koszt $0.070 (za godzinę) ponad bazową cenę transkrypcji. Szczegóły na stronie cennika API.
Transkrypcja wielokanałowa
Gdy use_multi_channel=True, każdy kanał audio jest transkrybowany osobno i dostaje ID mówcy na podstawie numeru kanału. Obsługiwanych jest do 5 kanałów. Maksymalna długość pliku w tym trybie to 1 godzina.
Tryb wielokanałowy sprawdza się, gdy masz osobne ścieżki audio dla każdego mówcy – np. nagranie rozmowy telefonicznej, gdzie każdy uczestnik jest na swoim kanale. To daje dokładniejsze przypisanie mówców niż diarizacja na pliku mono.
Dostawa asynchroniczna przez webhooki
Odbieranie wyniku przez polling działa przy małej skali, ale nie sprawdzi się przy długich plikach lub dużym ruchu. Webhooki rozwiązują ten problem, wysyłając wynik do ciebie.
Przy długich plikach lub dużej liczbie transkrypcji czekanie na odpowiedź synchroniczną nie ma sensu. Webhooki pozwalają wysłać żądanie i odebrać wynik na swoim endpointcie, gdy przetwarzanie się skończy – bez pollingu.
Konfiguracja webhooka
W panelu ElevenLabs przejdź do Deweloperzy > Webhooki, kliknij Utwórz webhook i ustaw:
- Nazwa: Podaj opisową i łatwą do zapamiętania nazwę webhooka.
- Callback URL: Dodaj publiczny endpoint HTTPS do webhooka.
- Metoda autoryzacji webhooka: Wybierz HMAC lub OAuth (opcjonalne, ale zalecane dla bezpieczeństwa).
- Zdarzenia: Wybierz Transcription completed z listy.
Wysyłanie transkrypcji z dostawą przez webhook
Python
Gdy webhook=True, żądanie zwraca odpowiedź od razu, bez transkrypcji. Gotowa transkrypcja trafia na twój endpoint jako POST po zakończeniu przetwarzania.
Implementacja endpointu webhooka
Struktura payloadu webhooka
Twój endpoint dostaje POST o takiej strukturze:
Najlepsze praktyki bezpieczeństwa webhooków
Przy pracy z webhookami warto zadbać o kilka kwestii, by mieć pewność, że zdarzenia są poprawnie dostarczane i przetwarzane.
- Weryfikuj podpisy webhooków: Zawsze sprawdzaj podpisy webhooków przez elevenlabs.webhooks.constructEvent(), by potwierdzić, że pochodzą od ElevenLabs.
- Używaj endpointów HTTPS: Adresy webhooków muszą być HTTPS, by chronić dane w trakcie przesyłania.
- Zwracaj odpowiedni kod statusu HTTP: Zwróć 200–299 przy sukcesie, 400–499 przy błędach po stronie klienta (nie będą ponawiane) i 500–599 przy błędach serwera (będą ponawiane).
- Użyj narzędzia tunelującego do pracy lokalnej: Do testów lokalnych użyj narzędzia typu ngrok, by wystawić lokalny serwer pod publicznym adresem HTTPS.
Dzięki tym zasadom możesz korzystać z webhooków bez obaw.
Najważniejsze rzeczy przy integracji Speech to Text API
Integracja Speech to Text API w produkcji sprowadza się do kilku decyzji.
Jeśli dobrze je wybierzesz, reszta pójdzie łatwo:
- Dobierz tryb do zastosowania: Użyj batch (scribe_v2), gdy audio jest gotowe przed przetwarzaniem. Użyj realtime (scribe_v2_realtime), gdy musisz transkrybować na bieżąco, np. dla agentów, asystentów głosowych czy napisów na żywo.
- Używaj słów kluczowych dla lepszej dokładności: Przekaż nazwy produktów, terminy techniczne czy nietypowe nazwy własne jako słowa kluczowe. Model wykorzysta kontekst i nie będzie ich nadużywał.
- Pozwól API obsłużyć długie pliki: Pliki powyżej 8 minut są automatycznie dzielone i przetwarzane równolegle – nie musisz robić tego sam. Pliki do 10 godzin i 3 GB są obsługiwane w trybie standardowym.
- Używaj webhooków do asynchronicznych zadań: Przy długich zadaniach lub dużej liczbie plików webhook=True pozwala wysłać żądanie i zająć się czymś innym. Weryfikuj podpis każdego webhooka.
- Włącz tryb no-verbatim dla czystych wyników: Jeśli robisz napisy, podsumowania lub przetwarzanie NLP, no_verbatim=True automatycznie usuwa wypełniacze i niepłynności.
- Użyj trybu wielokanałowego dla osobnych ścieżek audio: Jeśli nagranie ma osobny kanał na mówcę (call center, wywiady), transkrypcja wielokanałowa daje dokładniejsze przypisanie mówców niż diarizacja na pliku mieszanym. Pamiętaj o limicie 1 godziny w tym trybie.
Jeśli chcesz wiedzieć więcej, sprawdź pełną dokumentację API na start.
Zbuduj swoją integrację Speech to Text z ElevenAPI
Po tym przewodniku masz wszystkie wzorce potrzebne do wdrożenia Speech to Text API w produkcji. Zarówno batch, jak i realtime, a także funkcje jak podpowiadanie słów kluczowych czy asynchroniczna dostawa – jesteś gotowy, by uruchomić aplikację z podpiętym STT.
Zacznij od poznania Speech to Text API lub zarejestruj się, by wykonać pierwsze zapytanie przez ElevenAPI już dziś.
