Moknah Dokumentacja
Zacznij za darmo
Dokumentacja API

Zamiana tekstu na mowę (TTS) w czasie rzeczywistym

Strumieniuj tekst progresywnie i natychmiast odbieraj surowe bajty audio PCM lub MP3

WSS /api/v1/tts/ws/

Nawiązuje dwukierunkowe połączenie WebSocket do strumieniowania zamiany tekstu na mowę w czasie rzeczywistym. Wysyłaj fragmenty tekstu progresywnie (idealne dla odpowiedzi modeli LLM) i odbieraj binarne strumienie audio w sposób ciągły. Kredyty są naliczane identycznie jak w punkcie końcowym HTTP.

⚡ Optymalizacja opóźnień (TTFB)

Aby uzyskać ultraniskie opóźnienie (~200 ms czasu do pierwszego bajtu), upewnij się, że fragmenty tekstu kończą się wyraźnymi znakami interpunkcyjnymi (kropkami ., wykrzyknikami ! lub znakami zapytania ?). Sztuczna inteligencja naturalnie buforuje tekst do momentu wykrycia końca zdania, aby zapewnić idealną ludzką intonację.

Uwierzytelnianie

Uwierzytelnij się za pomocą nagłówka Authorization podczas uzgadniania połączenia WebSocket:

Authorization: Bearer YOUR_API_KEY

Konfiguracja połączenia

Po nawiązaniu połączenia wyślij wiadomość inicjalizacyjną z wybraną konfiguracją:

{
  "type": "init",
  "voice_id": 1710,
  "prerecording": 1,
  "language": "ar",
  "output_format": "pcm_24000",
  "voice_settings": {
    "temperature": 25,
    "similarity": 100,
    "expressiveness": 0,
    "speed": 1.0,
    "fast_mode": 2
  }
}

Parametry inicjalizacji

Parametr Wymagane Typ Opis
type wymagane string Musi mieć wartość "init" dla wiadomości inicjalizacyjnej.
voice_id wymagane liczba całkowita ID głosu z listy głosów.
output_format opcjonalne string Żądany format audio. Domyślnie pcm_24000. Dostępne opcje:
  • MP3: mp3_22050_32, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
  • PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100
Do strumieniowania w aplikacjach bez opóźnień użyj formatu PCM. Do zapisywania plików wybierz MP3.
prerecording opcjonalne liczba całkowita 1 (normalny, domyślnie), 2 (ulepszenie AI / arabski Tashkeel) lub 3 (Poeta AI). Wpływa na koszt w kredytach. Opcje 2 i 3 są dostępne tylko dla treści w języku arabskim; zobacz language.
language opcjonalne string Język treści jako kod ISO 639-1, na przykład ar lub en (akceptowane są kody regionów takie jak ar-JO). Decyduje o tym, które tryby wstępnego przetwarzania są dozwolone, i nie jest wysyłany do głosu. Tryby 2 i 3 są dostępne tylko dla języka arabskiego (ar). Jeśli pominięto parametr language, wartości 2 i 3 oznaczają język arabski, dzięki czemu istniejące integracje nadal działają. Każdy inny język z wartością 2 lub 3 albo nieznany kod zwraca komunikat o błędzie, a strumień nie zostaje zainicjalizowany.
voice_settings opcjonalne object Opcje dostosowywania głosu. Zobacz sekcję Ustawienia głosu poniżej.

Obiekt ustawień głosu

Strumieniowanie działa z oboma silnikami według własnej stawki za znak pomnożonej przez tryb: emotion (domyślnie) i fast_mode ×1, quality i studio ×2. Głosy silnika Zaawansowanego kosztują ×1,5.

  • Głosy silnika Standardowego są strumieniowane w każdym trybie: emotion (domyślnie, najniższe opóźnienie), quality oraz studio. Parametr fast_mode przełącza na model o niskim opóźnieniu.
  • Głosy silnika Zaawansowanego są strumieniowane zdanie po zdaniu: dźwięk dla każdego zdania rozpoczyna się natychmiast po jego ukończeniu. Użyj formatów wyjściowych pcm_* lub mp3_* (format Opus nie jest dostępny dla tych głosów).

Głosy silnika Standard

