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
| Fonction | Modèles | Point de terminaison | Facturation |
|---|---|---|---|
| Synthèse vocale | grok-tts | POST /v1/audio/speech | Nombre de caractères en entrée |
| Synthèse vocale en streaming | grok-tts | WebSocket /v1/tts | Nombre de caractères en entrée |
| Conversation vocale en temps réel | grok-voice-latest, grok-voice-3.0 | WebSocket /v1/realtime | Durée de la session |
| Synthèse vocale | gemini-3.8-flash-tts | generateContent natif Gemini (renvoie un lien de téléchargement de l'audio) | Tokens |
| Transcription de la parole | grok-stt | POST /v1/audio/transcriptions | Durée audio |
| Transcription de la parole | gemini-3-stt, gemini-3.5-stt, gemini-3.5-transcribe | POST /v1/audio/transcriptions, POST /v1/chat/completions (entrée audio), ou generateContent natif Gemini | Tokens |
- 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-sttvia les interfaces Chat, Responses ou Messages renvoie400, 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/speechrenvoie l'audio complet en une seule réponse. Le streaming n'est pas pris en charge :stream_format: "sse"renvoie400. 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_KEYSynthè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.mp3En 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
| Champ | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
model | string | Oui | — | grok-tts |
input | string | Oui | — | Texte à lire, non vide ; peut contenir les balises d'expression décrites plus bas |
voice | string | Non | eve | Voir le tableau des voix ci-dessous, insensible à la casse. Les noms de voix OpenAI comme alloy ou nova renvoient 400 |
response_format | string | Non | mp3 | mp3, wav, pcm, mulaw, alaw ; opus, aac et flac renvoient 400 |
language | string | Non | Détection automatique | Code de langue, par ex. zh, en, ja, ko, fr, ru, vi, pt-BR. Fixer la langue est plus stable que la détection automatique |
speed | number | Non | 1.0 | Facteur de vitesse, de 0.7 à 1.5 ; hors plage, renvoie 400 |
sample_rate | integer | Non | 24000 | 8000, 16000, 22050, 24000, 44100, 48000 ; toute autre valeur renvoie 400 |
bit_rate | integer | Non | 128000 | MP3 uniquement : 32000, 64000, 96000, 128000, 192000 |
text_normalization | boolean | Non | false | Si true, les nombres, abréviations et symboles sont d'abord convertis en forme parlée avant la synthèse |
replace | object | Non | — | 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_format | Content-Type | Description |
|---|---|---|
mp3 | audio/mpeg | 24 kHz et 128 kbps par défaut, lisible directement |
wav | audio/wav | 16 bits mono, adapté à la post-production |
pcm | audio/pcm | PCM brut 16 bits mono, sans en-tête, à décoder selon la fréquence d'échantillonnage |
mulaw | audio/basic | G.711 μ-law, pour la téléphonie, souvent avec sample_rate: 8000 |
alaw | audio/alaw | G.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.
| Voix | Style | Usages |
|---|---|---|
eve | Énergique, enjouée, accent britannique (par défaut) | Général |
ara | Chaleureuse, amicale | Général |
rex | Assurée, claire | Général |
sal | Fluide, équilibrée | Général |
leo | Autoritaire, puissante, accent britannique | Général |
carina | Douce, empathique, apaisante | Bien-être, service client |
zagan | Puissante, dramatique | Personnages, narration |
helix | Audacieuse, dynamique | Commentaire, podcast |
orion | Riche, cinématographique | Narration, livres audio |
luna | Douce, patiente | Éducation, assistant |
iris | Amicale, enjouée | Vente, service client |
altair | Élégante, raffinée | Publicité, narration |
zenith | Incisive, concentrée | Vente, publicité |
perseus | Solide, digne de confiance | Publicité, narration |
helios | Enjouée, énergique | Assistant, bien-être |
lux | Posée, sage | Bien-être, narration |
kepler | Inventive, charismatique | Publicité, podcast |
rigel | Précise, professionnelle, accent australien | Assistant, service client |
cosmo | Lumineuse, curieuse, facile à suivre | Éducation, podcast |
celeste | Bienveillante, rassurante | Service client, assistant |
ursa | Amicale, chaleureuse, fiable | Assistant, podcast |
sirius | Vive d'esprit, espiègle | Commentaire, personnages |
lumen | Chaleureuse, bien articulée | Éducation, publicité |
castor | Accessible, décontractée | Vente, service client |
naksh | Chaleureuse, sage, accent indien | Assistant, service client |
atlas | Assurée, imposante | Vente, assistant |
aurora | Sereine, stable | Service client, assistant |
liora | Calme, ancrée | Bien-ê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.
| Type | Balises |
|---|---|
| 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_KEYTous les paramètres se placent dans la chaîne de requête de l'URL de connexion :
| Paramètre | Obligatoire | Par défaut | Description |
|---|---|---|---|
model | Oui | — | grok-tts |
voice | Non | eve | Voir le tableau des voix ci-dessus |
codec | Non | mp3 | mp3, wav, pcm, mulaw (ou ulaw), alaw ; opus, aac et flac ne sont pas pris en charge |
language | Non | Détection automatique | Code de langue, par ex. zh, en, ja |
sample_rate | Non | 24000 | 8000, 16000, 22050, 24000, 44100, 48000 |
bit_rate | Non | 128000 | MP3 uniquement : 32000, 64000, 96000, 128000, 192000 |
speed | Non | 1.0 | Facteur de vitesse, de 0.7 à 1.5 |
text_normalization | Non | false | true 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 :
| Sens | Message | Description |
|---|---|---|
| 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 serveur | audio.delta | delta 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 serveur | audio.done | Tout l'audio de ce segment a été renvoyé |
| Renvoyé par le serveur | error | É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 lestext.deltaettext.donedu 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
voicene figure pas dans le tableau des voix (y compris les noms de voix OpenAI), ou sicodec,sample_rate,speedou un autre paramètre a une valeur invalide, la poignée de main renvoie directement HTTP400et 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
| Champ | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
file | file | Oui | — | Fichier audio ou vidéo : mp3, wav, ogg, opus, flac, aac, m4a, mp4, mkv ; le webm enregistré par un navigateur est aussi accepté |
model | string | Oui | — | grok-stt |
response_format | string | Non | json | json, text, verbose_json ; srt et vtt renvoient 400 |
language | string | Non | Détection automatique | Code de langue, par ex. zh, en, ja, yue (cantonais) ; le préciser rend la reconnaissance plus stable |
format | boolean | Non | false | Si true, les nombres, montants, etc. prononcés sont convertis en forme écrite ; nécessite aussi language |
keyterm | string | Non | — | 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_words | boolean | Non | false | Si 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_format | Content-Type | Contenu |
|---|---|---|
json | application/json | {"text": "..."} |
text | text/plain | Texte brut |
verbose_json | application/json | text, 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èle | Description |
|---|---|
grok-voice-latest | Pointe toujours vers la dernière version, actuellement grok-voice-3.0 |
grok-voice-3.0 | Version figée |
Connexion
wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEYLe 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" }
}
}| Champ | Description |
|---|---|
voice | Voix 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 |
instructions | Instructions 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
voicene figure pas dans le tableau des voix (y compris les noms de voix OpenAI), vous recevez un événementerrordonterror.paramvautsession.voice. Cesession.updaten'est alors pas appliqué du tout, mais la connexion reste ouverte : corrigez la valeur et renvoyez-le. session.updatedne renvoie pas la voix. La voix actuelle n'apparaît que dans lesession.createdreçu à la connexion, par exemplexai_arapar défaut.
Événements client
| Événement | Description |
|---|---|
session.update | Définit la voix, les instructions système et la détection de tour de parole |
conversation.item.create | Envoie un message texte (input_text dans content) |
response.create | Demande une réponse au modèle |
input_audio_buffer.append | Ajoute un fragment audio ; audio contient des données PCM16 encodées en Base64, idéalement environ 100 ms par envoi |
input_audio_buffer.commit | Valide 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énement | Description |
|---|---|
session.created, session.updated | Session créée, configuration appliquée |
input_audio_buffer.speech_started / speech_stopped | server_vad a détecté le début ou la fin de la parole |
conversation.item.input_audio_transcription.completed | Texte reconnu de la parole de l'utilisateur, dans transcript |
response.output_audio.delta | Fragment audio de la réponse ; delta est du PCM16 24 kHz mono encodé en Base64 |
response.output_audio_transcript.delta / .done | Transcription de la réponse ; le transcript de .done contient le texte complet |
response.done | Fin de la réponse pour ce tour |
ping | Battement de cœur, peut être ignoré |
error | Erreur ; 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.createavecinput_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êmeerrorarrive dans les 30 secondes, puis la connexion est fermée avec le code1008.
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.commitetresponse.create, ainsi que les événements serveur commesession.updated, la transcription etresponse.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=ssepeut ê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.
| Voix | Style | Genre |
|---|---|---|
Achernar | Douce | Féminine |
Achird | Amicale | Masculine |
Algenib | Rauque | Masculine |
Algieba | Fluide | Masculine |
Alnilam | Ferme | Masculine |
Aoede | Légère | Féminine |
Autonoe | Lumineuse | Féminine |
Callirrhoe | Décontractée | Féminine |
Charon | Informative | Masculine |
Despina | Fluide | Féminine |
Enceladus | Soufflée | Masculine |
Erinome | Claire | Féminine |
Fenrir | Exaltée | Masculine |
Gacrux | Mûre | Féminine |
Iapetus | Claire | Masculine |
Kore | Ferme | Féminine |
Laomedeia | Enjouée | Féminine |
Leda | Jeune | Féminine |
Orus | Ferme | Masculine |
Puck | Enjouée | Masculine |
Pulcherrima | Directe | Féminine |
Rasalgethi | Informative | Masculine |
Sadachbia | Vive | Masculine |
Sadaltager | Érudite | Masculine |
Schedar | Régulière | Masculine |
Sulafat | Chaleureuse | Féminine |
Umbriel | Décontractée | Masculine |
Vindemiatrix | Délicate | Féminine |
Zephyr | Lumineuse | Féminine |
Zubenelgenubi | Informelle | Masculine |
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èle | Remarques |
|---|---|
gemini-3-stt | Recommandé pour la transcription courante, réunions, sous-titres |
gemini-3.5-stt | Pour les audios plus difficiles ; prix unitaire plus élevé |
gemini-3.5-transcribe | Modè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."
}| Champ | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
file | file | Oui | — | Fichier audio ; les formats courants comme mp3, wav, m4a, ogg, flac sont acceptés, 25 Mo au maximum |
model | string | Oui | — | gemini-3-stt, gemini-3.5-stt ou gemini-3.5-transcribe |
response_format | string | Non | json | json ({"text": "..."}), text (texte brut), verbose_json (ajoute task, language, duration) ; srt et vtt renvoient 400 |
language | string | Non | Détection automatique | Code de langue, par ex. zh, en, yue (cantonais) |
prompt | string | Non | — | 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.jsonLa 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: renseignezlanguageavec un code de langue BCP-47, par ex.zh,en,yue; un code invalide renvoie400.promptest sans effet. Le modèle ne renvoie pas la langue détectée : lelanguagedeverbose_jsonreprend 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 messagesystemou le paramètrereasoning_effortrenvoie400. - Interface native :
generationConfig.audioTranscriptionConfigpermet 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 audioTranscriptionConfig | Type | Description |
|---|---|---|
languageCodes | string[] | Langue de l'audio, en codes BCP-47, par ex. ["zh"] ; détection automatique si absent |
customVocabulary | string[] | Noms propres à reconnaître en priorité, par ex. ["88API"] ; ces termes sont comptés dans l'usage en entrée |
diarization | boolean | Distingue les locuteurs ; chaque segment du résultat porte un speakerLabel (fonction expérimentale) |
wordTimestamp | boolean | Renvoie l'horodatage mot à mot words (fonction expérimentale) |
mode | string | SMART : 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
| Code | Cause habituelle | Que faire |
|---|---|---|
400 | input / 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 Mo | Corrigez la requête d'après le message d'erreur et les champs de cette page |
400 | Modèle vocal appelé via les interfaces Chat, Responses ou Messages | Utilisez le point de terminaison indiqué sur cette page |
400 | Texte bloqué par la politique de sécurité (PROHIBITED_CONTENT) | Modifiez le texte puis réessayez ; renvoyer le même contenu ne résoudra rien |
401 | Clé API absente ou invalide | Vérifiez le jeton Bearer et n'exposez jamais la clé dans le code côté navigateur |
429 | Limite de débit, de quota ou de capacité | Réessayez avec un backoff exponentiel et vérifiez le solde du compte |
500 / 502 / 503 | Incident temporaire côté serveur ou en amont | Ré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.