88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Audio

API vocales 88API : TTS et STT

Guide d'intégration des modèles vocaux Grok et Gemini : synthèse vocale avec /v1/audio/speech, synthèse vocale en streaming via WebSocket, conversation vocale Grok en temps réel, transcription avec /v1/audio/transcriptions et par chat audio, avec toutes les voix, formats de sortie, champs de requête, exemples cURL, SDK OpenAI, Python et Node.js.

88API propose deux familles de modèles vocaux : Grok et Gemini. Les modèles, points de terminaison et champs diffèrent entre la synthèse vocale (TTS) et la transcription de la parole (STT) ; choisissez à l'aide du tableau ci-dessous.

Modèles et points de terminaison

FonctionModèlesPoint de terminaisonFacturation
Synthèse vocalegrok-ttsPOST /v1/audio/speechNombre de caractères en entrée
Synthèse vocale en streaminggrok-ttsWebSocket /v1/ttsNombre de caractères en entrée
Conversation vocale en temps réelgrok-voice-latest, grok-voice-3.0WebSocket /v1/realtimeDurée de la session
Synthèse vocalegemini-3.8-flash-ttsgenerateContent natif Gemini (renvoie un lien de téléchargement de l'audio)Tokens
Transcription de la parolegrok-sttPOST /v1/audio/transcriptionsDurée audio
Transcription de la parolegemini-3-stt, gemini-3.5-stt, gemini-3.5-transcribePOST /v1/audio/transcriptions, POST /v1/chat/completions (entrée audio), ou generateContent natif GeminiTokens
  • Les tarifs en vigueur sont ceux affichés dans la place de marché des modèles de la console. Pour le groupe du jeton, choisissez 语音模型 (nom du groupe affiché dans la console) ou le groupe automatique.
  • Les modèles vocaux ne fonctionnent qu'avec les points de terminaison du tableau ci-dessus. Appeler un modèle TTS ou grok-stt via les interfaces Chat, Responses ou Messages renvoie 400, avec un message indiquant le bon point de terminaison.
  • Le point de terminaison /v1/audio/translations (traduction audio vers l'anglais) n'est pas proposé.
  • /v1/audio/speech renvoie l'audio complet en une seule réponse. Le streaming n'est pas pris en charge : stream_format: "sse" renvoie 400. Pour lire l'audio pendant la synthèse, utilisez la synthèse vocale Grok en streaming.

URL de base et authentification :

Base URL: https://api.88api.ai/v1
Authorization: Bearer $API_KEY

Synthèse vocale Grok (grok-tts)

cURL

curl --fail-with-body https://api.88api.ai/v1/audio/speech \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-tts",
    "input": "Bienvenue sur le service de synthèse vocale 88API.",
    "voice": "eve",
    "language": "fr",
    "response_format": "mp3"
  }' \
  --output speech.mp3

En cas de succès, la réponse est de l'audio binaire, pas du JSON : écrivez-la directement dans un fichier. Sous Windows, passer du texte non ASCII avec -d peut le corrompre ; enregistrez le corps de la requête dans un fichier UTF-8 et envoyez-le avec --data-binary @request.json.

Champs de la requête

ChampTypeObligatoirePar défautDescription
modelstringOui—grok-tts
inputstringOui—Texte à lire, non vide ; peut contenir les balises d'expression décrites plus bas
voicestringNoneveVoir le tableau des voix ci-dessous, insensible à la casse. Les noms de voix OpenAI comme alloy ou nova renvoient 400
response_formatstringNonmp3mp3, wav, pcm, mulaw, alaw ; opus, aac et flac renvoient 400
languagestringNonDétection automatiqueCode de langue, par ex. zh, en, ja, ko, fr, ru, vi, pt-BR. Fixer la langue est plus stable que la détection automatique
speednumberNon1.0Facteur de vitesse, de 0.7 à 1.5 ; hors plage, renvoie 400
sample_rateintegerNon240008000, 16000, 22050, 24000, 44100, 48000 ; toute autre valeur renvoie 400
bit_rateintegerNon128000MP3 uniquement : 32000, 64000, 96000, 128000, 192000
text_normalizationbooleanNonfalseSi true, les nombres, abréviations et symboles sont d'abord convertis en forme parlée avant la synthèse
replaceobjectNon—Table de remplacement de prononciation, par ex. {"nginx": "engine x"} : la clé est le texte d'origine, la valeur la prononciation

sample_rate, bit_rate, text_normalization et replace sont des champs d'extension Grok ; avec le SDK OpenAI, passez-les via extra_body. Le champ instructions n'a aucun effet sur grok-tts : contrôlez le ton avec les balises d'expression.

Formats de sortie

response_formatContent-TypeDescription
mp3audio/mpeg24 kHz et 128 kbps par défaut, lisible directement
wavaudio/wav16 bits mono, adapté à la post-production
pcmaudio/pcmPCM brut 16 bits mono, sans en-tête, à décoder selon la fréquence d'échantillonnage
mulawaudio/basicG.711 μ-law, pour la téléphonie, souvent avec sample_rate: 8000
alawaudio/alawG.711 A-law, pour la téléphonie, souvent avec sample_rate: 8000

pcm, mulaw et alaw ne peuvent pas être lus directement dans un navigateur ; pour la lecture sur le web, utilisez mp3 ou wav.

Voix

Toutes les voix peuvent lire n'importe quelle langue prise en charge, et leurs noms sont insensibles à la casse. Les descriptions de style proviennent du tableau officiel des voix xAI ; écoutez deux ou trois voix sur vos propres textes avant d'en fixer une.

VoixStyleUsages
eveÉnergique, enjouée, accent britannique (par défaut)Général
araChaleureuse, amicaleGénéral
rexAssurée, claireGénéral
salFluide, équilibréeGénéral
leoAutoritaire, puissante, accent britanniqueGénéral
carinaDouce, empathique, apaisanteBien-être, service client
zaganPuissante, dramatiquePersonnages, narration
helixAudacieuse, dynamiqueCommentaire, podcast
orionRiche, cinématographiqueNarration, livres audio
lunaDouce, patienteÉducation, assistant
irisAmicale, enjouéeVente, service client
altairÉlégante, raffinéePublicité, narration
zenithIncisive, concentréeVente, publicité
perseusSolide, digne de confiancePublicité, narration
heliosEnjouée, énergiqueAssistant, bien-être
luxPosée, sageBien-être, narration
keplerInventive, charismatiquePublicité, podcast
rigelPrécise, professionnelle, accent australienAssistant, service client
cosmoLumineuse, curieuse, facile à suivreÉducation, podcast
celesteBienveillante, rassuranteService client, assistant
ursaAmicale, chaleureuse, fiableAssistant, podcast
siriusVive d'esprit, espiègleCommentaire, personnages
lumenChaleureuse, bien articuléeÉducation, publicité
castorAccessible, décontractéeVente, service client
nakshChaleureuse, sage, accent indienAssistant, service client
atlasAssurée, imposanteVente, assistant
auroraSereine, stableService client, assistant
lioraCalme, ancréeBien-être, assistant

Un nom de voix absent du tableau ci-dessus renvoie 400, et le message d'erreur indique les voix disponibles.

Balises d'expression

Insérez des balises dans input pour contrôler les pauses, les rires, le chuchotement et d'autres effets ; la description complète figure dans la documentation officielle xAI.

TypeBalises
Ponctuelles (à placer là où le son doit se produire)[pause] [long-pause] [laugh] [chuckle] [giggle] [cry] [sigh] [breath] [inhale] [exhale] [tsk] [tongue-click] [lip-smack] [hum-tune]
Englobantes (par paires, autour d'un passage)<whisper> <soft> <loud> <build-intensity> <decrease-intensity> <higher-pitch> <lower-pitch> <slow> <fast> <emphasis> <sing-song> <singing>
{
  "model": "grok-tts",
  "voice": "eve",
  "input": "J'ai poussé la porte, [pause] et il était là. [laugh] <whisper>C'est un secret.</whisper> <slow><soft>Bonne nuit.</soft></slow>"
}

Les balises englobantes doivent être fermées et peuvent être imbriquées ; englober une phrase entière donne un résultat plus naturel que d'englober un ou deux mots seulement.

Python (SDK OpenAI)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_88API_KEY",
    base_url="https://api.88api.ai/v1",
)

with client.audio.speech.with_streaming_response.create(
    model="grok-tts",
    voice="eve",
    input="Bienvenue sur le service de synthèse vocale 88API.",
    response_format="mp3",
    extra_body={"language": "fr", "sample_rate": 44100},
) as response:
    response.stream_to_file("speech.mp3")

Node.js (SDK OpenAI)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.88api.ai/v1",
});

