Dokumentacja API Syntezy Mowy: Jak Integrować

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

Dokumentacja API TikSpeech wyjaśnia, jak zintegrować syntezę mowy z Twoimi projektami do TikToka, Reels i Shorts. Dowiesz się krok po kroku, jak uzyskać klucz API, wysłać zapytanie POST i odebrać gotowy plik audio. Opisujemy strukturę JSON, dostępne formaty wyjściowe oraz sposoby użycia z biblioteką OpenAI SDK.

Przeznaczone dla freelancerów i twórców treści, którzy potrzebują szybkiego i spójnego głosu bez zbędnego opisywania każdego filmu. Znajdziesz tu konkretne przykłady kodu, informacje o limitach (60 zapytań na minutę) oraz listę obsługiwanych języków i głosów. Strona zawiera wszystkie niezbędne dane techniczne do poprawnej integracji bez konieczności czytania długich opisów marketingowych.

Dokumentacja API Syntezy Mowy: Jak Integrować

Najczęściej zadawane pytania

Jak uzyskać klucz API?

Zarejestruj się na /get-api-key/, logując się przez Google lub tworząc konto z hasłem. Po zalogowaniu otrzymasz unikalny klucz API; kredyt próbny ($0.50) otrzymujesz tylko przy rejestracji przez Google. Klucz ten służy do autoryzacji wszystkich zapytań do API i jest widoczny w panelu użytkownika.

Jakie jest URL endpointu?

Główny endpoint to POST https://api.18g.info/v1/audio/speech. Wysyłasz tam tekst w formacie JSON, a otrzymujesz plik audio. Inne endpointy to GET /v1/voices i GET /v1/models. Baza URL dla SDK to https://api.18g.info/v1.

Jakie są dostępne formaty audio?

Możesz wybrać formaty: mp3, wav, opus, flac oraz pcm. Wybór odbywa się poprzez pole response_format w ciele zapytania JSON. Każdy z tych formatów jest obsługiwany przez API i zwracany jako gotowy plik dźwiękowy do pobrania lub użycia.

Jakie są limity zapytań?

Limit wynosi 60 zapytań na minutę na klucz. Przed pierwszym doładowaniem saldo wynosi 0, więc limit spada do 10 zapytań na minutę. Jeśli przekroczysz limit, zapytania mogą być opóźniane lub odrzucane. Limity są stosowane automatycznie do każdego aktywnego klucza API.

Jak zintegrować z SDK OpenAI?

Użyj oficjalnego SDK OpenAI, zmieniając base_url na https://api.18g.info/v1. Ustaw nagłówek Authorization z swoim kluczem API. Struktura ciała zapytania jest identyczna jak w endpointzie OpenAI, więc kod wymaga jedynie zmiany URL i klucza autoryzacji.

Czy mogę użyć własnego kodu?

Tak, API obsługuje zwykłe zapytania HTTP. Możesz wysyłać żądania POST z dowolnego języka programowania, który obsługuje JSON. Nie ma potrzeby używania dedykowanego SDK TikSpeech; wystarcza standardowa biblioteka HTTP Twojego języka do wysłania tekstu i pobrania audio.

Jak obsłużyć błędy?

Błędy są zwracane w standardowym formacie JSON z kodem statusu HTTP. Jeśli synteza się nie powiedzie, kwota zostanie zwrócona na saldo. Sprawdź kod błędu w odpowiedzi, aby zidentyfikować problem, np. przekroczenie limitu znaków lub nieprawidłowy format żądania.

Jakie są parametry języka?

Parametr language jest opcjonalny. Jeśli nie zostanie ustawiony, język jest domyślnie wykrywany na podstawie skryptu (łaciński domyślnie angielski). Dla tekstów w innych językach łacińskich zaleca się jawnego ustawienia kodu ISO, np. pl dla polskiego, aby zapewnić poprawną wymowę.

Czy mogę zmienić prędkość?

Tak, parametr speed pozwala regulować prędkość od 0.25 do 4.0. Wartość domyślna to 1.0. Zmiana prędkości wpływa na czas generowania i długość pliku audio. Wartości spoza tego zakresu mogą zostać odrzucone przez API jako nieprawidłowe.

Jak długo trwa generowanie?

Długie teksty generują się w czasie rzeczywistym, około 25 znaków na sekundę. Krótkie frazy mogą trwać kilka sekund. Żądania są przetwarzane kolejno, więc przy dużym obciążeniu może wystąpić kolejka. Czas zależy od długości tekstu i aktualnego ruchu na serwerze.

