Kompletna dokumentacja API syntezatora mowy

Przez redakcja VoxNieruchomosci · Zaktualizowano 2026-11-19

Dokumentacja API VoxNieruchomosci zawiera pełny opis endpointów, parametrów i przykładów kodu potrzebnych do zintegrowania syntezatora mowy z systemem agencji nieruchomości. Opisano tu strukturę żądań, autoryzację Bearer, obsługę błędów oraz specyficzne ograniczenia, takie jak limit 60 żądań na minutę i konieczność ręcznego podziału dłuższych opisów nieruchomości.

Strona przeznaczona jest dla programistów i inżynierów odpowiedzialnych za automatyzację produkcji treści do wirtualnych tur. Znajdziesz tu konkretne dane techniczne: dostępne formaty audio (MP3, WAV, Opus, FLAC, PCM), listę 8 głosów, obsługę 23 języków oraz zasady generowania kluczy API. Przykłady kodu w curl i konfiguracja SDK OpenAI pozwalają na szybkie wdrożenie rozwiązania bez zbędnych dygresji.

Kompletna dokumentacja API syntezatora mowy

Najczęściej zadawane pytania

Jak uzyskać klucz API?

Klucz uzyskasz na stronie /get-api-key/ po rejestracji przez Google lub email. Posiadasz jeden aktywny klucz w formacie tts-.... Nowy klucz możesz wygenerować w dowolnym momencie, co natychmiast unieważnia poprzedni. Klucz przesyłasz w nagłówku Authorization: Bearer.

Czy API jest kompatybilne z OpenAI?

Tak, żądania mają taki sam kształt jak endpoint OpenAI Speech. Wystarczy zmienić base_url na https://api.72d.info/v1 i użyć własnego klucza API. Oficjalne SDK OpenAI działają po zmianie base_url, co ułatwia integrację z istniejącymi systemami.

Jakie są domyślne formaty audio?

Wymagasz jawnego określenia formatu w polu response_format. Dostępne opcje to mp3, wav, opus, flac oraz pcm. Nie ma jednego formatu domyślnego; każde żądanie musi precyzyjnie wskazywać preferowaną formę pliku dźwiękowego, który zostanie zwrócony w odpowiedzi.

Co zrobić przy błędzie 429?

Błąd 429 oznacza przekroczenie limitu 60 żądań na minutę. Żądania są przetwarzane sekwencyjnie, więc przy dużym obciążeniu mogą czekać w kolejce. Zastosuj mechanizm ponownych prób z opóźnieniem (exponential backoff), aby zminimalizować ryzyko ponownego przekroczenia limitu.

Jak zmienić prędkość mowy?

Użyj pola speed w żądaniu JSON. Akceptowane wartości mieszczą się w zakresie od 0.25 do 4.0. Domyślna prędkość to 1.0. Zmiana tej wartości pozwala na przyspieszenie lub zwolnienie generowanej mowy zgodnie z potrzebami konkretnego materiału.

Czy można ustawić język ręcznie?

Tak, użyj opcjonalnego pola language z kodem ISO. Jeśli nie zostanie ustawione, język jest domyślnie domyślany na podstawie skryptu (tekst łaciński domyślnie anglicki). Dla tekstów łacińskich w innych językach zalecane jest jawnego wskazania kodu języka.

Jakie jest maksymalne długość tekstu?

Maksymalna długość tekstu w jednym żądaniu to 4096 znaków. Dla dłuższych treści należy podziлировать tekst na części, wygenerować audio dla każdej z nich i połączyć pliki. Każda część musi spełniać ten sam limit znakowy.

Czy API zwraca czas trwania audio?

W faktach nie podano, że odpowiedź zawiera metadane z czasem trwania pliku. Zwracany jest bezpośrednio strumień lub plik audio. Czas generowania zależy od długości tekstu i obciążenia serwera, ale nie jest on zwracany jako pole w odpowiedzi API.

Jak zintegrować API z Pythonem?

Użyj oficjalnego SDK OpenAI dla Pythona. Zmodyfikuj konfigurację, ustawiając base_url na https://api.72d.info/v1 i przekazując swój klucz API. Wywołaj metodę audio.speech.create() z odpowiednimi parametrami modelu, głosu i tekstu źródłowego.