const speech = await client.audio.speech.create({
  model: "grok-tts",
  voice: "ara",
  input: "Hello from 88API. [laugh] <whisper>This part is a secret.</whisper>",
  response_format: "wav",
});
fs.writeFileSync("speech.wav", Buffer.from(await speech.arrayBuffer()));

Synthèse vocale Grok en streaming (WebSocket)

Adaptée aux cas où un grand modèle de langage lit le texte au fur et à mesure qu'il le génère et où la lecture doit démarrer le plus tôt possible : le texte peut être envoyé en plusieurs fois, l'audio est renvoyé au fil de la synthèse, et le premier fragment audio arrive généralement en 0,3 seconde environ. Le modèle, les voix, les balises d'expression et le tarif sont identiques à ceux de grok-tts.

Connexion

wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=fr
Authorization: Bearer $API_KEY

Tous les paramètres se placent dans la chaîne de requête de l'URL de connexion :

ParamètreObligatoirePar défautDescription
modelOui—grok-tts
voiceNoneveVoir le tableau des voix ci-dessus
codecNonmp3mp3, wav, pcm, mulaw (ou ulaw), alaw ; opus, aac et flac ne sont pas pris en charge
languageNonDétection automatiqueCode de langue, par ex. zh, en, ja
sample_rateNon240008000, 16000, 22050, 24000, 44100, 48000
bit_rateNon128000MP3 uniquement : 32000, 64000, 96000, 128000, 192000
speedNon1.0Facteur de vitesse, de 0.7 à 1.5
text_normalizationNonfalsetrue ou false ; si true, les nombres, abréviations et symboles sont d'abord convertis en forme parlée avant la synthèse

Messages

Une fois la connexion établie, les deux côtés échangent des messages texte JSON :

