Migrer depuis Cartesia

Si votre application dispose déjà d’un adaptateur par fournisseur, conservez la forme de cet adaptateur et faites pointer son implémentation vers les endpoints Gradium, l’authentification x-api-key, les valeurs voice_id de Gradium et les messages WebSocket de Gradium. Pour les applications temps réel, Gradium vous donne également accès à la VAD sémantique STT et aux réglages de délai adaptatif dans la même API.

Remplacement des endpoints

Flux	Intégration existante	Gradium
TTS en un seul appel	`POST https://api.cartesia.ai/tts/bytes`	`POST https://api.gradium.ai/api/post/speech/tts`
TTS en streaming	`wss://api.cartesia.ai/tts/websocket`	`wss://api.gradium.ai/api/speech/tts`
STT en streaming	`wss://api.cartesia.ai/stt/websocket`	`wss://api.gradium.ai/api/speech/asr`

Correspondance de l’authentification

Champ d’authentification/de version existant	Gradium
`Authorization: Bearer $CARTESIA_API_KEY`	`x-api-key: $GRADIUM_API_KEY`
`X-API-Key`	`x-api-key`
En-tête de version d’API du fournisseur	Non requis par Gradium
`access_token` pour les clients navigateur	`?token=...` éphémère de Gradium ; voir WebSockets dans le navigateur.

TTS POST avec Gradium

L’endpoint POST de Gradium renvoie directement les octets audio lorsque only_audio vaut true : le reste de votre code qui « écrit cette réponse dans un fichier ou un lecteur » peut donc rester inchangé.

Gradium

curl -L -X POST https://api.gradium.ai/api/post/speech/tts \
  -H "x-api-key: $GRADIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Gradium.",
    "voice_id": "YTpq7expH9539ERJ",
    "output_format": "wav",
    "only_audio": true
  }' \
  > output.wav

Correspondance des champs TTS

Champ existant	Champ Gradium
`transcript`	`text`
`voice.id`	`voice_id`
`model_id`	`model_name`
`output_format.container` / encodage / fréquence d’échantillonnage	Chaîne `output_format`
`language` ou choix d’une voix localisée	Langue de la voix, plus `json_config.language` / règles de réécriture en option
Dictionnaire de prononciation	`pronunciation_id`

Gradium utilise une chaîne output_format compacte : wav, pcm, opus, ulaw_8000, alaw_8000, ou des fréquences PCM explicites comme pcm_16000.

Migration du TTS WebSocket

Avec Gradium, vous envoyez d’abord setup, puis un ou plusieurs messages text, puis end_of_stream. Utilisez client_req_id lorsque vous devez corréler plusieurs requêtes logiques simultanées sur un même socket.

Gradium messages

{"type":"setup","voice_id":"YTpq7expH9539ERJ","model_name":"default","output_format":"pcm","client_req_id":"ctx-1","close_ws_on_eos":false}
{"type":"text","text":"Hello from Gradium.","client_req_id":"ctx-1"}
{"type":"end_of_stream","client_req_id":"ctx-1"}

Pour un seul énoncé en streaming, client_req_id et close_ws_on_eos: false sont facultatifs. Utilisez-les lorsque vous voulez plusieurs énoncés sur un même socket.

Étape de streaming existante	Étape de streaming Gradium
Se connecter au WebSocket du fournisseur	Se connecter à `wss://api.gradium.ai/api/speech/tts`
Démarrer une requête logique	Envoyer le `setup` Gradium, éventuellement avec `client_req_id`
Poursuivre avec plus de texte	Envoyer d’autres messages `text` pour la même requête
Terminer la requête	Envoyer `end_of_stream` pour ce `client_req_id`
Recevoir des réponses `chunk` / audio	Recevoir des messages `audio`
Recevoir des horodatages	Recevoir les messages d’horodatage `text` du TTS, à la granularité du segment
Annuler un contexte	Arrêter la lecture et fermer le socket, ou isoler les requêtes avec `client_req_id`

Correspondance des fonctionnalités TTS

