Dokumentacja API syntezatora mowy dla twórców VTuberów

Przez Zespół redakcyjny GlosGamer · Zaktualizowano 2026-11-19

Dokumentacja opisuje sposób integracji API syntezatora mowy GlosGamer z Twoimi aplikacjami. Dowiesz się, jak wysyłać tekst i otrzymywać gotowe pliki audio przez prosty endpoint HTTP. Wszystkie żądania mają strukturę zgodną z OpenAI, więc wystarczy zmienić adres bazowy w istniejących bibliotekach.

Strona przeznaczona jest dla twórców VTuberów i streamerów, którzy potrzebują niezawodnego narzędzia do generowania mowy postaci. Znajdziesz tutaj konkretne przykłady kodu, parametry głosów, formatów i informacji o limitach. Dzięki temu szybko uruchomisz syntezę w swoim workflow bez zbędnych komplikacji.

Dokumentacja API syntezatora mowy dla twórców VTuberów

Najczęściej zadawane pytania

Jak wygenerować klucz API na stronie?

Klucz uzyskujesz na stronie /get-api-key/ po rejestracji przez Google lub e-mail. System wyświetla Twój unikalny token Bearer, saldo oraz przykładowe żądanie curl. Każdy kont posiada jeden aktywny klucz; możesz go natychmiast zmienić, co unieważnia poprzedni.

Czy mogę użyć biblioteki OpenAI dla tego API?

Tak, interfejs jest zgodny z endpointem OpenAI. Wystarczy zmienić base_url na https://api.vt338.info/v1 i użyć swojego klucza. Oficjalne biblioteki OpenAI działają bez modyfikacji, obsługując standardowe parametry modelu, głosu, formatu i prędkości syntezowania.

Jakie są typowe kody błędów w odpowiedzi?

Wiadomo jedynie, że nieudane żądania są darmowe, a kwota jest zwracana w pełnej wysokości.

Czy limit 60 żądań na minutę jest na konto czy na klucz?

Limit 60 żądań na minutę dotyczy pojedynczego klucza API. Przed pierwszą doładowaniem limit wynosi 10 żądań na minutę na klucz. Ponieważ na konto przypisany jest tylko jeden aktywny klucz, limit ten effectively ogranicza całe konto użytkownika.

Jak przesłać tekst dłuższy niż 4096 znaków?

Musisz samodzielnie podzielić tekst na fragmenty o długości maksymalnie 4096 znaków. Wyślij każdy fragment osobno do endpointu, a następnie połącz wygenerowane pliki audio w jeden plik końcowy. System nie obsługuje automatycznego dzielenia dłuższych treści w jednym żądaniu.

Czy endpoint zwraca stream czy plik końcowy?

Endpoint zwraca gotowy plik audio, a nie strumień. Nie ma obsługi streamingu, WebSocket ani częściowego audio. Żądania są przetwarzane sekwencyjnie, więc przy dużym obciążeniu odpowiedź może opóźnić się w kolejce, ale zwracany jest pełny plik.

Jak zmienić domyślny język w żądaniu?

W polu language w ciele żądania JSON podaj kod ISO języka (np. "pl"). Jeśli pole pominiemy, system zgaduje język na podstawie pisma (dla łaciny domyślnie angielski). Dla tekstów łacińskich w innych językach ustawienie language jest konieczne.

Czy mogę użyć klucza na wielu serwerach?

Tak, klucz API jest unikalny dla konta i może być używany z dowolnej liczby serwerów lub aplikacji. Klucz jest wysyłany w nagłówku Authorization. Nie ma ograniczeń liczby instancji, ale limit 60 żądań na minutę dotyczy łącznie wszystkich użyci klucza.

Jak sprawdzić dostępność głosów przez API?

Wyślij żądanie GET do endpointu /v1/voices. Odpowiedź zwróci listę dostępnych głosów, języków, formatów oraz informacji o cenie. Możesz tam znaleźć osiem presetów głosu dostępnych do użycia w żądaniach syntezowania mowy.

