Synthèse vocale (TTS) en temps réel
Diffusez du texte en continu et recevez instantanément des octets audio PCM bruts ou MP3.
Établit une connexion WebSocket bidirectionnelle pour le streaming de synthèse vocale en temps réel. Envoyez des segments de texte progressivement (idéal pour les sorties de LLM) et recevez des flux audio binaires en continu. Le calcul des crédits est identique à celui de l’endpoint HTTP.
Pour obtenir une latence ultra-faible (un délai jusqu’au premier octet d’environ 200 ms), veillez à ce que vos segments de texte se terminent par une ponctuation forte (points ., points d’exclamation ! ou points d’interrogation ?). L’IA met naturellement le texte en mémoire tampon jusqu’à ce qu’elle détecte une fin de phrase, afin de garantir une intonation humaine parfaite.
Authentification
Authentifiez-vous à l’aide de l’en-tête Authorization lors de la négociation de connexion WebSocket :
Authorization: Bearer YOUR_API_KEY
Configuration de la connexion
Une fois connecté, envoyez un message d’initialisation avec la configuration souhaitée :
{
"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
}
}
Paramètres d’initialisation
| Paramètre | Obligatoire | Type | Description |
|---|---|---|---|
| type | requis | chaîne | Doit valoir "init" pour le message d'initialisation. |
| voice_id | requis | nombre entier | Identification vocale de la liste des voix. |
| output_format | facultatif | chaîne | Le format audio souhaité. La valeur par défaut est pcm_24000. Les options incluent :
|
| prerecording | facultatif | nombre entier | 1 (normal, par défaut), 2 (amélioration par IA / Tashkeel arabe) ou 3 (IA Poète). Influence le coût en crédits. Les options 2 et 3 ne sont disponibles que pour le contenu en arabe ; voir la langue. |
| language | facultatif | chaîne | Langue du contenu sous forme de code ISO 639-1, par exemple « ar » ou « en » (les codes régionaux tels que « ar-JO » sont acceptés). Ce paramètre détermine les modes de pré-enregistrement autorisés et n'est pas transmis à la voix. Les modes 2 et 3 ne sont disponibles que pour l'arabe (ar). Si la langue n'est pas spécifiée, les modes 2 et 3 correspondent par défaut à l'arabe, garantissant ainsi le fonctionnement des intégrations existantes. L'utilisation de toute autre langue avec les modes 2 ou 3, ou d'un code inconnu, entraîne l'affichage d'un message d'erreur et empêche l'initialisation du flux. |
| voice_settings | facultatif | objet | Options de personnalisation de la voix. Voir la section Paramètres vocaux ci-dessous. |
Objet de paramètres vocaux
Le streaming fonctionne avec les deux moteurs à son propre tarif par caractère, multiplié selon le mode : emotion (par défaut) et fast_mode ×1, quality et studio ×2. Les voix du moteur avancé coûtent ×1,5.
- Les voix du moteur standard sont diffusées dans tous les modes : emotion (par défaut, latence la plus faible), quality et studio. fast_mode bascule vers le modèle à faible latence.
- Les voix du moteur avancé sont diffusées phrase par phrase : l'audio de chaque phrase démarre dès qu'elle est complète. Utilisez les formats pcm_* ou mp3_* (Opus n'est pas disponible pour ces voix).
Voix du moteur standard
| Paramètre | Type | Gamme | Par défaut | Description |
|---|---|---|---|---|
| mode | chaîne | emotion, quality, studio | emotion | Facultatif. emotion (Émotion et dialecte, ×1), quality (Émotion et dialecte haute qualité, ×2) ou studio (Qualité studio, ×2). En emotion et quality, seuls temperature et similarity s’appliquent. |
| temperature | nombre entier | 0 – 100 | 25 | Plus bas = stable et prévisible, plus élevé = créatif et varié. |
| similarity | nombre entier | 0 – 100 | 100 | À quel point la parole correspond au clone vocal original. |
| speed | flotter | 0.5 – 2.0 | 1.0 | Multiplicateur de vitesse de lecture. |
| fast_mode | nombre entier | 0, 1, or 2 | 0 | 1 ou 2 bascule vers le modèle à faible latence (×1 crédit) et remplace mode. 0 = désactivé. |
Voix du moteur avancé
| Paramètre | Type | Valeurs | Description |
|---|---|---|---|
| context | chaîne | jusqu'à 500 caractères | Le réglage le plus puissant. Décrivez l'accent, l'émotion, l'ambiance ou l'objectif. |
| setting | chaîne | jusqu'à 500 caractères | Cadre et ambiance. |
| style | chaîne | neutral, warm, energetic, serious, cheerful, poetic | Style de diction général. |
| pace | chaîne | slow, normal, fast | Rythme de parole. |
Astuce : envoyez des phrases complètes (se terminant par . ! ? ou un retour à la ligne) pour obtenir le premier audio le plus vite.
Pipeline de streaming
1. Envoyer des segments de texte
Envoyez le texte au fur et à mesure que votre LLM le génère :
{"type": "text", "data": "مرحبا بكم."}
Le serveur traitera instantanément le segment, déduira les crédits correspondant à cette durée et commencera à diffuser l’audio en retour.
2. Signal de fin (Arrêt)
Une fois la génération de texte entièrement terminée, envoyez le signal d’arrêt :
{"type": "stop"}
Le serveur terminera la synthèse du texte restant dans sa mémoire tampon, vous transmettra les derniers octets audio et enverra le signal de fin de flux.
Réception de messages
Le serveur transmet deux types de trames via le WebSocket :
1. Segments audio binaires (PCM / MP3)
Octets audio bruts diffusés en continu au fur et à mesure de leur génération. Le format dépend du paramètre `output_format` demandé (par défaut : PCM 16 bits à 24 kHz). Si vous avez demandé le format MP3, vous pouvez écrire ces octets directement dans un fichier.
2. Messages de contrôle JSON
Initialisation prête :
{"status": "ready", "message": "Initialisé et prêt à recevoir du texte."}
Fin de flux (signal de fermeture sécurisée) :
{"type": "end_of_stream"}
Lorsque vous recevez ce message, cela garantit mathématiquement que 100 % des fragments audio ont été livrés. Vous pouvez désormais fermer en toute sécurité la connexion WebSocket côté client.
Erreur en cours de traitement :
{"error": "Crédits insuffisants pendant le flux"}
Exemples prêts pour la production
# pip install websockets
import asyncio
import websockets
import json
API_KEY = "YOUR_API_KEY"
url = "wss://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://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://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://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"}
Fermer les codes et les erreurs
La connexion WebSocket peut se fermer avec l’un de ces codes standard :
| Code | Type | Description |
|---|---|---|
1000 |
SUCCÈS | Le flux s’est terminé naturellement. |
3011 |
ERREUR_DE_GÉNÉRATION | La génération audio a échoué au niveau de l’API en amont. Veuillez réessayer la requête. |
4001 |
CLÉ_API_MANQUANTE | Aucune clé API fournie dans l’en-tête Authorization. |
4002 |
ÉCHEC_AUTHENTIFICATION | Clé invalide, compte inactif, crédits initiaux insuffisants ou restriction IP. |
4290 |
LIMITE_DE_CONCURRENCE | L’utilisateur dispose déjà d’une connexion WebSocket TTS active. La limite est de 1 par utilisateur. |
Pour toute question ou tout problème concernant l’API, contactez-nous à l’adresse api@moknah.io.