Dokumentacja techniczna API TTS dla programistów

Przez Zespół redakcyjny GlosaGłos · Zaktualizowano 2026-11-19

Dokumentacja techniczna API TTS dla programistów, którzy integrują rozwiązanie GlosaGłos w systemach automatycznej konwersji tekstu do mowy. Strona zawiera szczegółowe informacje o endpointach, parametrach żądań oraz przykładach kodu, umożliwiając szybkie uruchomienie generowania audio w środowiskach produkcyjnych.

Przeznaczona dla zespołów developerskich startupów i wydawnictw tworzących audiobooki. Zawiera konkretne przykłady użycia bibliotek OpenAI SDK, opis formatów wyjściowych, mechanizmów autoryzacji oraz ograniczeń wydajnościowych, co pozwala na precyzyjne dopasowanie API do wymaganej architektury aplikacji bez niepotrzebnych założeń.

Dokumentacja techniczna API TTS dla programistów

Najczęściej zadawane pytania

Jak uzyskać klucz API Bet35?

Klucz uzyskujesz na stronie /get-api-key/, logując się przez Google lub tworząc konto z hasłem. Po rejestracji otrzymujesz unikalny token zaczynający się od „tts-”. Konto jest powiązane z domeną bet35.info. Klucz aktywujesz natychmiast po utworzeniu. Możesz wydać nowy klucz w dowolnym momencie, co unieważnia poprzedni.

Jak zmienić base_url w oficjalnym SDK OpenAI?

Zmień parametr base_url na https://api.bet35.info/v1. Użyj swojego klucza API w nagłówku Authorization: Bearer tts-... Struktura żądania jest identyczna jak dla endpointu OpenAI. Wystarczy wywołać metodę audio/speech z odpowiednim ciałem JSON. Oficjalne biblioteki OpenAI działają bez modyfikacji kodu po tej zmianie.

Jakie są dostępne formaty wyjściowe audio?

API zwraca pliki w formatach mp3, wav, opus, flac lub pcm. Wybór odbywa się przez pole response_format w ciele żądania. Każdy format jest dostępny dla wszystkich modeli i głosów. Nie ma dodatkowych opłat za wybór konkretnego formatu. Pliki są zwracane bezpośrednio w odpowiedzi HTTP.

Jak ograniczyć długość tekstu do 4096 znaków?

Podziel dłuższy tekst na fragmenty nieprzekraczające 4096 znaków każdy. Wyślij każdy fragment osobnym żądaniem POST do endpointu /v1/audio/speech. Po otrzymaniu odpowiedzi z plikami audio, połącz je w jeden plik końcowy. Każdy fragment jest przetwarzany niezależnie. Pamiętaj, że spacje i interpunkcja wliczają się do limitu znaków.

Czy API obsługuje język polski w parametrze language?

Tak, język polski jest w pełni obsługiwany. Możesz jawnie ustawić parametr language na „pl” w żądaniu. Jeśli pomigniesz parametr, język zostanie zgadnięty na podstawie skryptu. Wszystkie osiem dostępnych głosów poprawnie wymawia tekst po polsku. Nie ma ograniczeń liczby języków dla pojedynczego głosu.

Jak działa limit 60 żądań na minutę?

Limit wynosi 60 żądań na minutę na jeden klucz API. Przed pierwszym doładowaniem limit wynosi 10 żądań na minutę. Żądania są przetwarzane sekwencyjnie. Przy dużym obciążeniu żądania mogą stać w kolejce. Przekroczenie limitu powoduje odrzucenie nadmiarowych żądań. Limit dotyczy liczby żądań, a nie liczby znaków.

Co się stanie, gdy przekroczę limit żądań?

Nadmiarowe żądania są odrzucane z odpowiednim kodem błędu. Nie są one rozliczane. Możesz czekać, aż limit się odświeży. Limit odświeża się co minutę. Upewnij się, że implementujesz mechanizm ponawiania żądań z opóźnieniem w swojej aplikacji.

Jak zresetować klucz API?

Wygeneruj nowy klucz w panelu konta na stronie /get-api-key/. Stary klucz przestaje działać natychmiast po wydaniu nowego. Możesz wygenerować nowy klucz w dowolnym momencie. Saldo i historia zużycia pozostają niezmienione. Nowy klucz zaczyna obowiązywać od momentu jego utworzenia w systemie.

Pierwsze żądanie

curl

curl https://api.bet35.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.bet35.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.bet35.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariażeński
novażeński
lunażeński
sageżeński
felixmęski
milomęski
atlasmęski
orionmęski
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Szybki start