SensMessageDescription
Envoyé par le client{"type": "text.delta", "delta": "..."}Ajoute du texte à lire ; peut être envoyé plusieurs fois de suite
Envoyé par le client{"type": "text.done"}Le texte de ce segment a été entièrement envoyé
Renvoyé par le serveuraudio.deltadelta est un fragment audio encodé en Base64 ; concaténez les fragments dans l'ordre de réception pour obtenir l'audio complet
Renvoyé par le serveuraudio.doneTout l'audio de ce segment a été renvoyé
Renvoyé par le serveurerrorÉchec de la synthèse de ce segment ; détails dans le message

Exemple de réponse réelle :

{"type": "audio.delta", "delta": "//PExABLjDncBN4ZECBPfcTHl40IKQ..."}
{"type": "audio.done", "trace_id": "a52a926b-726f-439c-bbeb-5d741dd497ad"}
  • Après réception de audio.done, la connexion reste ouverte : vous pouvez envoyer les text.delta et text.done du segment suivant sans vous reconnecter.
  • La facturation se fait au nombre de caractères du texte des segments pour lesquels l'audio a effectivement été synthétisé, au même tarif que grok-tts ; les segments dont la synthèse a échoué et les connexions sans texte envoyé ne sont pas facturés.
  • Seuls les messages texte JSON sont acceptés ; n'envoyez pas de trames binaires.
  • Les paramètres sont validés avant l'établissement de la connexion : si voice ne figure pas dans le tableau des voix (y compris les noms de voix OpenAI), ou si codec, sample_rate, speed ou un autre paramètre a une valeur invalide, la poignée de main renvoie directement HTTP 400 et aucune connexion WebSocket n'est établie ; le message d'erreur indique les valeurs acceptées.

Python

Nécessite websockets 14 ou une version ultérieure (pip install websockets).

import asyncio
import base64
import json

import websockets

API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=fr"


async def main():
    async with websockets.connect(
        URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
    ) as ws:
        segments = [
            ["Bienvenue sur la synthèse vocale ", "en streaming de 88API : ", "le texte est lu au fil de sa génération."],
            ["La même connexion peut ensuite synthétiser le segment suivant."],
        ]
        for i, pieces in enumerate(segments):
            for text in pieces:
                await ws.send(json.dumps({"type": "text.delta", "delta": text}))
            await ws.send(json.dumps({"type": "text.done"}))

            with open(f"part{i + 1}.mp3", "wb") as f:
                async for message in ws:
                    event = json.loads(message)
                    if event["type"] == "audio.delta":
                        f.write(base64.b64decode(event["delta"]))
                    elif event["type"] == "audio.done":
                        break
                    elif event["type"] == "error":
                        raise RuntimeError(event)


asyncio.run(main())

Node.js

Utilise la bibliothèque ws (npm install ws).

import fs from "node:fs";
import WebSocket from "ws";

const url = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=ara&codec=mp3&language=fr";
const ws = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const chunks = [];

ws.on("open", () => {
  for (const delta of ["J'ai poussé la porte, ", "[pause] et il était là. ", "<whisper>C'est un secret.</whisper>"]) {
    ws.send(JSON.stringify({ type: "text.delta", delta }));
  }
  ws.send(JSON.stringify({ type: "text.done" }));
});

ws.on("message", (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === "audio.delta") {
    chunks.push(Buffer.from(event.delta, "base64"));
  } else if (event.type === "audio.done") {
    fs.writeFileSync("speech.mp3", Buffer.concat(chunks));
    ws.close();
  } else if (event.type === "error") {
    console.error(event);
    ws.close();
  }
});

Transcription Grok (grok-stt)

cURL

Envoyez l'audio en multipart/form-data. Laissez cURL ou votre SDK générer la limite multipart ; ne définissez pas vous-même l'en-tête Content-Type: multipart/form-data.

curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=grok-stt" \
  -F "language=fr" \
  -F "keyterm=88API" \
  -F "file=@./meeting.mp3"

Réponse :

{
  "text": "Bienvenue sur le service de synthèse vocale 88API, nous sommes le 17 octobre 2026."
}

Champs de la requête

ChampTypeObligatoirePar défautDescription
filefileOui—Fichier audio ou vidéo : mp3, wav, ogg, opus, flac, aac, m4a, mp4, mkv ; le webm enregistré par un navigateur est aussi accepté
modelstringOui—grok-stt
response_formatstringNonjsonjson, text, verbose_json ; srt et vtt renvoient 400
languagestringNonDétection automatiqueCode de langue, par ex. zh, en, ja, yue (cantonais) ; le préciser rend la reconnaissance plus stable
formatbooleanNonfalseSi true, les nombres, montants, etc. prononcés sont convertis en forme écrite ; nécessite aussi language
keytermstringNon—Termes propres à reconnaître en priorité, comme des noms de produits ou de personnes ; peut être répété, un terme à la fois. Par exemple des noms de produits comme 88API
filler_wordsbooleanNonfalseSi true, les mots de remplissage comme « euh » ou « hum » sont conservés ; par défaut ils sont supprimés

Les champs OpenAI prompt, temperature et timestamp_granularities n'ont aucun effet sur grok-stt et sont ignorés. Pour que le modèle reconnaisse correctement des noms propres, utilisez keyterm.

Formats de réponse

response_formatContent-TypeContenu
jsonapplication/json{"text": "..."}
texttext/plainTexte brut
verbose_jsonapplication/jsontext, language, duration (secondes) et horodatage mot à mot words (word, start, end)

Exemple verbose_json :