Czy występują opóźnienia w odpowiedzi?

Tak, żądania są przetwarzane jedna po drugiej, co przy dużym obciążeniu powoduje kolejki. Krótkie fragmenty generują się w kilka sekund, a dłuższe teksty osiągają prędkość zbliżoną do czasu rzeczywistego. Opóźnienia zależą od aktualnego ruchu na serwerze.

Jak zaktualizować klucz API?

Nowy klucz możesz wygenerować w dowolnym momencie z panelu konta. Po wygenerowaniu nowego klucza, stary przestaje działać natychmiast. Zaleca się użycie nowego klucza w aplikacjach, aby uniknąć przerw w dostępie podczas rotacji.

Czy endpointy są statyczne?

Tak, endpointy są stałe: POST /v1/audio/speech do generowania, GET /v1/voices do listy głosów i GET /v1/models. Bazowy URL to https://api.72d.info/v1. Struktura żądań i odpowiedzi pozostaje niezmieniona w ramach wersji v1.

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

Wyślij żądanie GET /v1/voices. Odpowiedź zawiera listę dostępnych głosów, języków, formatów oraz cen. Masz do dyspozycji 8 presetów głosowych, które obsługują wszystkie dostępne języki.

Czy API obsługuje żądania asynchroniczne?

Nie, API jest synchroniczne. Żądania są przetwarzane sekwencyjnie w kolejce. Nie ma endpointu do sprawdzania statusu ani mechanizmu webhooków. Musisz czekać na pełną odpowiedź z plikiem audio lub obsłużyć timeout i ponowne próby w swoim kodzie.

Pierwsze żądanie

curl

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

Interakcja z API wymaga aktywnego kluca autoryzacyjnego, który generuje się w panelu konta. Klucz zaczyna się od prefiksu tts- i może być wymieniony w dowolnym momencie; stara wersja przestaje działać natychmiast.

Żądanie wysyłane jest metodą POST na endpoint https://api.72d.info/v1/audio/speech w formacie JSON. Struktura jest zgodna ze standardem OpenAI, co pozwala na użycie oficjalnych bibliotek SDK po zmianie base_url.

Uzyskanie klucza API

Uzyskanie klucza API

Klucz uzyskujesz na stronie /get-api-key/ po zalogowaniu się kontem Google lub e-mail. Po rejestracji widoczny jest Twój aktywny klucz, balans konta oraz przykładowe żądanie curl.

Posiadasz tylko jeden aktywny klucz na konto. Wygenerowanie nowego natychmiast unieważnia poprzedni.

  • Rejestracja przez Google lub e-mail
  • Jeden klucz aktywny jednocześnie
  • Natychmiastowa ważność po wygenerowaniu

Struktura żądania

Struktura żądania

Podstawowe pole input zawiera tekst do syntezy (max 4096 znaków). Długość tekstu wpływa na czas generowania i koszt, który wynosi $0.01 za 1000 znaków.

Połączenie z API wymaga podania modelu, wybranego głosu oraz preferowanego formatu wyjściowego audio.

  • Metoda: POST
  • Endpoint: /v1/audio/speech
  • Format wejściowy: JSON

Autoryzacja Bearer

Każde żądanie musi zawierać nagłówek Authorization: Bearer tts-... z Twoim kluczem API. Bez poprawnego nagłówka żądanie zostanie odrzucone.

Klucz jest jedynym elementem needed do uwierzytelnienia; nie wymaga dodatkowych tokenów odświeżania.

  • Nagłówek: Authorization: Bearer
  • Prefiks klucza: tts-
  • Bezpośrednia walidacja przez API

Endpointy

Ilustracja fali dźwiękowej dla: Endpointy

Interakcja z silnikiem TTS opiera się na trzech podstawowych endpointach REST, zwracających dane w formacie JSON. Kluczowym punktem jest endpoint do generowania audio, który przyjmuje tekst i parametry syntezacji, zwracając plik dźwiękowy lub błąd w przypadku niepowodzenia.

Endpointy listujące konfigurację systemową pozwalają na dynamiczne pobranie dostępnych głosów, modeli oraz metadanych. Są one niezbędne do budowy interfejsu użytkownika lub automatyzacji wyborów przed wysłaniem żądania do głównego endpointu generowania.