Czy są dostępne głosy męskie?

Tak, dostępne są głosy męskie: Felix (energetyczny, promocyjny), Milo (przyjazny, konwersacyjny), Atlas (neutralny, newsowy) oraz Orion (głęboki, dokumentalny). Każdy z tych głosów może mówić każdym z obsługiwanych języków, w tym polskim, angielskim czy niemieckim.

Czy są dostępne głosy żeńskie?

Tak, dostępne są głosy żeńskie: Aria (ciepła, klarowna), Nova (jasna, pełna energii), Luna (miękka, opowiadająca) oraz Sage (spokojna, instruktażowa). Wszystkie głosy są oparte na nagraniach z licencji CC BY 4.0 (LibriTTS-R) i domyńnych nagraniach z LibriVox.

Jak sprawdzić saldo?

Saldo jest widoczne w panelu użytkownika na stronie /get-api-key/. Pokazuje dostępne środki, kredyt próbny oraz zużyte znaki. Saldo nie wygasa. Możesz doładować konto za pomocą USDT (TRC-20), a środki pojawią się automatycznie po potwierdzeniu transakcji.

Czy mogę wygenerować klucz ponownie?

Tak, możesz wygenerować nowy klucz API w dowolnym momencie w panelu użytkownika. Stary klucz przestaje działać natychmiast po wydaniu nowego. Możesz mieć aktywny tylko jeden klucz na konto. Nowy klucz wymaga ponownej konfiguracji w Twoich aplikacjach.

Pierwsze żądanie

curl

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

Uzyskanie klucza API

Ilustracja fali dźwiękowej dla: Uzyskanie klucza API

Dostęp do API TikSpeech zaczyna się od założenia konta na stronie https://18g.info/get-api-key/. Możesz zarejestrować się przy użyciu konta Google lub podając adres e-mail i hasło. Rejestracja jest niezbędna do wygenerowania unikalnego klucza dostępu, który autoryzuje Twoje zapytania do endpointu https://api.18g.info/v1.

Rejestracja konta

Rejestracja konta

Proces rejestracji jest szybki i odbywa się bezpośrednio w przeglądarce. Po zalogowaniu otrzymujesz dostęp do panelu zarządzania, gdzie możesz zarządzać swoimi kluczami API i śledzić zużycie znaków.

Wygenerowanie klucza

Wygenerowanie klucza

Po zalogowaniu przejdź do sekcji zarządzania kontem, aby wygenerować klucz API. Każdy kont posiada jeden aktywny klucz begin formu „tts-...”. Jeśli chcesz odświeżyć dostęp, możesz wygenerować nowy klucz w dowolnym momencie; stary klucz przestaje działać natychmiast.

Bezpieczeństwo klucza

Przechowuj swój klucz API w bezpiecznym miejscu, podobnie jak hasło. Klucz ten służy do autoryzacji żądań HTTP za pomocą nagłówka Authorization: Bearer tts-.... Nie udostępniaj go publicznie w kodzie widocznym dla klientów, jeśli nie jest to konieczne.

Pierwsze zapytanie

Ilustracja fali dźwiękowej dla: Pierwsze zapytanie

['Po uzyskaniu klucza API z panelu /get-api-key/, możesz przetestować syntezę za pomocą prostego zapytania HTTP. Poniżej znajduje się gotowy przykład dla konsoli oraz struktura danych wymaganych przez endpoint /v1/audio/speech.', 'Zwróć uwagę, że każde zapytanie musi zawierać autoryzację Bearer oraz poprawny format JSON. Tekst wejściowy jest ograniczony do 4096 znaków na żądanie.']

Użycie SDK OpenAI

Ilustracja fali dźwiękowej dla: Użycie SDK OpenAI

Dzięki kompatybilności z interfejsem OpenAI, możesz wykorzystać oficjalne biblioteki SDK do prostszej integracji z TikSpeech. Wystarczy jedynie przekierować zapytania do naszego endpointu, zachowując tę samą strukturę danych.

Ta metoda eliminuje potrzebę pisania własnej logiki HTTP. Po zmianie podstawowego URL, wszystkie standardowe operacje generowania mowy działają bez modyfikacji kodu źródłowego aplikacji.

Zmiana base_url

Aby SDK OpenAI pracowało z naszym API, należy zaktualizować parametr base_url na https://api.18g.info/v1. To jedyna konieczna zmiana konfiguracji, która pozwala klientowi na wysyłanie żądań do naszej infrastruktury.

Instalacja biblioteki