{
  "task": "transcribe",
  "language": "fr",
  "duration": 6.768,
  "text": "Bienvenue sur le service de synthèse vocale 88API, nous sommes le 17 octobre 2026.",
  "words": [
    { "word": "Bienvenue", "start": 0.12, "end": 0.621 },
    { "word": "sur", "start": 0.681, "end": 0.781 }
  ]
}

Python (SDK OpenAI)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_88API_KEY",
    base_url="https://api.88api.ai/v1",
)

with open("meeting.mp3", "rb") as audio_file:
    result = client.audio.transcriptions.create(
        model="grok-stt",
        file=audio_file,
        language="fr",
        response_format="verbose_json",
        extra_body={"format": "true", "keyterm": "88API"},
    )

print(result.text, result.duration)

Node.js (SDK OpenAI)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.88api.ai/v1",
});

const transcription = await client.audio.transcriptions.create({
  model: "grok-stt",
  file: fs.createReadStream("meeting.mp3"),
  language: "fr",
});
console.log(transcription.text);

Conversation vocale Grok en temps réel (grok-voice)

Dialoguez à la voix en temps réel avec le modèle via une seule connexion WebSocket : envoyez du texte ou l'audio du micro, le modèle répond directement à la voix et fournit en même temps la transcription. Adapté aux assistants vocaux, au service client téléphonique, à l'entraînement à l'oral, etc.

ModèleDescription
grok-voice-latestPointe toujours vers la dernière version, actuellement grok-voice-3.0
grok-voice-3.0Version figée

Connexion

wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEY

Le protocole d'événements est identique à celui de xAI Realtime. Une fois la connexion établie, le serveur envoie d'abord session.created et conversation.created ; le client configure ensuite la session et démarre la conversation.

  • Par défaut, l'audio est envoyé et reçu encodé en Base64 dans des événements JSON. Vous pouvez aussi passer au transport binaire : l'audio brut transite alors directement par des trames binaires WebSocket, voir Transport audio binaire.
  • Le WebSocket du navigateur ne permet pas de définir l'en-tête Authorization, et la clé API ne doit pas être exposée côté front-end. Établissez la connexion depuis votre propre serveur, puis relayez l'audio vers le navigateur ou l'application.
  • Format audio : en entrée comme en sortie, PCM16 (16 bits little-endian), 24 kHz, mono.

Configurer la session

{
  "type": "session.update",
  "session": {
    "voice": "eve",
    "instructions": "Tu es l'assistant vocal de 88API. Réponds de façon concise.",
    "turn_detection": { "type": "server_vad" }
  }
}
ChampDescription
voiceVoix de la réponse, parmi les 28 voix de grok-tts (voir le tableau des voix ci-dessus), insensible à la casse ; ara par défaut
instructionsInstructions système : rôle, ton, longueur des réponses, etc.
turn_detection{"type": "server_vad"} : le serveur répond automatiquement dès qu'il détecte que vous avez fini de parler ; null (par défaut) : vous devez valider l'audio et demander la réponse manuellement
  • Si voice ne figure pas dans le tableau des voix (y compris les noms de voix OpenAI), vous recevez un événement error dont error.param vaut session.voice. Ce session.update n'est alors pas appliqué du tout, mais la connexion reste ouverte : corrigez la valeur et renvoyez-le.
  • session.updated ne renvoie pas la voix. La voix actuelle n'apparaît que dans le session.created reçu à la connexion, par exemple xai_ara par défaut.

Événements client

ÉvénementDescription
session.updateDéfinit la voix, les instructions système et la détection de tour de parole
conversation.item.createEnvoie un message texte (input_text dans content)
response.createDemande une réponse au modèle
input_audio_buffer.appendAjoute un fragment audio ; audio contient des données PCM16 encodées en Base64, idéalement environ 100 ms par envoi
input_audio_buffer.commitValide l'audio ajouté comme un message utilisateur ; à utiliser quand turn_detection vaut null

Envoyer du texte :

{"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Présente-toi en une phrase."}]}}
{"type": "response.create"}

Envoyer de la voix : envoyez des input_audio_buffer.append à la suite. Avec server_vad activé, un court silence après la fin de la parole déclenche la réponse automatique ; si turn_detection vaut null, envoyez input_audio_buffer.commit puis response.create une fois l'audio envoyé.

Événements serveur

ÉvénementDescription
session.created, session.updatedSession créée, configuration appliquée
input_audio_buffer.speech_started / speech_stoppedserver_vad a détecté le début ou la fin de la parole
conversation.item.input_audio_transcription.completedTexte reconnu de la parole de l'utilisateur, dans transcript
response.output_audio.deltaFragment audio de la réponse ; delta est du PCM16 24 kHz mono encodé en Base64
response.output_audio_transcript.delta / .doneTranscription de la réponse ; le transcript de .done contient le texte complet
response.doneFin de la réponse pour ce tour
pingBattement de cœur, peut être ignoré
errorErreur ; détails dans error.message et error.code

Réponse réelle (extrait) à ce message texte, avec la configuration de session ci-dessus :