Czy requesty są przetwarzane synchronicznie?

Żądania są przetwarzane jedno po drugim (sekwencyjnie). Przy dużym obciążeniu request może czekać w kolejce. Typowa prędkość to ok. 25 znaków na sekundę, więc krótkie frazy generują się w kilka sekund, a dłuższe teksty w czasie rzeczywistym.

Jak zaimplementować ponawianie żądań?

Implementacja zależy od Twojej warstwy aplikacyjnej. Ponawiaj żądania w przypadku błędów sieciowych lub przekroczenia limitu. Pamiętaj, że nieudane syntezy są darmowe. Przy sekwencyjnym przetwarzaniu uwzględnij opóźnienia wynikające z kolejki, stosując wykładnicze backoff między próbami.

Jakie jest maksymalne rozmiary pliku WAV?

Fakty produktowe nie określają maksymalnego rozmiaru pliku WAV. Limit dotyczy liczby znaków wejściowych (4096 na żądanie), a nie wielkości wyjściowego pliku. Rozmiar pliku zależy od długości tekstu, prędkości i formatu. Nie ma podanego górnego limitu rozmiaru pliku.

Czy API zwraca metadane o czasie generowania?

Przechowywane są metadane żądania (czas, znaki, status) do rozliczeń.

Jak odzyskać klucz jeśli go zgubię?

Klucz możesz wydać ponownie na stronie /get-api-key/ po zalogowaniu. Nowy klucz staje się aktywny natychmiast, a stary przestaje działać w tym samym momencie. Nie ma mechanizmu odzyskiwania starego klucza; generujesz nowy token dla tego samego konta.

Pierwsze żądanie

curl

curl https://api.vt338.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.vt338.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.vt338.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

Pierwsze kroki

Ilustracja fali dźwiękowej dla: Pierwsze kroki

Zacznij od rejestracji na /get-api-key/, wybierając logowanie przez Google lub e-mail. Po zalogowaniu otrzymasz unikalny klucz API oraz dostępne środki. Klucz jest jedyny w trakcie sesji, a jego natychmiastowa wymiana blokuje poprzedni.

Każde żądanie musi zawierać nagłówek "Authorization: Bearer tts-...". Umożliwia to bezpieczne uwierzytelnienie Twoich żądań do silnika syntezatora. Bez prawidłowego klucza endpoint zwróci błąd autoryzacji.

Generowanie klucza API

Generowanie klucza API

Rejestracja odbywa się na stronie /get-api-key/. Użytkownicy logujący się przez Google otrzymają natychmiastową dotację próbną w wysokości 0,50 USD. Konta tworzone wyłącznie emailem nie posiadają początkowego kredytu.

  • Logowanie przez Google lub e-mail
  • Automatyczne przyznanie kredytu próbnego (tylko Google)
  • Jeden aktywny klucz na konto

Autoryzacja żądań

Autoryzacja żądań

Używaj nagłówka Authorization z prefiksem Bearer. Klucz zaczyna się od "tts-". Każdy nowy klucz unieważnia poprzedni natychmiast po wydaniu.

  • Nagłówek: Authorization: Bearer tts-...
  • Format: standardowy token Bearer
  • Wymiana klucza: natychmiastowa

Podstawowy endpoint

Wysyłaj żądania POST do https://api.vt338.info/v1/audio/speech. To główny punkt końcowy generowania mowy z tekstu do audio.

Żądanie musi zawierać model, tekst wejściowy oraz preferowany format wyjściowy. Odpowiedzią jest plik audio w wybranym formacie.

  • Metoda: POST
  • URL: /v1/audio/speech
  • Format wejścia: JSON

Struktura żądania

Ilustracja fali dźwiękowej dla: Struktura żądania