Zainstaluj oficjalną paczkę openai dla Pythona lub JavaScriptu. Nie ma potrzeby używania dedykowanej biblioteki TikSpeech; standardowe narzędzia OpenAI obsługują nasz endpoint bez dodatkowych zależności.

Przykładowy kod

Poniższy fragment pokazuje inicjalizację klienta z właściwym URL-em. Pamiętaj, aby użyć klucza API wygenerowanego na stronie /get-api-key/. Struktura żądania pozostaje identyczna jak w standardowym API OpenAI.

  • Zainstaluj bibliotekę: pip install openai
  • Ustaw base_url na https://api.18g.info/v1
  • Wyślij tekst do syntezy używając standardowych metod SDK

Formaty wyjściowe

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

API zwraca pliki audio w formacie binarnym bezpośrednio w odpowiedzi HTTP. Wybór formatu zależy od potrzeb Twojego edytora wideo lub odtwarzacza w aplikacji. Wszystkie dostępne kodeki są obsługiwane przez standardowe biblioteki OpenAI oraz czyste zapytania HTTP.

Format wyjściowy określasz parametrem response_format w ciele zapytania JSON. Dostępne opcje to mp3, wav, opus, flac oraz pcm. Wybór nie wpływa na cenę ani jakość głosu, lecz na rozmiar pliku i kompatybilność z Twoim potokiem produkcyjnym.

MP3

Najbardziej uniwersalny format do publikacji na TikToku, Reels i Shorts. Zapewnia dobre zrównoważenie między jakością a małym rozmiarem pliku. Większość platform social media automatycznie konwertuje MP3, więc jest to bezpieczny wybór domyślny.

Pliki MP3 są łatwe do przesyłania i łączenia z innymi klipami wideo w popularnych edytorach mobilnych i desktopowych. Nie wymagają dodatkowej konwersji przed wgraniem do mediów społecznościowych.

  • Rozmiar pliku: optymalny do przesyłania

WAV

Format bezstratny, idealny, jeśli planujesz dalszą obróbkkę audio w profesjonalnym DAW (Digital Audio Workstation). Zapewnia najwyższą wierność dźwięku bez kompresji.

Pliki WAV są znacznie większe niż MP3, co może spowolnić przesyłanie przy dużych objętościach tekstu. Wybieraj ten format, gdy zależy Ci na precyzyjnym cięciu lub efekcie w postprodukcji.

  • Jakość: bezstratna
  • Rozmiar: większy niż MP3

OPUS i FLAC

OPUS oferuje wysoką jakość przy bardzo niskim bitrate’ie, co jest korzystne dla aplikacji mobilnych i strumieniowania. FLAC to bezstratny format archiwalny, zachowujący pełną wierność oryginału.

Użyj OPUS, gdy priorytetem jest oszczędność transferu danych na urządzeniach klienckich. FLAC wybierz do archiwizacji materiałów źródłowych. Obie opcje są zwracane jako pliki binarne w odpowiedzi API.

  • OPUS: wysoka efektywność
  • FLAC: bezstratna archiwizacja

Limity i wydajność

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

Wydajność API TikSpeech jest zaprojektowana pod kątem stabilnej pracy przy generowaniu krótkich formatów wideo. Kluczowe parametry dotyczą limitów zapytań, długości tekstu oraz czasu potrzebnego na syntezę.

60 zapytań na minutę

Dla każdego klucza API limity wynoszą 60 zapytań na minutę. Przed pierwszym doładowaniem konta limit ten wynosi 10 zapytań na minutę.

Limit znaków

Jedno zapytanie może zawierać tekst o długości do 4096 znaków. Przestrzenie i interpunkcja liczą się jako znaki. W przypadku dłuższych tekstów należy podzielić tekst na części i połączyć wygenerowane pliki audio.

Czas generowania

Typowa prędkość to około 25 znaków tekstu na sekundę generowania, co odpowiada przybliżonemu czasowi rzeczywistemu dla długich tekstów. Krótkie frazy mogą wymagać kilku sekund. W okresach dużego obciążenia zapytania przetwarzane są sekwencyjnie, co może wydłużyć czas oczekiwania w kolejce.

Limity i wydajność

Obsługa błędów

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

API zwraca standardowe kody HTTP, aby informować o statusie zapytania. Dzięki temu możesz łatwo zintegrować obsługę błędów z własnymi narzędziami automatyzacji.

Kody błędów