{"type": "response.output_audio_transcript.delta", "delta": "Je suis l'assistant vocal de 88API, prêt à vous aider."}
{"type": "response.output_audio.delta", "delta": "<audio en Base64>"}
{"type": "response.output_audio_transcript.done", "transcript": "Je suis l'assistant vocal de 88API, prêt à vous aider."}
{"type": "response.output_audio.done"}
{"type": "response.done", "response": {"status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "audio", "transcript": "Je suis l'assistant vocal de 88API, prêt à vous aider."}]}]}}

Facturation

  • Facturation à la durée de la session : décomptée à la seconde, de l'établissement à la fermeture de la connexion, temps morts sans parole compris ; fermez la connexion dès que vous avez terminé. Les tarifs sont affichés dans la place de marché des modèles de la console.
  • Chaque message texte de l'utilisateur (conversation.item.create avec input_text) entraîne un petit coût supplémentaire ; l'entrée vocale et les réponses vocales du modèle ne sont pas facturées séparément.
  • Si le solde ou le quota du jeton ne couvre pas 1 minute de conversation, vous recevez une error (code : insufficient_user_quota) dès l'établissement de la connexion, puis celle-ci est fermée. Si le solde s'épuise en cours de conversation, la même error arrive dans les 30 secondes, puis la connexion est fermée avec le code 1008.

Python

Nécessite websockets 14 ou une version ultérieure (pip install websockets). L'exemple suivant envoie un message texte et enregistre la réponse vocale dans reply.wav :

import asyncio
import base64
import json
import wave

import websockets

API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"


async def main():
    async with websockets.connect(
        URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
    ) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "voice": "eve",
                "instructions": "Tu es l'assistant vocal de 88API. Réponds de façon concise.",
                "turn_detection": {"type": "server_vad"},
            },
        }))
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "message",
                "role": "user",
                "content": [{"type": "input_text", "text": "Présente-toi en une phrase."}],
            },
        }))
        await ws.send(json.dumps({"type": "response.create"}))

        audio = bytearray()
        async for message in ws:
            event = json.loads(message)
            if event["type"] == "response.output_audio.delta":
                audio += base64.b64decode(event["delta"])
            elif event["type"] == "response.output_audio_transcript.done":
                print("Transcription :", event["transcript"])
            elif event["type"] == "response.done":
                break
            elif event["type"] == "error":
                raise RuntimeError(event)

    with wave.open("reply.wav", "wb") as f:
        f.setnchannels(1)
        f.setsampwidth(2)
        f.setframerate(24000)
        f.writeframes(bytes(audio))


asyncio.run(main())

Pour envoyer de la voix, transmettez l'audio 24 kHz, 16 bits, mono par fragments. Avec la session ci-dessus, où server_vad est activé, vous pouvez remplacer les deux messages d'envoi de texte par :

with wave.open("question.wav", "rb") as f:  # 24 kHz, 16 bits, mono
    pcm = f.readframes(f.getnframes())
pcm += b"\x00" * 48000  # ajoute 1 s de silence à la fin pour que server_vad détecte la fin de la parole

for i in range(0, len(pcm), 4800):  # 100 ms par envoi
    await ws.send(json.dumps({
        "type": "input_audio_buffer.append",
        "audio": base64.b64encode(pcm[i:i + 4800]).decode(),
    }))

Pour une entrée micro en temps réel, envoyez directement l'audio capturé, sans ajouter de silence.

Node.js

Utilise la bibliothèque ws (npm install ws). Cet exemple désactive server_vad, demande manuellement la réponse après l'envoi du texte et enregistre la réponse dans reply.wav :

import fs from "node:fs";
import WebSocket from "ws";

const ws = new WebSocket("wss://api.88api.ai/v1/realtime?model=grok-voice-latest", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const send = (event) => ws.send(JSON.stringify(event));
const chunks = [];

// Ajoute un en-tête WAV aux données PCM16 24 kHz mono
function toWav(pcm, rate = 24000) {
  const header = Buffer.alloc(44);
  header.write("RIFF", 0);
  header.writeUInt32LE(36 + pcm.length, 4);
  header.write("WAVEfmt ", 8);
  header.writeUInt32LE(16, 16);
  header.writeUInt16LE(1, 20);
  header.writeUInt16LE(1, 22);
  header.writeUInt32LE(rate, 24);
  header.writeUInt32LE(rate * 2, 28);
  header.writeUInt16LE(2, 32);
  header.writeUInt16LE(16, 34);
  header.write("data", 36);
  header.writeUInt32LE(pcm.length, 40);
  return Buffer.concat([header, pcm]);
}

ws.on("open", () => {
  send({
    type: "session.update",
    session: { voice: "rex", instructions: "Réponds en une phrase.", turn_detection: null },
  });
  send({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [{ type: "input_text", text: "Quelle est la capitale de la France ?" }],
    },
  });
  send({ type: "response.create" });
});

ws.on("message", (data) => {
  const event = JSON.parse(data.toString());
  switch (event.type) {
    case "response.output_audio.delta":
      chunks.push(Buffer.from(event.delta, "base64"));
      break;
    case "response.output_audio_transcript.delta":
      process.stdout.write(event.delta);
      break;
    case "response.done":
      fs.writeFileSync("reply.wav", toWav(Buffer.concat(chunks)));
      ws.close();
      break;
    case "error":
      console.error(event.error);
      ws.close();
      break;
  }
});

Transport audio binaire

Après avoir défini transport sur "binary" pour l'entrée et la sortie dans session.update, l'audio PCM brut est envoyé et reçu directement sous forme de trames binaires WebSocket, sans encodage ni décodage Base64 :

