Kompleksowy przewodnik po API Syntezy Mowy Fonogram

Przez Redakcja Fonogram · Zaktualizowano 2026-11-19

Ta dokumentacja zawiera konkretne instrukcje dotyczące integracji API Syntezy Mowy Fonogram z Twoimi projektami. Opisujemy tutaj wszystkie niezbędne parametry, dostępne głosy, formaty dźwięku oraz sposoby autoryzacji, abyś mógł szybko zamieniać tekst na mowę w swoim kodzie.

Przewodnik jest przeznaczony dla freelancerów i małych agencji reklamowych, które szukają taniego i szybkiego rozwiązania do tworzenia spotów radiowych czy lektorów do filmów. Znajdziesz tu gotowe przykłady w Pythonie i JavaScript, a także wyjaśnienia dotyczące limitów i błędów, bez zbędnego teoretyzowania.

Kompleksowy przewodnik po API Syntezy Mowy Fonogram

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.mp3

Python (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
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

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

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

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

Ilustracja fali dźwiękowej dla: 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

Ilustracja fali dźwiękowej dla: 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

Ilustracja fali dźwiękowej dla: 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

Ilustracja fali dźwiękowej dla: 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.

Błędy i Statusy

SDK OpenAI

Ilustracja fali dźwiękowej dla: 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

Ilustracja fali dźwiękowej dla: 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

Ilustracja fali dźwiękowej dla: 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.

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. MDN: Web Speech API
  3. Python documentation
  4. Creative Commons Attribution 4.0
  5. ISO 639 language codes
  6. OpenAI API reference: create speech
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. openai-node on GitHub
  9. W3C WAI: making audio and video accessible
  10. Tether (USDT)
  11. openai-python on GitHub
  12. LibriTTS-R corpus (OpenSLR 141)

Więcej na tej stronie