Użyj kodu 401, gdy klucz jest nieprawidłowy lub wygasł. Kod 429 oznacza przekroczenie limitu 60 zapytań na minutę. Kod 400 sygnalizuje błędy w strukturze JSON lub przekroczenie limitu 4096 znaków.

  • 400: Błąd walidacji danych wejściowych
  • 401: Nieautoryzowany dostęp
  • 429: Przekroczony limit zapytań
  • 500: Błąd serwera podczas syntezy

Powtarzanie zapytań

Jeśli otrzymasz kod 429, poczekaj minutę przed ponowną próbą. Błędy sieciowe lub czasowe (500) można bezpiecznie powtórzyć raz. W przypadku niepowodzenia syntezy zwrot kwoty następuje automatycznie.

Logi

System przechowuje metadane zapytań, w tym czas, liczbę znaków i status, wyłącznie w celu rozliczenia. Nie przechowujemy treści wygenerowanego audio ani oryginalnego tekstu.

Języki i głosy

Ilustracja fali dźwiękowej dla: Języki i głosy

Dokładne ustawienie parametru language jest kluczowe dla jakości syntezy, zwłaszcza przy tekstach w językach łacińskich innych niż angielski. Jeśli pole pozostanie puste, system domyślnie zakłada angielski dla tekstu w alfabecie łacińskim, co może zniekształcić wymowę w innych językach.

Parametr języka

Używaj kodów ISO (np. pl, de, es) w polu language, aby wymusić poprawną wymowę. Bez tego ustawienia system może błędnie zinterpretować tekst, np. uznając polski tekst łaciński za angielski.

Lista głosów

API oferuje 8 presetów głosowych: Aria, Nova, Luna, Sage (kobiece) oraz Felix, Milo, Atlas, Orion (męskie). Każdy głos obsługuje wszystkie 23 dostępne języki, w tym arabski, chiński, hiszpański czy japoński, bez konieczności zmiany konfiguracji.

  • Aria: ciepły narrator
  • Felix: energetyczny, promocyjny
  • Atlas: neutralny, newsowy
  • Orion: głęboki, dokumentalny

Domyślne ustawienia

Domyślnie język jest zgadywany na podstawie pisma. Teksty w alfabecie łacińskim są domyślnie traktowane jako angielskie. Dla języków słowiańskich, romańskich czy germańskich używających łaciny, jawnie ustaw language aby uniknąć akcentu angielskiego.

Podsumowanie techniczne

Ilustracja fali dźwiękowej dla: Podsumowanie techniczne

Wsparcie techniczne odbywa się wyłącznie drogą e-mailową. Nie oferujemy numeru telefonu ani czatu na żywo, co pozwala nam skupić się na skutecznej pomocy merytorycznej.

Aktualizacje API są wprowadzane bez wcześniejszego zapowiedzi, a zmiany w cenniku lub limitach są publikowane na stronie /pricing/. Nie posiadamy własnych SDK ani wtyczek (np. WordPress).

Wsparcie

Dołącz do nas na Discordzie i dołącz do społeczności. Jesteśmy zawsze dostępni, aby pomóc Ci w integracji API.

  • Wsparcie techniczne odbywa się wyłącznie drogą e-mailową.
  • Nie oferujemy numeru telefonu ani czatu na żywo.
  • Nie posiadamy własnych SDK ani wtyczek (np. WordPress).

Aktualizacje

Aktualizacje API są wprowadzane bez wcześniejszego zapowiedzi, a zmiany w cenniku lub limitach są publikowane na stronie /pricing/. Nie posiadamy własnych SDK ani wtyczek (np. WordPress).

Kontakt

Napisz do nas na adres [email protected]. Podaj swój klucz API i opis problemu, abyśmy mogli szybciej Ci pomóc.

  • Wsparcie techniczne odbywa się wyłącznie drogą e-mailową.
  • Nie oferujemy numeru telefonu ani czatu na żywo.
  • Nie posiadamy własnych SDK ani wtyczek (np. WordPress).

Posłuchaj 8 głosów

Każdą z poniższych próbek wygenerowano za pomocą tego API z tego samego zdania. Idealnie sprawdza się w formacie storytellingu, gdy chcesz zbudować intymną atmosferę wokół prezentowanej treści.

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. FFmpeg documentation
  4. W3C WAI: making audio and video accessible
  5. IETF RFC 7845: Ogg Opus
  6. LibriVox public-domain audiobooks
  7. LibriTTS-R corpus (OpenSLR 141)
  8. curl documentation
  9. openai-node on GitHub
  10. Python documentation
  11. OpenAI API reference: create speech
  12. TRON developer hub: TRC-20

Więcej na tej stronie