Generowanie mowy

Endpoint POST /v1/audio/speech konwertuje tekst na plik audio. Żądanie musi zawierać klucz input z tekstem (max 4096 znaków), model oraz voice. Odpowiedzią jest plik audio w wybranym formacie.

  • Metoda: POST
  • Content-Type: application/json
  • Zwraca: plik audio (mp3/wav/opus/flac/pcm) lub błąd JSON

Lista głosów

Endpoint GET /v1/voices zwraca listę dostępnych presetów głosu wraz z ich metadanymi, takimi jak języki i dostępne formaty. Pozwala to na walidację dostępności konkretnego głosu przed generowaniem.

  • Zwraca listę 8 głosów (np. aria, nova, felix)
  • Określa obsługiwane języki dla każdego głosu
  • Nie wymaga ciała żądania

Lista modeli

Endpoint GET /v1/models zwraca dostępne modele syntezy (tts-1, tts-1-hd). Informacje te służą do weryfikacji zgodności żądań i uzyskania aktualnych metadanych dotyczących cen i limitów charakterystycznych dla danego modelu.

  • Zwraca listę ID modeli
  • Dostarcza metadane o charakterystyce każdego modelu
  • Stabilny interfejs wersjonowania

Parametry żądania

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

Parametry żądania definiują sposób, w jaki syntezator przetwarza tekst na audio. Kluczowe jest zrozumienie różnic między modelami, dostępnych głosów oraz formatów plików, aby zoptymalizować koszty i jakość dla masowej produkcji opisów nieruchomości.

Wszystkie parametry są przesyłane w ciele żądania JSON do endpointu /v1/audio/speech. Nie ma potrzeby konfigurowania zewnętrznych bibliotek do podstawowych operacji – wystarczy standardowe połączenie HTTP.

Model tts-1 i tts-1-hd

Oba modele używają tego samego silnika syntezy, różniąc się jedynie ceną. Wybór zależy od budżetu projektu, a nie od wymagań technicznych jakości dźwięku.

  • tts-1: Standardowy model, niższy koszt za milion znaków.
  • tts-1-hd: Ten sam silnik, wyższa stawka.

Wybór głosu

Dostępnych jest 8 presetów głosowych. Każdy głos potrafi mówić we wszystkich obsługiwanych językach (23), w tym w języku polskim. Jeśli nie podasz kodu języka, system domyślnie zakłada angielski dla tekstów w alfabecie łacińskim.

  • aria, nova, luna, sage (żeńskie)
  • felix, milo, atlas, orion (męskie)

Format wyjściowy

Można wybrać format zgodny z potrzebami systemu odtwarzania w aplikacji. MP3 i WAV są najczęstszym wyborem do webowych tur wirtualnych. Opus i FLAC zapewniają mniejszy rozmiar przy zachowaniu wysokiej jakości.

  • mp3, wav, opus, flac, pcm

Obsługiwane formaty audio

Ilustracja fali dźwiękowej dla: Obsługiwane formaty audio

Format wyjściowy determinuje kompromis między jakością a wielkością pliku. Możesz wybrać standardowe kodeki kompresji lub surowe dane PCM. Każdy wygenerowany plik zawiera niewidoczny znak wodny oznaczający go jako mowę syntetyczną.

MP3 i WAV

MP3 to domylny format, zapewniający dobrą jakość przy małym rozmiarze pliku. WAV oferuje nieskompresowany dźwięk lossless, idealny do dalszej obróbki w edytorach audio, przy czym pliki są znacznie większe.

  • Dostępny w obu wariantach tts-1 i tts-1-hd
  • Optymalny do odtwarzania w przeglądarkach i aplikacjach mobilnych

Opus i FLAC

Opus i FLAC zapewniają mniejszy rozmiar pliku. Opus oferuje wysoką efektywność kompresji przy zachowaniu jakości, podczas gdy FLAC zapewnia bezstratną kompresję, redukując objętość pliku bez utraty danych.

  • Opus: zalecany do przesyłania strumieniowego
  • FLAC: archiwizacja i dalsza obróbka

PCM surowy