Interfejs API akceptuje tekst do syntezy w polu input, z limitem 4096 znaków na jedno żądanie. Każdy znak, wliczając spacje i interpunkcję, liczy się do rozliczenia. Dla dłuższych tekstów należy podzielić je na fragmenty i połączyć wygenerowane pliki audio.

Model tts-1 i tts-1-hd korzystają z tego samego silnika, więc jakość dźwięku jest identyczna, a cena wynosi $10 za milion znaków. Wybór modelu nie wpływa na koszt ani parametry głosu.

Pole input i maksymalna długość

Parametr input przyjmuje ciąg znaków do przetworzenia. Maksymalna długość to 4096 znaków. Jeśli tekst przekracza ten limit, należy go podzielić na mniejsze części i połączyć wynikowe pliki audio w całość.

  • Limit: 4096 znaków na żądanie
  • Każdy znak (w tym spacje) liczy się do rozliczenia
  • Wymagane jest ręczne łączenie fragmentów dla dłuższych tekstów

Wybór modelu tts-1 lub tts-1-hd

Oba modele (tts-1, tts-1-hd) generują audio o identycznej jakości, korzystając z tego samego silnika. Różnią się jedynie nazwą w żądaniu, ale nie wpływają na cenę ani czas generowania. Wybór zależy od preferencji w kodzie.

  • Oba modele mają tę samą cenę: $10/1 mln znaków
  • Jakość dźwięku jest identyczna
  • Wybór jest dowolny i nie ma wpływu na wynik

Parametr voice i język

Wybierz jeden z 8 presetów głosu, takich jak Aria czy Felix. Parametr language jest opcjonalny; jeśli nie zostanie ustawiony, język jest domyślnie rozpoznawany na podstawie skryptu (domyślnie angielski dla tekstu łacińskiego). Dla innych języków zalecamy jawną definicję kodu ISO.

Głosy są uniwersalne i mogą mówić każdym z 23 obsługiwanych języków. Nie ma przypisania głosu do konkretnego języka.

  • 8 presetów: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion
  • Wspierane języki: 23, w tym polski, angielski, niemiecki
  • Parametr language opcjonalny; domyślnie angielski dla skryptu łacińskiego

Formaty wyjściowe

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

Wybór formatu wyjściowego wpływa na balans między jakością a zużyciem zasobów. Możesz wybrać między MP3, WAV, OPUS, FLAC i PCM, dostosowując wynik do potrzeb Twojej aplikacji lub streamu.

MP3 dla małego rozmiaru pliku

MP3 to najbardziej uniwersalny format, idealny do szybkiego przesyłania plików audio przez sieć. Zapewnia dobrą jakość przy minimalnym rozmiarze pliku, co oszczędza transfer i pamięć.

  • Najmniejszy rozmiar pliku spośród formatów stratnych
  • Szerokie wsparcie we wszystkich odtwarzaczach i aplikacjach

WAV do wysokiej jakości

Format WAV zapewnia bezstratną jakość dźwięku, co jest kluczowe przy edycji nagrań lub archiwizacji. Nie ma utraty danych, więc syntezowana mowa brzmi dokładnie tak, jak wygenerowano.

  • Bezstratna kompresja zachowująca każdy detal głosu
  • Idealny do dalszej obróbki w edytorach audio

OPUS i FLAC dla streamów

OPUS i FLAC oferują zaawansowane opcje dla zaawansowanych użytkowników. FLAC zapewnia bezstratną kompresję, a OPUS jest zoptymalizowany pod kątem transmisji strumieniowej przy niskim zużyciu pasma.

  • FLAC: bezstratna kompresja, mniejszy rozmiar niż WAV
  • OPUS: zoptymalizowany pod kątem transmisji przy niskim zużyciu pasma

Prędkość generowania

Ilustracja fali dźwiękowej dla: Prędkość generowania

Parametr speed pozwala dostosować tempo syntezacji do potrzeb Twojej postaci, przyjmując wartości od 0.25 do 4.0. Zmniejszenie prędkości może nadać głosu bardziej dramatyczny charakter, natomiast przyspieszenie jest przydatne przy szybkich reakcjach.