Fonctionnalité existante	Équivalent Gradium	Remarque de migration
`context_id`	`client_req_id`	À utiliser pour la corrélation et le multiplexage, pas pour conserver la prosodie entre des requêtes sans lien.
`continue: true/false`	Plusieurs messages `text` puis `end_of_stream`	Envoyez des fragments composés de mots ou de phrases complets ; utilisez `<flush>` aux frontières naturelles.
Contextes simultanés	Multiplexage	Définissez `close_ws_on_eos: false` et routez par `client_req_id`.
`transcript`	`text`	Même concept, nom de champ différent.
`output_format` structuré	Chaîne `output_format`	Choisissez le format Gradium le plus proche de votre lecteur en aval.
Horodatages par mot/phonème	Horodatages par segment	Gradium documente des horodatages de texte au niveau du segment.
Jetons d’accès pour le navigateur	`GET /api/api-keys/token` et `?token=...` de Gradium	Voir WebSockets dans le navigateur.

STT en streaming avec Gradium

Le STT de Gradium utilise des messages JSON pour l’audio en WebSocket direct, avec des payloads en base64. Il renvoie des messages text, end_text, step, flushed et end_of_stream.

Gradium STT

{"type":"setup","model_name":"default","input_format":"pcm","json_config":{"language":"en"}}
{"type":"audio","audio":"base64_encoded_audio"}
{"type":"flush","flush_id":1}
{"type":"end_of_stream"}

Concept STT existant	Équivalent STT Gradium
Trames audio binaires	Messages JSON `audio` en base64
Paramètres de connexion `encoding` et `sample_rate`	`input_format`, par exemple `pcm_16000`, `pcm_24000`, `ulaw_8000`
`transcript.is_final`	`text` plus finalisation du segment par `end_text`
`finalize`	`flush` avec un `flush_id`
`flush_done`	`flushed` avec le même `flush_id`
`done`	`end_of_stream`
Horodatages par mot	Horodatages par segment dans la documentation publique de Gradium
VAD externe / événements de tour de parole	Messages `step` de VAD sémantique

Checklist de l’adaptateur

Remplacez les URL du fournisseur par les endpoints Gradium correspondants.
Supprimez les en-têtes de version d’API du fournisseur ; Gradium n’en a pas besoin.
Passez l’authentification à x-api-key côté serveur, ou à un ?token=... temporaire pour les WebSockets dans le navigateur.
Renommez transcript en text.
Aplatissez voice.id en voice_id.
Convertissez l’output_format structuré en chaîne de format Gradium.
Pour un routage par contexte, associez l’identifiant de requête à client_req_id lorsque vous avez besoin de corréler les réponses.
Pour les clients STT en WebSocket direct, encodez l’audio en base64 dans les messages JSON.

Étapes suivantes

Guide TTS WebSocket de Gradium

Messages de configuration du streaming, messages audio, flush et horodatages.

Multiplexage

Remplacez le routage par contexte par client_req_id.

WebSockets dans le navigateur

Utilisez des jetons éphémères sans exposer vos clés API.

Audio pour la téléphonie

Correspondance des formats PCM à basse fréquence d’échantillonnage, mu-law et A-law.

Premiers pas

Synthèse vocale (TTS)

Transcription (STT)

Speech-to-Speech

Commun

Recettes temps réel

Migrations

Voix

Auto-hébergé

Ressources

Migrer depuis Cartesia

Remplacement des endpoints

Correspondance de l’authentification

TTS POST avec Gradium

Correspondance des champs TTS

Migration du TTS WebSocket

Correspondance des fonctionnalités TTS

STT en streaming avec Gradium

Checklist de l’adaptateur

Étapes suivantes

Guide TTS WebSocket de Gradium

Multiplexage

WebSockets dans le navigateur

Audio pour la téléphonie

​Remplacement des endpoints

​Correspondance de l’authentification

​TTS POST avec Gradium

​Correspondance des champs TTS

​Migration du TTS WebSocket

​Correspondance des fonctionnalités TTS

​STT en streaming avec Gradium

​Checklist de l’adaptateur

​Étapes suivantes

Guide TTS WebSocket de Gradium

Multiplexage

WebSockets dans le navigateur

Audio pour la téléphonie

Remplacement des endpoints

Correspondance de l’authentification

TTS POST avec Gradium

Correspondance des champs TTS

Migration du TTS WebSocket

Correspondance des fonctionnalités TTS

STT en streaming avec Gradium

Checklist de l’adaptateur

Étapes suivantes