Parametr Typ Zakres Domyślny Opis
mode string emotion, quality, studio emotion Opcjonalnie. emotion (Emocje i dialekt, ×1), quality (Wysoka jakość emocji i dialektu, ×2) lub studio (Jakość studyjna, ×2). W trybach emotion i quality zastosowanie mają tylko parametry temperature i similarity.
temperature liczba całkowita 0 – 100 25 Niżej = stabilnie i przewidywalnie, Wyżej = kreatywnie i różnorodnie.
similarity liczba całkowita 0 – 100 100 Jak dokładnie mowa odwzorowuje oryginalny klon głosu.
speed float 0.5 – 2.0 1.0 Mnożnik prędkości odtwarzania.
fast_mode liczba całkowita 0, 1, or 2 0 1 lub 2 przełącza na model o niskim opóźnieniu (×1 kredytów) i nadpisuje mode. 0 = wył.

Głosy silnika Zaawansowanego

Parametr Typ Wartości Opis
context string do 500 znaków Najmocniejsza kontrola. Opisz akcent, emocje, nastrój lub cel.
setting string do 500 znaków Scena i nastrój.
style string neutral, warm, energetic, serious, cheerful, poetic Ogólny styl wypowiedzi.
pace string slow, normal, fast Tempo mówienia.

Wskazówka: wysyłaj całe zdania (zakończone znakiem . ! ? lub nową linią), aby jak najszybciej uzyskać pierwszy dźwięk.

Potok strumieniowania

1. Wysyłaj fragmenty tekstu

Wysyłaj tekst stopniowo, w miarę jak generuje go Twój LLM:

{"type": "text", "data": "مرحبا بكم."}

Serwer natychmiast przetworzy fragment, pobierze odpowiednią liczbę kredytów dla tej długości i rozpocznie strumieniowanie dźwięku z powrotem.

2. Zasygnalizuj zakończenie (Stop)

Gdy generowanie tekstu całkowicie się zakończy, wyślij sygnał zatrzymania:

{"type": "stop"}

Serwer dokończy syntezę pozostałego tekstu w buforze, przekaże Ci ostatnie bajty audio i wyśle sygnał końca strumienia.

Odbieranie wiadomości

Serwer przesyła przez WebSocket dwa typy ramek:

1. Binarne fragmenty audio (PCM / MP3)

Surowe bajty audio strumieniowane tak szybko, jak są generowane. Format zależy od żądanego parametru output_format (domyślnie 16-bitowy PCM przy 24 kHz). Jeśli zażądano formatu MP3, możesz zapisać te bajty bezpośrednio do pliku.

2. Komunikaty sterujące JSON

Inicjalizacja gotowa:

{"status": "ready", "message": "Zainicjalizowano i gotowe do odbierania tekstu."}

Koniec strumienia (sygnał bezpiecznego zamknięcia):

{"type": "end_of_stream"}

Otrzymanie tego komunikatu daje matematyczną gwarancję, że 100% fragmentów audio zostało dostarczonych. Możesz teraz bezpiecznie zamknąć połączenie WebSocket po stronie klienta.

Błąd w trakcie strumieniowania:

{"error": "Niewystarczająca liczba kredytów podczas transmisji"}

Przykłady gotowe do wdrożenia

# pip install websockets
import asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
url = "wss://api.moknah.io/api/v1/tts/ws/"

async def stream_tts():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        # 1. Initialize session (Requesting MP3 so we can save to file)
        await ws.send(json.dumps({
            "type": "init",
            "voice_id": 1710,
            "output_format": "mp3_44100_128",
            "voice_settings": {"fast_mode": 2}
        }))
        print(f"Server: {await ws.recv()}")

        # 2. Receiver Task
        async def receive_audio():
            with open("audio.mp3", "wb") as f:
                async for msg in ws:
                    if isinstance(msg, bytes):
                        f.write(msg)
                    else:
                        data = json.loads(msg)
                        if data.get("type") == "end_of_stream":
                            print("✅ Stream finished safely.")
                            await ws.close()
                            break

        receiver = asyncio.create_task(receive_audio())

        # 3. Send Text
        for chunk in ["مرحبا بكم.", "في منصة مُكنة."]:
            await ws.send(json.dumps({"type": "text", "data": chunk}))
            await asyncio.sleep(0.5)

        # 4. Signal Stop
        await ws.send(json.dumps({"type": "stop"}))
        await receiver