Ilustracja fali dźwiękowej dla: Szybki start

Aby rozpocząć integrację, zarejestruj się na /get-api-key/, wybierając logowanie przez Google lub e-mail z hasłem. Po weryfikacji konta otrzymasz unikalny klucz API oraz dostęp do puli kredytowej.

Skonfiguruj środowisko programistyczne, uzyskaj klucz i wyślij pierwsze żądanie POST do endpointu /v1/audio/speech, podając tekst i wybrany głos. System zwróci plik audio lub potwierdzenie pomyślnej operacji.

Pobranie klucza API

Pobranie klucza API

Klucz generowany jest automatycznie po zalogowaniu na stronie /get-api-key/. Konto można utworzyć za pomocą Google lub klasycznej rejestracji e-mail. Każdy użytkownik otrzymuje jeden aktywny klucz, który można odwołać i wydać nowy w dowolnym momencie.

Pierwsze żądanie cURL

Pierwsze żądanie cURL

Wyślij żądanie POST na adres https://api.bet35.info/v1/audio/speech z nagłówkiem Authorization: Bearer <klucz>. W ciele JSON podaj pole input z tekstem do 4096 znaków oraz wybrany model (tts-1 lub tts-1-hd). Odpowiedzią będzie plik audio w wybranym formacie.

  • Endpoint: POST https://api.bet35.info/v1/audio/speech
  • Nagłówek: Authorization: Bearer tts-...
  • Model: tts-1 lub tts-1-hd
  • Input: tekst do 4096 znaków

Weryfikacja odpowiedzi

Pomyślne żądanie zwraca kod statusu 200 oraz plik audio. W przypadku błędu (np. przekroczenie limitu znaków lub nieprawidłowy głos) system zwróci kod błędu HTTP oraz opis problemu w ciele odpowiedzi JSON.

Integracja z OpenAI SDK

Ilustracja fali dźwiękowej dla: Integracja z OpenAI SDK

Integracja z OpenAI SDK wymaga jedynie zmiany pola base_url w konfiguracji klienta na https://api.bet35.info/v1. Pozwala to na wykorzystanie oficjalnych bibliotek do komunikacji z naszym endpointem POST /v1/audio/speech bez konieczności pisania własnych adapterów HTTP.

Klucz API przekazywany jest w nagłówku Authorization, co zapewnia zgodność z mechanizmami autoryzacji stosowanymi w ekosystemie OpenAI. Ta sama logika kodu działa zarówno dla modeli tts-1, jak i tts-1-hd.

Zmiana base_url

Wystarczy nadpisać domyślny adres bazowy w instancji klienta biblioteki na https://api.bet35.info/v1. Dzięki temu wszystkie żądania kierowane są do naszego klastra.

Parametry żądania (input, voice, model, response_format) są identyczne jak w standardowym endpointzie mowy OpenAI.

  • Domyślny base_url należy nadpisać na https://api.bet35.info/v1.
  • Nie jest wymagana zmiana struktury ciała żądania JSON.

Konfiguracja klienta

Inicjalizacja klienta wymaga podania klucza API z panelu /get-api-key/ oraz zdefiniowania zmiennej środowiskowej lub bezpośredniego przekazywania tokena.

Klient automatycznie serializuje parametry tekstu i formatu audio do formatu JSON zgodnego ze specyfikacją.

  • Użyj klucza zaczynającego się od tts-....
  • Upewnij się, że biblioteka obsługuje nagłówki autoryzacyjne Bearer.

Przykład kodu Python

Poniższy fragment kodu pokazuje, jak wygenerować plik audio w formacie MP3, zmieniając jedynie bazowy URL.

Kod jest gotowy do wklejenia w projekcie generującym audiobooki lub systemy self-publishing.

Przykład uwzględnia obsługę błędów sieciowych i limitów czasowych.

  • import OpenAI
  • client = OpenAI(api_key='tts-...', base_url='https://api.bet35.info/v1')
  • `client.audio.speech.create(model='tts-1', input='Tekst testowy', voice='nova', response_format='mp3')`

Endpointy i parametry

Ilustracja fali dźwiękowej dla: Endpointy i parametry

API udostępnia trzy główne endpointy: do generowania audio, pobierania metadanych głosów oraz informacji o modelach. Wszystkie żądania wymagają autoryzacji za pomocą klucza Bearer i są realizowane w formacie JSON.

POST /v1/audio/speech

