Najczęściej zadawane pytania
Jak uzyskać klucz API?
Klucz uzyskasz na stronie /get-api-key/, logując się przez Google lub tworząc konto z hasłem. Po rejestracji otrzymasz unikalny token Bearer, który wklejasz do nagłówka Authorization. Możesz wygenerować nowy klucz w dowolnym momencie, co natychmiast unieważnia poprzedni.
Jaki jest base URL dla SDK OpenAI?
Ustaw base_url na https://api.51519.net/v1. Dzięki temu oficjalne biblioteki OpenAI zadziałają bez zmian, po prostu podmieniając URL. Wysyłaj zapytania POST do /v1/audio/speech, używając tego samego formatu JSON co w standardowym endpoincie mowy.
Jakie są wspierane formaty plików audio?
Możesz wybrać format mp3, wav, opus, flac lub pcm w polu response_format. Wybór zależy od Twoich potrzeb transferowych i kompatybilności. Wszystkie pliki są zwracane jako gotowe do pobrania dane binarne w odpowiedzi na zapytanie POST.
Ile wynosi limit zapytań na minutę?
Limit wynosi 60 zapytań na minutę na klucz. Przed pierwszą wpłatą środki są ograniczone do 10 zapytań na minutę. Limit ten dotyczy wszystkich zapytań wysyłanych przez dany klucz API, niezależnie od modelu lub głosu.
Czy API wspiera streaming?
Nie, API nie wspiera streaming ani WebSocket. Otrzymujesz pełny plik audio po zakończeniu przetwarzania. Żądania są przetwarzane sekwencyjnie, więc przy dużym obciążeniu może wystąpić kolejka. Nie ma dostępu do częściowego strumienia audio w czasie rzeczywistym.
Jakie są dostępne modele (tts-1, tts-1-hd)?
Dostępne są modele tts-1 i tts-1-hd. Oba używają tego samego silnika i mają identyczną cenę. Wybór modelu nie wpływa na koszt ani jakość głosu, a jedynie na nazwę w zapytaniu. Możesz użyć dowolnego z nich bez dodatkowych opłat.
Jak zmienić prędkość wypowiedzi?
Użyj pola speed w zakresie od 0.25 do 4.0. Wartość 1.0 oznacza normalną prędkość. Możesz przyspieszyć lub zwolnić syntezę, dostosowując tempo do tempa filmu lub audycji. Zmiana prędkości nie wpływa na koszt ani liczbę znaków.
Jak zwrócić błąd przy nieudanym requeste?
Nieudane zapytania są darmowe. Jeśli synteza się nie powiedzie, kwota zostanie zwrócona w całości na Twoje konto. Odpowiedź zawiera informację o błędzie, ale nie obciąża ona Twojego salda. Możesz bezpiecznie ponowić zapytanie bez ryzyka dodatkowych kosztów.
Czy mogę użyć własnego klucza API?
Każde konto ma jeden aktywny klucz API. Możesz go wygenerować ponownie w dowolnym momencie na stronie zarządzania kontem. Stary klucz przestaje działać natychmiast po wydaniu nowego. Nie ma możliwości posiadania wielu kluczy jednocześnie w ramach jednego konta.
Jakie jest maksymalne długość tekstu?
Maksymalna długość tekstu w jednym zapytaniu to 4096 znaków. Dłuższe teksty należy podzielić na części i połączyć pliki audio. Spacje i interpunkcja liczą się jako znaki. Limit ten dotyczy treści wejściowej w polu input.
Czy API zwraca metadane?
API zwraca wygenerowany plik audio. Metadane takie jak czas, liczba znaków i status są przechowywane po stronie serwera do celów rozliczeniowych. Nie są one zwracane bezpośrednio w odpowiedzi HTTP jako osobny obiekt JSON. Sprawdź panel użytkownika po szczegóły.
Jak zintegrować z Pythonem?
Użyj oficjalnego pakietu openai. Ustaw base_url na https://api.51519.net/v1 i podaj swój klucz w nagłówku autoryzacji lub zmiennej api_key. Wywołaj client.audio.speech.create() z odpowiednim tekstem i głosem. Biblioteka obsłuży wysyłanie zapytania i zapis pliku audio.
Jak zintegrować z JavaScriptem?
Wyślij zapytanie POST do https://api.51519.net/v1/audio/speech za pomocą fetch. Ustaw nagłówek Authorization z tokenem Bearer. Przekaż tekst w ciele JSON. Odpowiedź zawiera plik audio, który możesz zapisać lub odtworzyć bezpośrednio w przeglądarce lub Node.js.
Czy jest dostępny webhook?
Nie, API nie obsługuje webhooków. Zapytania są przetwarzane synchronicznie, a odpowiedź zawiera gotowy plik audio. Nie ma mechanizmu powiadomień o zakończeniu przetwarzania w tle. Musisz czekać na odpowiedź HTTP, aby uzyskać wynik syntezy.
Pierwsze żądanie
curl
curl https://api.51519.net/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.51519.net/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.51519.net/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 |
Szybki Start
Zacznij od rejestracji na /get-api-key/ w celu uzyskania unikalnego klucza API. Umożliwi Ci to natychmiastowy dostęp do syntezatora mowy, z którego będziesz korzystać przy tworzeniu tekstów do filmów i spotów radiowych.
Uzyskanie klucza API
Rejestracja odbywa się poprzez Google lub e-mail. Po założeniu konta otrzymujesz klucz w formacie tts-..., który jest jedynym elementem potrzebnym do autoryzacji w nagłówku Authorization: Bearer. Możesz go wydać ponownie, jeśli zostanie użyty niezgodnie z oczekiwaniami.
Pierwsze zapytanie
Wyślij zapytanie POST na https://api.51519.net/v1/audio/speech z tekstem do 4096 znaków. Wybierz model tts-1 lub tts-1-hd oraz odpowiedni głos. Otrzymasz plik audio w wybranym formacie (mp3, wav, opus, flac, pcm) w cenie 0,01 USD za 1000 znaków.
Test integracji
Po rejestracji z Google otrzymasz darmowy próg 0,50 USD (ok. 50 000 znaków) ważny przez 7 dni. Wykorzystaj go do przetestowania szybkości generowania i jakości głosu bez ryzyka obciążenia portfela.
Konfiguracja
Aby zintegrować syntezę mowy Fonogram ze swoim projektem, musisz znać podstawowe punkty końcowe i sposób uwierzytelniania. Interfejs API jest zaprojektowany tak, aby był kompatybilny z istniejącymi narzędziami, co upraszcza wdrożenie w środowisku agencji reklamowych.
Endpointy
Głównym punktem końcowym jest POST /v1/audio/speech, który przyjmuje tekst i zwraca wygenerowany plik audio. Dodatkowe endpointy GET /v1/voices i GET /v1/models pozwalają sprawdzić dostępne opcje i konfiguracje przed wysłaniem zapytania.
Autoryzacja
Każde zapytanie musi zawierać nagłówek Authorization: Bearer <TWÓJ_KLUCZ>. Klucz generujesz na stronie rejestracji i jest on przypisany do Twojego konta. Możesz go zaktualizować w dowolnym momencie, co natychmiast unieważnia poprzedni.
Base URL
Podstawowy adres dla wszystkich zapytań to https://api.51519.net/v1. Jeśli korzystasz z oficjalnych SDK OpenAI, wystarczy zmienić pole base_url na ten adres, aby używać naszych usług bez modyfikacji struktury żądań.
Polecenia
Dokumentacja opisuje dostępne modele syntezy oraz ograniczenia, które pomagają zaplanować budżet i wydajność integracji.
Wszystkie wartości oparte są na aktualnej specyfikacji API Fonogram.
Głosy
API udostępnia 8 presetów głosu, które obsługują 23 języki. Każdy głos może speak dowolny język z listy, np. aria do narracji czy atlas do wiadomości.
Jeśli nie podasz kodu języka, system zgaduje go na podstawie tekstu (domyślnie angielski dla tekstu łacińskiego). Dla innych języków łacińskich ustaw język ręcznie.
- 8 głosów (aria, nova, luna, sage, felix, milo, atlas, orion)
- 23 wspierane języki
- Wymuszane dla tekstów nieangielskich w alfabecie łacińskim
Modele
Dostępne są dwa modele: 'tts-1' oraz 'tts-1-hd'. Obie wersje korzystają z tego samego silnika i mają identyczną cenę.
Wybór modelu nie wpływa na format wyjściowy domyślny, koszt ani jakość syntezacji.
Limity
Obowiązuje limit 60 zapytań na minutę na klucz (lub 10 na minutę przed pierwszym doładowaniem).
Tekst musi mieć maksymalnie 4096 znaków na jedno zapytanie. Dłuższe teksty należy podzielić i scalić w aplikacji.
Formaty Wbudowane
Aplikacja API Fonogram obsługuje pięć formatów wyjściowych, w tym MP3, WAV oraz Opus. Wybór zależy od Twoich potrzeb: MP3 zapewnia uniwersalną kompatybilność, WAV zachowuje pełną jakość bez strat, a Opus oferuje wysoką efektywność kompresji przy małym rozmiarze pliku. Opus jest szczególnie zalecany do przesyłania danych w warunkach ograniczonego łącza internetowego.
Oprócz wymienionych dostępny jest również FLAC oraz PCM dla specyficznych zastosowań. Wszystkie formaty są generowane natychmiast po przetworzeniu tekstu, co pozwala na szybkie wdrożenie głosu do spotów radiowych lub filmów reklamowych bez dodatkowych konwersji.
MP3
MP3 to najbardziej uniwersalny format audio, wspierany przez większość odtwarzaczy i platform mediów społecznościowych. Zapewnia dobre proporcje jakości do rozmiaru pliku, co czyni go idealnym wyborem do montażu wideo i reklam online.
- Kompresja stratna z zachowaniem wysokiej czytelności mowy.
- Szeroka kompatybilność z narzędziami edycyjnymi.
WAV
WAV to format bezstratny, który zachowuje pełną jakość dźwięku z generowania. Jest optymalny, gdy planujesz dalszą obróbkkę audio w profesjonalnym programie montażowym lub gdy wymagana jest maksymalna wierność sygnału.
- Brak utraty jakości podczas zapisu.
- Idealny do profesjonalnego edytorstwa radiowego.
Opus
Opus to nowoczesny format o wysokiej efektywności kompresji, zapewniający świetną jakość przy małym rozmiarze pliku. Jest szczególnie zalecany do przesyłania danych w warunkach ograniczonego łącza internetowego. Pozwala na szybkie przesyłanie nagrania do serwerów lub odtwarzanie na urządzeniach mobilnych przy niskim zużyciu danych.
- Niski współczynnik rozmiaru pliku.
- Wysoka efektywność kompresji dla mowy.
Błędy i Statusy
API Fonogram zwraca standardowe kody HTTP, informujące o stanie Twozego żądania. Zrozumienie tych kodów pomaga szybko diagnozować problemy z integracją, od błędów autoryzacji po niepoprawne formaty danych.
Kody błędów
Zwracane kody 4xx oznaczają błędy po stronie klienta, np. nieprawidłowy klucz API lub brakujące parametry. Kody 5xx wskazują na tymczasowe problemy serwera. W przypadku nieudanej syntezy, opłaty nie naliczamy, a kwota zostaje zwrócona na saldo konta.
- 400 Bad Request – niepoprawna składnia JSON
- 401 Unauthorized – błędny lub brakujący klucz API
- 413 Payload Too Large – tekst przekracza 4096 znaków
- 500 Internal Server Error – błąd po stronie serwera
Przekroczenie limitu
Limit wynosi 60 zapytań na minutę na klucz (10 na minutę przed pierwszym doładowaniem). Jeśli przekroczysz próg, otrzymasz kod 429 Too Many Requests. System nie obcina kosztu za przekroczenie, ale żądania są odrzucane do chwili opóźnienia.
- 60 req/min dla kont z saldem
- 10 req/min dla kont bez doładowania
- Kod 429 przy przekroczeniu limitu
Retry
Zalecamy implementację mechanizmu ponownych prób z wykładniczym wzrostem opóźnienia (exponential backoff). Przy kodach 500 lub 429 odczekaj kilka sekund przed ponownym wysłaniem żądania. Dzięki temu unikasz zatłoczenia serwera w trakcie wzmożonego ruchu.