asyncio.run(stream_tts())
// npm install ws
const WebSocket = require('ws');
const fs = require('fs');

const API_KEY = "YOUR_API_KEY";
const ws = new WebSocket('wss://api.moknah.io/api/v1/tts/ws/', {
    headers: { "Authorization": `Bearer ${API_KEY}` }
});

const audioStream = fs.createWriteStream('audio.mp3');

ws.on('open', function open() {
    // Requesting MP3 to safely write to an MP3 file
    ws.send(JSON.stringify({
        type: "init",
        voice_id: 1710,
        output_format: "mp3_44100_128",
        voice_settings: { fast_mode: 2 }
    }));
});

ws.on('message', function incoming(data, isBinary) {
    if (isBinary) {
        audioStream.write(data); // Save MP3 chunks
    } else {
        const msg = JSON.parse(data.toString());
        if (msg.status === 'ready') {
            console.log("Ready! Sending text...");
            ws.send(JSON.stringify({ type: "text", data: "مرحبا بكم." }));
            setTimeout(() => ws.send(JSON.stringify({ type: "text", data: "في منصة مُكة." })), 500);
            setTimeout(() => ws.send(JSON.stringify({ type: "stop" })), 1000);
        } else if (msg.type === 'end_of_stream') {
            console.log("✅ All audio received. Closing connection.");
            ws.close();
        }
    }
});
<?php
// composer require textalk/websocket
require 'vendor/autoload.php';
use WebSocket\Client;

$apiKey = "YOUR_API_KEY";
$client = new Client("wss://api.moknah.io/api/v1/tts/ws/", [
    'headers' => ['Authorization' => "Bearer $apiKey"],
    'timeout' => 60
]);

// 1. Initialize (Requesting MP3 format)
$client->text(json_encode([
    "type" => "init",
    "voice_id" => 1710,
    "output_format" => "mp3_44100_128",
    "voice_settings" => ["fast_mode" => 2]
]));
echo "Server: " . $client->receive() . "\n";

// 2. Send Text Chunks
$client->text(json_encode(["type" => "text", "data" => "مرحبا بكم."]));
$client->text(json_encode(["type" => "text", "data" => "في منصة مُكنة."]));
$client->text(json_encode(["type" => "stop"]));

// 3. Receive Audio & Control Messages
$audioFile = fopen("audio.mp3", "wb");
while (true) {
    $message = $client->receive();
    $decoded = json_decode($message, true);

    if ($decoded && isset($decoded['type']) && $decoded['type'] == 'end_of_stream') {
        echo "✅ Stream finished successfully.\n";
        break;
    } elseif (!$decoded) {
        // If it can't be decoded as JSON, it's our binary MP3 audio chunk
        fwrite($audioFile, $message);
    }
}
fclose($audioFile);
$client->close();
?>
# Standard cURL does not support bidirectional WebSockets easily.
# Use 'websocat' to test WebSockets from the command line:

websocat wss://api.moknah.io/api/v1/tts/ws/ \
  -H "Authorization: Bearer YOUR_API_KEY"

# Once connected, paste the JSON payloads interactively:
{"type": "init", "voice_id": 1710, "output_format": "mp3_44100_128"}

{"type": "text", "data": "مرحبا بكم."}

{"type": "stop"}

Kody zamknięcia i błędy

Połączenie WebSocket może zostać zamknięte jednym z poniższych standardowych kodów:

Kod Typ Opis
1000 SUCCESS Strumień zakończył się prawidłowo.
3011 GENERATION_ERROR Generowanie dźwięku w nadrzędnym API nie powiodło się. Ponów żądanie.
4001 MISSING_API_KEY Nie podano klucza API w nagłówku Authorization.
4002 AUTH_FAILED Nieprawidłowy klucz, nieaktywne konto, niewystarczająca początkowa liczba kredytów lub ograniczenie IP.
4290 CONCURRENT_LIMIT Użytkownik ma już aktywne połączenie TTS WebSocket. Limit wynosi 1 na użytkownika.
Wsparcie API

W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.