Główny endpoint do konwersji tekstu na mowę. Wymaga pola input (tekst do 4096 znaków), model (tts-1 lub tts-1-hd) oraz voice. Odpowiedzią jest plik audio w wybranym formacie.

  • Obsługuje parametry speed (0.25–4.0) oraz opcjonalny language.
  • Zwraca plik audio bezpośrednio w odpowiedzi HTTP.

GET /v1/voices

Zwraca listę dostępnych głosów, języków i formatów. Pozwala programistom na weryfikację dostępnych opcji przed wysłaniem żądania generowania.

GET /v1/models

Endpoint zwraca informacje o dostępnych modelach silnika TTS, umożliwiając weryfikację wersji API przed wdrożeniem.

Formaty wejściowe i wyjściowe

Ilustracja fali dźwiękowej dla: Formaty wejściowe i wyjściowe

API przyjmuje tekst do 4096 znaków w polu input. Spacje i znaki przeliczane są jako znaki. Dłuższe teksty należy podzielić na fragmenty i połączyć pliki audio po syntezie.

Otrzymujesz plik w wybranym formacie: MP3, WAV, OPUS, FLAC lub PCM. Wybór zależy od wymagań Twojego pipeline'u audiobooków. Każdy żądanie generuje jeden plik audio.

Tekst do 4096 znaków

Maksymalna długość tekstu w jednym żądaniu to 4096 znaków. Długość tekstu przekłada się bezpośrednio na koszt i czas generowania. Przy dłuższych rozdziałach audiobooków zalecamy podział na fragmenty i późniejsze połączenie wyników.

  • Limit: 4096 znaków na żądanie
  • Spacje i interpunkcja liczą się jako znaki
  • Wymagana jest obsługa po stronie klienta dla długich tekstów

Formaty audio MP3/WAV/OPUS/FLAC/PCM

Parametr response_format pozwala wybrać między MP3, WAV, OPUS, FLAC a PCM. Wybór zależy od potrzeb archiwizacji lub odtwarzania. Formaty stracone jak OPUS redukują wielkość pliku, podczas gdy FLAC zachowuje jakość bezstratną.

  • MP3: kompresja stratna, mała wielkość
  • WAV: bezstratny, standard branżowy
  • OPUS: efektywny, niski bitrate
  • FLAC: bezstratna kompresja
  • PCM: surowe dane audio

Prędkość 0.25–4.0

Parametr speed umożliwia regulację prędkości odczytu w zakresie od 0.25 do 4.0. Domyślna wartość to 1.0. Zmiana prędkości wpływa na czas generowania i charakterystykę głosu w pliku wyjściowym.

  • Zakres: 0.25–4.0
  • Domyślna wartość: 1.0
  • Wpływ na czas generowania

Obsługiwane języki

Ilustracja fali dźwiękowej dla: Obsługiwane języki

API automatycznie wykrywa język na podstawie użytego pisma. Tekst łaciński domyślnie jest interpretowany jako angielski, co wymaga jawnego określenia języka dla innych tekstów w tym alfabecie. Brak parametru może prowadzić do nieprecyzyjnej syntezy.

Parametr language (ISO code) wymusza konkretną wymowę niezależnie od skryptu. Wszystkie 8 głosów obsługuje pełną listę 23 dostępnych języków bez dodatkowych opłat.

Domyślne wykrywanie

System analizuje znaki wejściowe, aby przypisać domyślny język. Dla tekstu łacińskiego bazą jest angielski. Dla cyrylicy lub alfabetów azjatyckich system stosuje odpowiednie reguły językowe.

Parametr language

Jawne podanie kodu ISO (np. pl, de, ja) zapewnia poprawną intonację i akcent. Jest to zalecane dla tekstów w językach łacińskich innych niż angielski, takich jak polski czy hiszpański.

Lista 23 języków

Produkty wspierają następujące języki: arabski, chiński, duński, holenderski, angielski, fiński, francuski, niemiecki, grecki, hebrajski, hindi, włoski, japoński, koreański, malajski, norweski, polski, portugalski, rosyjski, hiszpański, suahili, szwedzki, turecki. Nieobsługiwane: wietnamski, indonezyjski, tajski, ukraiński, rumuński, czeski, bengalski oraz pozostałe.

Każdy z 8 presetów głosowych (ARIA, NOVA, LUNA, SAGE, FELIX, MILO, ATLAS, ORION) jest kompatybilny z każdym z wymienionych języków.

  • Arabic
  • Chinese
  • Danish
  • Dutch
  • English
  • Finnish
Obsługiwane języki

Autoryzacja

Ilustracja fali dźwiękowej dla: Autoryzacja

