Zamiana tekstu na mowę (TTS) w czasie rzeczywistym
Strumieniuj tekst progresywnie i natychmiast odbieraj surowe bajty audio PCM lub MP3
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.
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:
|
| 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. |
W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.