Format PCM zwraca surowe dane audio bez nagłówków kontenerowych. Jest użyteczny, gdy wymagana jest precyzyjna kontrola nad próbkowaniem i bitowością w systemach wbudowanych lub prostych odtwarzaczach.

  • Brak kompresji
  • Najmniejsze opóźnienie dekodowania

Przykłady kodu

Ilustracja fali dźwiękowej dla: Przykłady kodu

Dokumentacja przedstawia konkretne przykłady integracji z API VoxNieruchomosci, dostosowane do potrzeb agencji nieruchomości. Poniższe fragmenty kodu pozwalają na szybkie wdrożenie generowania opisów nieruchomości bez zbędnej warstwy abstrakcji.

Każdy przykład uwzględnia kluczowe aspekty: autoryzację, wybór formatu audio oraz obsługa typowych błędów wynikających z limitów lub nieprawidłowych parametrów.

Żądanie curl

Minimalne żądanie do generowania opisu mieszkania w formacie MP3. Klucz należy zamienić na własny z panelu /get-api-key/.

  • `curl -X POST https://api.72d.info/v1/audio/speech \ -H "Authorization: Bearer tts-klucz" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Trzypokojowe mieszanie w centrum", "voice": "aria", "response_format": "mp3"}'`

Konfiguracja SDK OpenAI

Użycie oficjalnego SDK OpenAI wymaga zmiany base_url na adres api.72d.info. Pozwala to na zachowanie znanej składni, np. w Pythonie.

  • client = OpenAI(base_url="https://api.72d.info/v1", api_key="tts-klucz") `audio_response = client.audio.speech.create(model="tts-1", voice="nova", input="Opis apartamentu", response_format="mp3")`

Obsługa błędów JSON

API zwraca standardowe kody HTTP. Błędy walidacji (np. brak tekstu) zwracają kod 400 z opisem w ciele odpowiedzi JSON. Przechwyć je, aby nie przerywać procesu batchowego.

Przykłady kodu

Limity i wydajność

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

Wydajność API jest kluczowa dla masowej produkcji opisów nieruchomości. System obsługuje do 60 żądań na minutę dla jednego klucza.

Przy dłuższych opisach należy podzielić tekst na fragmenty do 4096 znaków i połączyć wynikowe pliki audio. Pozwala to na bezproblemową obsługę nawet najdłuższych ofert.

Limit 60 żądań/min

Standardowy limit to 60 żądań na minutę dla aktywnego klucza API. W przypadku nowego konta, przed pierwszą dopłatą, limit wynosi 10 żądań na minutę. Przekroczenie limitu skutkuje błędem HTTP 429 (Too Many Requests).

Limit dotyczy liczby żądań POST do endpointu /v1/audio/speech. Żądania są przetwarzane jedno po drugim.

  • Limit: 60 żądań/min (klucz aktywny)
  • Limit dla nowych kont: 10 żądań/min
  • Błąd przy przekroczeniu: HTTP 429

Czas generowania

Typowy czas generowania wynosi około 25 znaków tekstu na sekundę dźwięku. Krótkie opisy nieruchomości są generowane w ciągu kilku sekund. Dłuższe teksty mogą wymagać więcej czasu ze względu na podział i łączenie plików.

Typowa szybkość generowania to około 25 znaków tekstu na sekundę dźwięku.

  • Typowa szybkość: ~25 znaków/sekundę dźwięku
  • Krótkie opisy: kilka sekund
  • Długie teksty: czas zależny od długości

Kolejkowanie żądań

Żądania są przetwarzane kolejno, co oznacza, że w przypadku dużego obciążenia, nowe żądania mogą czekać w kolejce. To zapewnia stabilność systemu i uniknięcie przeciążenia serwerów.

Kolejkowanie jest automatyczne i nie wymaga dodatkowej konfiguracji po stronie klienta. Zaleca się implementację mechanizmu ponownych prób z opóźnieniem przy błędach 429 lub 503.

  • Przetwarzanie kolejne
  • Automatyczne kolejkowanie
  • Rekomendacja: retry z opóźnieniem

Obsługa błędów

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