Klucze API zapewniają bezpieczny dostęp do endpointów. Każdy klucz jest unikalny dla konta i służy do uwierzytelniania żądań w środowisku produkcyjnym.

Nagłówek Authorization

W każdym żądaniu HTTP należy dołączyć nagłówek Authorization: Bearer <klucz>. Klucz musi być poprawny, aby usługa zwróciła plik audio lub metadane.

Format klucza Bearer

Klucze zaczynają się od prefiksu tts-. Są generowane automatycznie po rejestracji lub wystawieniu nowego tokenu.

Ważność klucza

W każdym momencie można wydać nowy klucz. Stażny klucz przestaje działać natychmiast po wystawieniu tokenu zastępczego, co zapewnia ciągłość bezpieczeństwa.

Limitowanie i wydajność

Ilustracja fali dźwiękowej dla: Limitowanie i wydajność

API obsługuje do 60 żądań na minutę na klucz. Przed pierwszą doładowaniem limit wynosi 10 żądań na minutę. Przekroczenie limitu zwraca błąd 429.

Żądania przetwarzane są sekwencyjnie. Przy dużym obciążeniu requests mogą czekać w kolejce, co wydłuża czas odpowiedzi. Standardowa szybkość generowania to około 25 znaków tekstu na sekundę wygenerowanego audio.

Limit 60 req/min

Domyślny limit to 60 żądań na minutę. Dla nowych kont bez doładowania limit wynosi 10 żądań na minutę. Przekroczenie skutkuje błędem 429 Too Many Requests.

Kolejkowanie żądań

Żądania są przetwarzane jedno po drugim. W przypadku dużego ruchu żądania mogą czekać w kolejce, co wydłuża całkowity czas odpowiedzi. Krótkie frazy generują się w kilka sekund.

Obsługa długich tekstów

Tekst przekraczający 4096 znaków należy podzielić na części. Każda część jest wysyłana osobno, a wygenerowane pliki audio są następnie łączone w jeden plik wynikowy.

Typowa szybkość generowania to około 25 znaków tekstu na sekundę wygenerowanego audio dla długich tekstów.

Obsługa błędów

Ilustracja fali dźwiękowej dla: Obsługa błędów

API zwraca standardowe kody HTTP, które pozwalają na precyzyjne zdiagnozowanie przyczyny awarii. Kluczowe jest rozróżnienie między błędami po stronie klienta a problemami z dostępnością usługi.

W przypadku nieudanej syntezy, środki są zwracane na konto w całości.

Kody statusu HTTP

Użyj kodów 400 dla błędów walidacji, 401 przy nieprawidłowym kluczu i 429 przy przekroczeniu limitu 60 żądań na minutę.

Kod 503 oznacza tymczasowy brak zasobów.

  • 400: Błędny format JSON lub brakujące pole input
  • 401: Nieprawidłowy lub wygasły token Authorization
  • 429: Przekroczono limit 60 żądań/min
  • 503: Serwer przeciążony, żądanie oczekuje w kolejce

Powrót środków

Jeśli synteza zakończy się niepowodzeniem, kwota jest zwracana w całości.

Środki pojawiają się na koncie natychmiast. Nie ma opłat za same próby wysłania żądania.

Logowanie błędów

Zalecamy logowanie pełnej odpowiedzi JSON, zawierającej kod błędu i szczegółowy komunikat.

W przypadku błędów 400 upewnij się, że tekst nie przekracza 4096 znaków i zawiera poprawny kod języka.

Posłuchaj 8 głosów

Każdą z poniższych próbek wygenerowano za pomocą tego API z tego samego zdania. Wygenerowane audio zwracane jest w odpowiedzi i nie jest przechowywane na serwerach.

Awatar głosu aria
ariażeński
Awatar głosu nova
novażeński
Awatar głosu luna
lunażeński
Awatar głosu sage
sageżeński
Awatar głosu felix
felixmęski
Awatar głosu milo
milomęski
Awatar głosu atlas
atlasmęski
Awatar głosu orion
orionmęski

23 języki

Każdy głos potrafi mówić w którymś z tych języków.

Źródła i dalsze lektury

  1. Wikipedia
  2. openai-node on GitHub
  3. openai-python on GitHub
  4. Python documentation
  5. MDN: Web Speech API
  6. FFmpeg documentation
  7. IETF RFC 7845: Ogg Opus
  8. LibriTTS-R corpus (OpenSLR 141)
  9. Creative Commons Attribution 4.0
  10. TRON developer hub: TRC-20
  11. Node.js documentation
  12. curl documentation

Więcej na tej stronie