Moknah Documents
Commencez gratuitement
Référence de l’API

Synthèse vocale (TTS) en temps réel

Diffusez du texte en continu et recevez instantanément des octets audio PCM bruts ou MP3.

WSS /api/v1/tts/ws/

É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.

⚡ Optimisation de la latence (TTFB)

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 :
  • 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
Pour la diffusion d’applications sans latence, utilisez le format PCM. Pour l’enregistrement de fichiers, demandez le format MP3.
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.
Support API

Pour toute question ou tout problème concernant l’API, contactez-nous à l’adresse api@moknah.io.