{
  "type": "session.update",
  "session": {
    "turn_detection": null,
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" }
    }
  }
}
  • Envoi : chaque trame binaire contient un segment d'audio brut PCM16, 24 kHz, mono ; nous recommandons 100 ms par trame (4800 octets). Elle remplace input_audio_buffer.append.
  • Réception : l'audio de la réponse arrive sous forme de trames binaires, sans événement response.output_audio.delta ; il suffit de concaténer les trames dans l'ordre de réception.
  • Les événements de contrôle comme input_audio_buffer.commit et response.create, ainsi que les événements serveur comme session.updated, la transcription et response.done, restent des trames texte JSON.
  • La facturation est inchangée.

Exemple Python : envoie une question vocale et enregistre la réponse vocale dans reply.wav :

import asyncio
import json
import wave

import websockets

API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
PCM = {"type": "audio/pcm", "rate": 24000}


async def main():
    async with websockets.connect(
        URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
    ) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "voice": "eve",
                "turn_detection": None,
                "audio": {
                    "input": {"format": PCM, "transport": "binary"},
                    "output": {"format": PCM, "transport": "binary"},
                },
            },
        }))

        with wave.open("question.wav", "rb") as f:  # 24 kHz, 16 bits, mono
            pcm = f.readframes(f.getnframes())
        for i in range(0, len(pcm), 4800):  # 100 ms par trame, envoi direct du PCM brut
            await ws.send(pcm[i:i + 4800])
        await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
        await ws.send(json.dumps({"type": "response.create"}))

        audio = bytearray()
        async for message in ws:
            if isinstance(message, bytes):  # trame binaire : audio de la réponse
                audio += message
                continue
            event = json.loads(message)  # trame texte : événement de contrôle
            if event["type"] == "response.output_audio_transcript.done":
                print("Transcription :", event["transcript"])
            elif event["type"] == "response.done":
                break
            elif event["type"] == "error":
                raise RuntimeError(event)

    with wave.open("reply.wav", "wb") as f:
        f.setnchannels(1)
        f.setsampwidth(2)
        f.setframerate(24000)
        f.writeframes(bytes(audio))


asyncio.run(main())

Synthèse vocale Gemini

La synthèse vocale Gemini ne propose plus que gemini-3.8-flash-tts, qui s'appelle via l'interface native Gemini ; /v1/audio/speech n'est pas pris en charge (la requête renvoie 500 « 模型没有返回音频 » (le modèle n'a renvoyé aucun audio), sans facturation). Les anciens gemini-3.1-flash-tts, gemini-3.8-flash-lite-tts, gemini-2.5-flash-tts et gemini-2.5-pro-tts ne sont plus proposés ; si vous avez besoin de /v1/audio/speech ou d'audio en streaming, utilisez la synthèse vocale Grok.

cURL

La clé reste votre clé API 88API et peut être passée dans l'en-tête x-goog-api-key.

curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "role": "user", "parts": [{ "text": "Bienvenue sur le service de synthèse vocale 88API. <laugh> Quelle belle journée." }] }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }
      }
    }
  }'

Réponse et téléchargement

La réponse est du JSON qui ne contient pas de données audio : candidates[0].content.parts[0].text renvoie un lien de téléchargement de l'audio, au format lien Markdown (le texte du lien est toujours « 生成音频 », « audio généré ») :

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "text": "[生成音频](https://example.com/contents/xxxxxxxx.wav)" }]
    },
    "finishReason": "STOP"
  }]
}
  • Extrayez du texte l'adresse entre parenthèses et téléchargez-la ; le téléchargement ne nécessite pas de clé API. L'audio est un fichier WAV (24 kHz, 16 bits, mono).
  • Le lien n'est conservé que quelques heures et ne peut plus être téléchargé ensuite : téléchargez et enregistrez l'audio dès réception de la réponse.
  • La facturation porte sur les tokens d'entrée et de sortie ; les tarifs en vigueur sont ceux affichés dans la place de marché des modèles de la console.
  • Le point de terminaison en streaming POST /v1beta/models/gemini-3.8-flash-tts:streamGenerateContent?alt=sse peut être appelé, mais ne renvoie pas l'audio par fragments : une fois la synthèse terminée, il renvoie le même lien de téléchargement dans un seul événement.

Règles de lecture

  • Lecture mot pour mot : tout le texte est lu à voix haute. N'y écrivez pas de consigne comme « Dis sur un ton joyeux : », sinon cette phrase sera lue elle aussi.
  • Le ton se contrôle par des balises entre chevrons dans le texte ; les balises elles-mêmes ne sont pas lues, par exemple <laugh> (rire), <short pause> (courte pause), <whispers> (chuchotement), <sigh> (soupir).

Voix

La voix se définit dans speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName, parmi 30 voix prédéfinies. Les descriptions de style proviennent du tableau officiel des voix Google ; toutes les voix peuvent lire de nombreuses langues, dont le chinois.