Zakres 0.25 do 4.0

Możesz precyzyjnie kontrolować tempo wypowiedzi, wpisując wartość numeryczną w żądaniu API. Domyślne ustawienie to 1.0, ale zakres od ćwierć zwolnienia do czterokrotnego przyspieszenia daje pełną kontrolę nad dynamiką głosu.

Szacowany czas generowania

Długie teksty generują się w przybliżeniu w czasie rzeczywistym, co odpowiada około 25 znakom tekstu na sekundę dźwięku. Krótkie frazy wymagają kilku sekund na przetworzenie, nawet przy niskim obciążeniu serwera.

Kolejkowanie żądań

Żądania są przetwarzane sekwencyjnie, co oznacza, że pod wysokim obciążeniem Twoje żądanie może trafić do kolejki. Limit wynosi 60 żądań na minutę na klucz.

Obsługa błędów

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

API zwraca konkretne kody błędów, które umożliwiają szybkie zdiagnozowanie problemu. Najczęstszym błędem jest 401 Unauthorized, pojawiający się przy nieprawidłowym kluczu API. Warto regularnie sprawdzać panel, aby wygenerować nowy klucz, jeśli stary został skompromitowany.

Przy przekroczeniu limitu 4096 znaków w jednym żądaniu otrzymasz błąd 400. Rozdziel tekst na mniejsze fragmenty i połącz je w skrypcie. Błędy serwera (5xx) oznaczają chwilową niedostępność; żądanie jest wtedy zwalniane bez pobierania środków.

Błędy autoryzacji

Kod 401 oznacza, że klucz jest nieprawidłowy lub usunięto go po wydaniu nowego. Klucz należy podawać w nagłówku Authorization: Bearer.

  • Sprawdź poprawność klucza w panelu /get-api-key/
  • Wygeneruj nowy klucz, jeśli stary przestał działać

Przekroczenie limitu znaków

Pole input nie może przekraczać 4096 znaków. Przekroczenie powoduje odrzucenie żądania.

Podziel dłuższe teksty na mniejsze fragmenty w kodzie przed wysłaniem.

Błędy serwera i zwrot środków

Przy nieudanych żądaniach środki są zwracane w pełni. Nie musisz robić nic ręcznie.

Niepobierane środki pojawiają się na koncie automatycznie w ciągu kilku minut.

  • Sprawdź status w panelu
  • Czekaj na automatyczny zwrot
Obsługa błędów

Integracja z OpenAI SDK

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

Skorzystaj z oficjalnych bibliotek OpenAI, zmieniając jedynie parametr base_url na https://api.vt338.info/v1. Dzięki temu zachowujesz znany interfejs API, a żądania trafiają do naszego syntezatora.

Biblioteki obsługują standardowe parametry: model, głos, format dźwięku i prędkość. Nie musisz pisać własnej logiki połączeń HTTP, co przyspiesza integrację z Twoimi narzędziami do streamingu.

Zmiana base_url

W ustawieniach klienta biblioteki OpenAI podaj adres https://api.vt338.info/v1. Klucz API generujesz na stronie /get-api-key/ i przypisujesz go do zmiennej środowiskowej OPENAI_API_KEY lub przekazujesz bezpośrednio.

Użycie oficjalnych bibliotek

Oficjalne biblioteki OpenAI działają po zmianie base_url, obsługując standardowe parametry modelu, głosu, formatu i prędkości syntezowania. Działa to zarówno z clientem synchronicznym, jak i asynchronicznym, co jest kluczowe dla płynnych streamów w czasie rzeczywistym.

Przykład w Pythonie

Zainstaluj pakiet openai. W kodzie inicjalizuj klienta z nadpisanym base_url. Wywołaj metodę audio.speech.create(), podając tekst, wybrany głos (np. 'nova') i format 'mp3'. Otrzymasz binarną odpowiedź do zapisu pliku.

