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.mp3Python (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 |
felix | męski |
milo | męski |
atlas | męski |
orion | męski |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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ń
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
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
languageopcjonalny; domyślnie angielski dla skryptu łacińskiego
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
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
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

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ń
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
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.
23 języki
Każdy głos potrafi mówić w którymś z tych języków.