VoixStyleGenre
AchernarDouceFéminine
AchirdAmicaleMasculine
AlgenibRauqueMasculine
AlgiebaFluideMasculine
AlnilamFermeMasculine
AoedeLégèreFéminine
AutonoeLumineuseFéminine
CallirrhoeDécontractéeFéminine
CharonInformativeMasculine
DespinaFluideFéminine
EnceladusSouffléeMasculine
ErinomeClaireFéminine
FenrirExaltéeMasculine
GacruxMûreFéminine
IapetusClaireMasculine
KoreFermeFéminine
LaomedeiaEnjouéeFéminine
LedaJeuneFéminine
OrusFermeMasculine
PuckEnjouéeMasculine
PulcherrimaDirecteFéminine
RasalgethiInformativeMasculine
SadachbiaViveMasculine
SadaltagerÉruditeMasculine
SchedarRégulièreMasculine
SulafatChaleureuseFéminine
UmbrielDécontractéeMasculine
VindemiatrixDélicateFéminine
ZephyrLumineuseFéminine
ZubenelgenubiInformelleMasculine

En cas de doute, commencez par Kore (féminine) et Charon (masculine). Pour les mises à jour des voix et des langues, la documentation officielle Google Gemini-TTS fait foi.

Dialogue à deux voix

Remplacez voiceConfig dans speechConfig par multiSpeakerVoiceConfig et attribuez une voix à chacun des 2 locuteurs au maximum. Écrivez seulement « Nom: réplique » sur chaque ligne du texte, sans consigne comme « TTS the following conversation… » (elle serait lue) :

{
  "contents": [{
    "role": "user",
    "parts": [{ "text": "Joe: How's it going today Jane?\nJane: Not too bad, how about you?" }]
  }],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "multiSpeakerVoiceConfig": {
        "speakerVoiceConfigs": [
          { "speaker": "Joe", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Charon" } } },
          { "speaker": "Jane", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }
        ]
      }
    }
  }
}

La réponse a la même forme que pour une seule voix : un lien de téléchargement WAV.

Transcription Gemini

ModèleRemarques
gemini-3-sttRecommandé pour la transcription courante, réunions, sous-titres
gemini-3.5-sttPour les audios plus difficiles ; prix unitaire plus élevé
gemini-3.5-transcribeModèle dédié à la transcription : détection automatique de plus de 85 langues, jusqu'à environ 1 heure d'audio par requête, rapide

Les trois modèles s'appellent de la même façon ; remplacez simplement le nom du modèle dans les exemples ci-dessous. Les particularités de gemini-3.5-transcribe sont décrites dans gemini-3.5-transcribe. Trois modes d'appel sont possibles : envoyer le fichier à /v1/audio/transcriptions (recommandé), transmettre l'audio via l'interface Chat, ou utiliser l'interface native Gemini.

Envoi de fichier (recommandé)

Comme pour grok-stt, envoyez l'audio en multipart/form-data ; ne définissez pas vous-même l'en-tête Content-Type: multipart/form-data.

curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gemini-3-stt" \
  -F "language=fr" \
  -F "file=@./meeting.mp3"

Réponse :

{
  "text": "Bienvenue sur le service de synthèse vocale 88 API. Nous sommes le 17 octobre 2026."
}
ChampTypeObligatoirePar défautDescription
filefileOui—Fichier audio ; les formats courants comme mp3, wav, m4a, ogg, flac sont acceptés, 25 Mo au maximum
modelstringOui—gemini-3-stt, gemini-3.5-stt ou gemini-3.5-transcribe
response_formatstringNonjsonjson ({"text": "..."}), text (texte brut), verbose_json (ajoute task, language, duration) ; srt et vtt renvoient 400
languagestringNonDétection automatiqueCode de langue, par ex. zh, en, yue (cantonais)
promptstringNon—Indications sur le contexte, les noms de personnes, les termes techniques, pour aider la reconnaissance ; sans effet avec gemini-3.5-transcribe

verbose_json ne contient ni horodatage mot à mot (words) ni segments (segments) ; pour l'horodatage mot à mot, utilisez grok-stt ou l'interface native de gemini-3.5-transcribe. Un fichier de plus de 25 Mo renvoie 400 : compressez-le (par exemple en MP3 mono 16 kHz) ou découpez-le avant la transcription.

Python (SDK OpenAI) :

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_88API_KEY",
    base_url="https://api.88api.ai/v1",
)

with open("meeting.mp3", "rb") as audio_file:
    result = client.audio.transcriptions.create(
        model="gemini-3-stt",
        file=audio_file,
        language="fr",
    )

print(result.text)

Interface Chat (entrée audio)

Placez l'audio en Base64 dans un message de chat ; le modèle renvoie la transcription selon vos consignes écrites. Vous pouvez préciser dans la consigne le contexte, les noms de personnes et les termes techniques pour aider le modèle à les reconnaître correctement.

cURL

Encodez d'abord l'audio en Base64, puis placez-le dans input_audio :

AUDIO_B64=$(base64 < meeting.mp3 | tr -d '\n')

cat > request.json <<EOF
{
  "model": "gemini-3-stt",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Transcris cet audio. Renvoie uniquement la transcription." },
      { "type": "input_audio", "input_audio": { "data": "$AUDIO_B64", "format": "mp3" } }
    ]
  }]
}
EOF

curl --fail-with-body https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

La transcription se trouve dans choices[0].message.content. Renseignez format avec le format audio, par ex. mp3 ou wav.

Python (SDK OpenAI)

import base64
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_88API_KEY",
    base_url="https://api.88api.ai/v1",
)

with open("meeting.mp3", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

completion = client.chat.completions.create(
    model="gemini-3-stt",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcris cet audio. Renvoie uniquement la transcription."},
            {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
        ],
    }],
)
print(completion.choices[0].message.content)