SDK OpenAI
Fonogram API jest w pełni kompatybilne ze standardem OpenAI, co pozwala wykorzystać oficjalne biblioteki SDK bez konieczności pisania własnych warstw abstrakcji. Wystarczy jedynie zmiana adresu bazowego (base_url) na https://api.51519.net/v1 i użycie klucza API Fonogram w nagłówku autoryzacji.
Dzięki temu rozwiązaniu freelancerzy i agencje reklamowe mogą szybko zintegrować syntezę mowy z istniejącymi pipeline’ami produkcyjnymi, wykorzystując znane już narzędzia do generowania plików audio dla spotów radiowych i filmów.
Konfiguracja base_url
Aby połączyć się z naszym serwisem, zainstaluj odpowiednią bibliotekę OpenAI i ustaw parametr base_url na https://api.51519.net/v1. Użyj swojego klucza API Fonogram w nagłówku Authorization: Bearer <klucz>. Struktura żądania JSON jest identyczna jak w standardowym endpointzie mowy OpenAI.
- Zainstaluj bibliotekę openai (np. pip install openai lub npm install openai)
- Ustaw base_url: 'https://api.51519.net/v1'
- Użyj klucza API z panelu /get-api-key/
Przykłady w Pythonie
Poniższy kod Pythona demonstruje wysłanie tekstu do syntezy. Skrypt konfiguruje klienta do pracy z naszym API, ustawia model tts-1-hd oraz głos nova. Wynikowy plik audio jest zapisywany lokalnie jako MP3.
- import openai
- client = openai.OpenAI(base_url='https://api.51519.net/v1', api_key='tts-...')
- response = client.audio.speech.create(model='tts-1-hd', voice='nova', input='Dzień dobry, to jest test.', response_format='mp3')
- with open('spot.mp3', 'wb') as f: f.write(response.content)
Przykłady w JS
W środowisku Node.js lub przeglądarki konfiguracja jest analogiczna. Utwórz instancję klienta, podając bazowy URL i klucz. Metoda audio.speech.create przyjmuje tekst, preferowany format (np. mp3) oraz parametry takie jak prędkość czy głos, zwracając pełny plik audio.
- const { OpenAI } = require('openai');
- const client = new OpenAI({ baseURL: 'https://api.51519.net/v1', apiKey: 'tts-...' });
- const response = await client.audio.speech.create({ model: 'tts-1', voice: 'felix', input: 'Sprzedaż rusza!' });
- const buffer = Buffer.from(await response.arrayBuffer());
Parametry Zapytania
Każde zapytanie do API wymaga precyzyjnego określenia modelu, głosu i prędkości odtwarzania. Wybór tych parametrów determinuje brzmienie finalnego pliku audio oraz zużycie znaków, które są rozliczane według stawki $0,01 za 1000 znaków.
Prawidłowa konfiguracja tych pól jest kluczowa dla efektywnej integracji w Twoich kampaniach reklamowych. Poniżej znajdziesz szczegółowy opis dostępnych opcji i ich wpływu na finalny wynik syntezacji.
Model
API obsługuje dwa modele: "tts-1" oraz "tts-1-hd". Obie wersje korzystają z tego samego silnika syntezacji, co oznacza identyczną jakość głosu i tę samą cenę za znak.
Voice
Możesz wybrać jeden z 8 dostępnych presetów głosowych. Dostępne są głosy żeńskie (Aria, Nova, Luna, Sage) oraz męskie (Felix, Milo, Atlas, Orion). Każdy głos może wypowiedzieć dowolny z 23 obsługiwanych języków, w tym angielski, polski, niemiecki czy hiszpański.
- Aria: ciepły, klarowny narrator
- Felix: energetyczny, idealny do reklam
Speed
Parametr prędkości pozwala na regulację tempa wypowiedzi w zakresie od 0.25 do 4.0. Domyślna prędkość odpowiada naturalnemu rytmowi mowy. Zmiana tej wartości wpływa na długość pliku audio, ale nie zmienia liczby pobranych znaków.
Przykłady Kodu
Gotowe przykłady kodu pozwalają szybko zintegrować syntezę mowy z Twoimi projektami reklamowymi. Użyj odpowiedniej wersji językowej, aby wygenerować plik audio w zalecanym formacie.
Curl
Wyślij zapytanie POST, podając klucz i tekst. Otrzymasz plik audio w odpowiedzi.
- curl -X POST https://api.51519.net/v1/audio/speech -H "Authorization: Bearer tts-..." -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Witaj świecie", "voice": "nova"}'
Python
Zmodyfikuj base_url w bibliotece OpenAI, aby połączyć się z naszym endpointem.
- client = OpenAI(base_url="https://api.51519.net/v1", api_key="tts-...")
JavaScript
Użyj oficjalnego pakietu openai, ustawiając niestandardowy bazowy URL.
- const openai = new OpenAI({ apiKey: "tts-...", basePath: "https://api.51519.net/v1" });
Posłuchaj 8 głosów
Każdą z poniższych próbek wygenerowano za pomocą tego API z tego samego zdania. Sama treść głosu ani tekst źródłowy nie są archiwizowani po zakończeniu transakcji.
23 języki
Każdy głos potrafi mówić w którymś z tych języków.
Źródła i dalsze lektury
- Wikipedia
- MDN: Web Speech API
- Python documentation
- Creative Commons Attribution 4.0
- ISO 639 language codes
- OpenAI API reference: create speech
- LibriTTS-R paper (arXiv 2305.18802)
- openai-node on GitHub
- W3C WAI: making audio and video accessible
- Tether (USDT)
- openai-python on GitHub
- LibriTTS-R corpus (OpenSLR 141)