Pamiętaj, że tekst musi mieścić się w limicie 4096 znaków na jedno żądanie. Dla dłuższych tekstów podziel je logicznie w swoim kodzie przed wysłaniem.

Przykład z linii poleceń

Ilustracja fali dźwiękowej dla: Przykład z linii poleceń

Najprostszy sposób na przetestowanie syntezatora to użycie komendy curl w terminalu. Pozwala ona na bezpośrednie wysłanie żądania POST do endpointu /v1/audio/speech bez konieczności instalowania dodatkowych bibliotek.

Przykład poniżej ilustruje minimalną konfigurację potrzebną do wygenerowania pliku audio. Pamiętaj, aby zastąpić YOUR_API_KEY swoim kluczem z panelu /get-api-key/.

Komenda curl

Wyślij tekst do API, używając flagi -X POST. W ciele żądania (body) przekaż model, wybrany głos oraz sam tekst do syntezy. Wymagany jest nagłówek Authorization z Twoim kluczem API.

  • Zmień YOUR_API_KEY na właściwy klucz
  • Dostosuj parametr voice do dostępnych presetów
  • Zmień input na dowolny tekst do 4096 znaków

Odczyt odpowiedzi binarnej

API zwraca surowy strumień audio w odpowiedzi HTTP. Domyślnie curl wyświetla te dane binarne bezpośrednio w terminalu, co może wyglądać jak losowe znaki. Jest to poprawne zachowanie potwierdzające sukces żądania.

Zapis do pliku audio

Aby zapisać plik, przekaż wynik do przekierowania lub użyj flagi -o. Wymaga to określenia formatu wyjściowego (np. mp3) w parametrze response_format. Plik będzie gotowy do natychmiastowego użycia w strumieniu.

Listy głosów i modeli

Ilustracja fali dźwiękowej dla: Listy głosów i modeli

Dokumentacja API syntezatora mowy dla twórców VTuberów. Listy głosów i modeli

Endpoint /v1/voices

Wywołanie GET /v1/voices zwraca listę dostępnych syntezatorów, ich języków i formatów. Każdy głos obsługuje 23 języki, w tym polski i angielski, bez konieczności ręcznego ustawiania kodu języka, choć zalecamy jego jawną specyfikację dla tekstów łacińskich innych niż angielski.

  • GET /v1/voices

Endpoint /v1/models

Endpoint GET /v1/models zwraca dostępne silniki syntezacji. Obecnie są dostępne dwa modele: tts-1 i tts-1-hd. Oba używają tego samego silnika i mają identyczną cenę, różniąc się jedynie wewnętrznymi parametrami jakości.

Dostępne parametry każdego głosu

Każdy z 8 presetów (np. Aria, Nova, Felix) ma unikalny ton, ale wszystkie generują audio w formatach MP3, WAV, OPUS, FLAC i PCM. Prędkość można regulować w zakresie 0.25–4.0, a tekst ograniczony jest do 4096 znaków na żądanie.

  • 8 presetów głosów
  • 23 obsługiwane języki
  • Formaty: MP3, WAV, OPUS, FLAC, PCM

Posłuchaj 8 głosów

Każdą z poniższych próbek wygenerowano za pomocą tego API z tego samego zdania. Brzmienie jest ciepłe, ale nie przesadnie emocjonalne, co zapobiega zmęczeniu słuchaczy podczas długich sesji rozmowy.

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. Python documentation
  3. Tether (USDT)
  4. MDN: Web Speech API
  5. IETF RFC 7845: Ogg Opus
  6. W3C WAI: making audio and video accessible
  7. openai-python on GitHub
  8. LibriTTS-R corpus (OpenSLR 141)
  9. ISO 639 language codes
  10. Node.js documentation
  11. FFmpeg documentation
  12. Creative Commons Attribution 4.0

Więcej na tej stronie