Node.js (SDK OpenAI)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.88api.ai/v1",
});

const audio = fs.readFileSync("meeting.mp3").toString("base64");
const completion = await client.chat.completions.create({
  model: "gemini-3-stt",
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "Transcris cet audio. Renvoie uniquement la transcription." },
      { type: "input_audio", input_audio: { data: audio, format: "mp3" } },
    ],
  }],
});
console.log(completion.choices[0].message.content);

Interface native Gemini

{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "Transcris cet audio. Renvoie uniquement la transcription." },
      { "inlineData": { "mimeType": "audio/wav", "data": "<audio en Base64>" } }
    ]
  }]
}

Envoyez cette requête à POST https://api.88api.ai/v1beta/models/gemini-3-stt:generateContent avec l'en-tête x-goog-api-key: $API_KEY.

L'interface Chat et l'interface native placent l'audio en Base64 dans le corps de la requête, ce qui convient aux enregistrements courts ; pour les fichiers volumineux, utilisez l'envoi de fichier. Les modèles retirés gemini-2.5-stt et gemini-3.6-stt doivent être remplacés par gemini-3-stt, gemini-3.5-stt ou grok-stt.

gemini-3.5-transcribe

Modèle dédié à la transcription : il suffit d'envoyer l'audio, aucune consigne écrite n'est nécessaire ni acceptée.

  • /v1/audio/transcriptions : renseignez language avec un code de langue BCP-47, par ex. zh, en, yue ; un code invalide renvoie 400. prompt est sans effet. Le modèle ne renvoie pas la langue détectée : le language de verbose_json reprend la valeur que vous avez envoyée, ou une chaîne vide si vous n'en avez pas envoyé.
  • Interface Chat : le texte des messages est ignoré et n'est pas facturé ; envoyez seulement input_audio. Un message system ou le paramètre reasoning_effort renvoie 400.
  • Interface native : generationConfig.audioTranscriptionConfig permet de préciser la langue, un vocabulaire personnalisé, la distinction des locuteurs et l'horodatage mot à mot.
  • La transcription en streaming en temps réel n'est pas disponible.

Exemple avec l'interface native :

curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "inlineData": { "mimeType": "audio/wav", "data": "<audio en Base64>" } }]
    }],
    "generationConfig": {
      "audioTranscriptionConfig": { "diarization": true, "wordTimestamp": true }
    }
  }'
Champ de audioTranscriptionConfigTypeDescription
languageCodesstring[]Langue de l'audio, en codes BCP-47, par ex. ["zh"] ; détection automatique si absent
customVocabularystring[]Noms propres à reconnaître en priorité, par ex. ["88API"] ; ces termes sont comptés dans l'usage en entrée
diarizationbooleanDistingue les locuteurs ; chaque segment du résultat porte un speakerLabel (fonction expérimentale)
wordTimestampbooleanRenvoie l'horodatage mot à mot words (fonction expérimentale)
modestringSMART : mode de transcription intelligente, traitement plus long ; incompatible avec diarization et wordTimestamp, sinon renvoie 400

Réponse réelle pour un dialogue à deux voix (candidates[0].content.parts, extrait) :

[
  {
    "text": "How's it going today, Jane?",
    "audioTranscription": {
      "text": "How's it going today, Jane?",
      "speakerLabel": "spk:0",
      "words": [
        { "word": "How's", "startOffset": "0.200s", "endOffset": "0.300s" },
        { "word": "it", "startOffset": "0.300s", "endOffset": "0.400s" }
      ]
    }
  },
  {
    "text": "Not too bad. How about you?",
    "audioTranscription": {
      "text": "Not too bad. How about you?",
      "speakerLabel": "spk:1",
      "words": [
        { "word": "Not", "startOffset": "2.100s", "endOffset": "2.200s" }
      ]
    }
  }
]

Sans distinction des locuteurs, la transcription complète se trouve dans parts[0].text. La distinction des locuteurs et l'horodatage mot à mot sont expérimentaux : sur un audio mêlant chinois et anglais, les passages dans la langue minoritaire peuvent être perdus. Si vous avez besoin du texte complet, désactivez ces deux options.

Erreurs courantes

CodeCause habituelleQue faire
400input / file manquant, nom de voix absent du tableau des voix (y compris les noms de voix OpenAI), format ou fréquence d'échantillonnage non pris en charge, speed hors plage, texte trop long, fichier envoyé de plus de 25 MoCorrigez la requête d'après le message d'erreur et les champs de cette page
400Modèle vocal appelé via les interfaces Chat, Responses ou MessagesUtilisez le point de terminaison indiqué sur cette page
400Texte bloqué par la politique de sécurité (PROHIBITED_CONTENT)Modifiez le texte puis réessayez ; renvoyer le même contenu ne résoudra rien
401Clé API absente ou invalideVérifiez le jeton Bearer et n'exposez jamais la clé dans le code côté navigateur
429Limite de débit, de quota ou de capacitéRéessayez avec un backoff exponentiel et vérifiez le solde du compte
500 / 502 / 503Incident temporaire côté serveur ou en amontRéessayez un nombre limité de fois ; en cas d'échec persistant, contactez le support avec l'ID de requête

Le request id des réponses d'erreur sert au diagnostic : conservez-le dans vos journaux. Ne journalisez jamais la clé API, les enregistrements privés ni les transcriptions sensibles.