API zwraca standardowe kody HTTP, które informują o powodzeniu lub przyczynie niepowodzenia operacji. Każda odpowiedź zawiera obiekt JSON z kodem błędu i opisem, co ułatwia debugowanie integracji w systemach agencji.

Nie ma gwarancji SLA ani numeru telefonu do wsparcia. W przypadku problemów technicznych lub wątpliwości dotyczących błędów, kontakt mailowy jest jedyną dostępną formą pomocy.

Kody błędów HTTP

W odpowiedziach API zwracane są standardowe kody statusu HTTP. Kod 200 oznacza pomyślne wygenerowanie pliku audio. Kody z zakresu 4xx wskazują na błędy po stronie klienta, takie jak nieprawidłowy klucz autoryzacji lub brak środków. Kody 5xx oznaczają chwilowe problemy po stronie serwera.

Każdy błąd jest opisany w ciele odpowiedzi JSON, co pozwala na automatyczne przetwarzanie komunikatów w systemach CRM agencji nieruchomości.

  • 401 Unauthorized – nieprawidłowy klucz API.
  • 402 Payment Required – brak wystarczających środków na koncie.
  • 429 Too Many Requests – przekroczenie limitu żądań.

Przekroczenie limitu

Limit wynosi 60 żądań na minutę na klucz API. Przed pierwszą wpłatą limit ten wynosi 10 żądań na minutę. Przekroczenie limitu skutkuje zwrotem kodu 429.

Nie ma gwarancji ciągłości połączenia ani przydziału zasobów na żądanie. W przypadku dużego obciążenia żądania są przetwarzane kolejno, co może wydłużać czas oczekiwania.

  • 60 żądań/min po doładowaniu konta.
  • 10 żądań/min przed pierwszą wpłatą.
  • Brak limitu dziennego ani miesięcznego.

Nieprawidłowy format

Błędy związane z nieprawidłowym formatem danych (np. błędna składnia JSON, nieobsługiwany format audio) są sygnalizowane kodem 400. Kluczowe jest zapewnienie, że tekst wejściowy nie przekracza 4096 znaków.

W przypadku błędów formatu, żądanie nie jest rozliczane, a środki na koncie nie są pobierane.

  • Sprawdź poprawność struktury JSON.
  • Upewnij się, że format wyjściowy jest jednym z obsługiwanych.
  • Sprawdź, czy tekst nie przekracza limitu znaków.

Specyfika implementacji

Ilustracja fali dźwiękowej dla: Specyfika implementacji

API zwraca pliki audio o długości maksymalnie 4096 znaków. Dla dłuższych opisów nieruchomości należy podzielić tekst na fragmenty i połączyć wyniki.

Jeśli nie podasz kodu języka, system zgaduje go na podstawie skryptu. Dla tekstów łacińskich poza angielskim należy ustawić parametr language.

Podział długich tekstów

Każde żądanie obsługuje do 4096 znaków (wliczając spacje i interpunkcję). Jeśli opis apartamentu przekracza ten limit, podziel go logicznie. Wyślij osobne żądania dla każdego fragmentu i połącz wygenerowane pliki audio w jedną całość.

Detekcja języka

System automatycznie rozpoznaje język na podstawie znaków w tekście. Domyślnie teksty w alfabecie łacińskim są interpretowane jako angielskie. Dla innych języków łacińskich (np. polskiego, hiszpańskiego) zawsze podawaj kod ISO w polu language.

Watermark w pliku

Każdy wygenerowany plik audio zawiera niewidoczny znak wodny informujący, że mowa została wygenerowana syntetycznie. Jest on wbudowany w strumień dźwiękowy i nie wpływa na jakość odtwarzania ani na rozmiar pliku.

Posłuchaj 8 głosów

Każdą z poniższych próbek wygenerowano za pomocą tego API z tego samego zdania. Brak zaawansowanych znaczników SSML ogranicza precyzję intonacji.

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. LibriVox public-domain audiobooks
  3. MDN: Web Speech API
  4. Node.js documentation
  5. ISO 639 language codes
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. openai-python on GitHub
  8. curl documentation
  9. Tether (USDT)
  10. IETF RFC 7845: Ogg Opus
  11. OpenAI API reference: create speech
  12. Creative Commons Attribution 4.0

Więcej na tej stronie