Référence API

API Synthèse vocale (TTS)

Convertissez du texte en audio vocal.Requête unique. POST /tts synthétise en une requête. Retourne un fichier WAV complet, ou définissez streaming: true pour recevoir du PCM16 en chunks.Stream dédié. POST /tts/stream est le chemin streaming uniquement.Lot. POST /tts/batch met en file jusqu'à 50 textes pour une synthèse en arrière-plan.Facturation. Par caractère.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 4
Portées: tts:use

POST/tts

Synthétiser du texte en fichier WAV, ou streamer des chunks PCM bruts avec `streaming: true`.

Synthétiser la parole

Convertit du texte en audio en une seule requête.Mode WAV. Par défaut. Le corps de la réponse est un fichier audio/wav complet.Mode streaming. Définissez streaming: true pour un audio en temps réel. La réponse est audio/pcm avec Transfer-Encoding: chunked. Le corps est du PCM16 little-endian signé à 24 kHz, mono, sans en-tête.

Corps de la requête

textstringrequis
Texte à synthétiser. 1–650 caractères par requête ; chaque caractère compte pour la facturation. Utilisez POST /tts/batch pour les scripts plus longs.
languagestringoptionnel
Supporte actuellement english (par défaut) et french.
voice_idstringoptionnel
Identifiant de voix depuis GET /voices. Quand omis, la voix par défaut du déploiement est utilisée ; les clients hérités peuvent passer default avec le même effet.
streamingbooleanoptionnel
Définir à true pour un streaming PCM16 en chunks au lieu d'un fichier WAV complet. Par défaut false.

Erreurs

404Voix non liée à un modèle TTS actif

Le voice_id est résolu mais aucun modèle TTS actif n'y est associé. Le serveur renvoie le détail "Voice not linked to an active TTS model" tel quel — basez vos correspondances de chaîne sur cette valeur.

Vérifiez l'ID avec GET /voices, ou omettez voice_id pour utiliser la voix par défaut.

413Texte trop long

Le text dépasse le plafond de sécurité de 650 caractères pour la synthèse TTS synchrone. La requête renvoie 413 avant le début de la synthèse.

Utilisez POST /tts/batch pour le texte long, ou découpez le texte aux limites des phrases pour les usages temps réel.

422Erreur de validation

text est vide ou dépasse le plafond du schéma, language n'est pas english/french, ou un mot de text est trop long pour être prononcé (un long code, jeton ou URL sans espaces). Le champ error en donne la raison.

Envoyez 1–650 caractères de texte et un code de langue supporté, et écrivez les longs codes avec des espaces entre les groupes. Pour les textes plus longs, utilisez POST /tts/batch.

503TTS non prêt

Le service de synthèse démarre ou est en cours de montée en charge.

Réessayez après un court délai. Une voix nouvellement déployée peut prendre une à deux minutes pour se préparer.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/tts \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -o speech.wav \
  -d '{
    "text": "Hello, welcome to Aethex.",
    "language": "english",
    "streaming": false
  }'

Réponse 200

json

{
  "Content-Type": "audio/wav",
  "X-Sample-Rate": "24000",
  "body": "<binary WAV: 24 kHz, 16-bit, mono PCM>"
}

POST/tts/stream

Endpoint de streaming dédié ; même format que `POST /tts` avec `streaming: true`.

Streaming de synthèse

Synthèse en streaming uniquement. Retourne du PCM16 en chunks : PCM 16 bits little-endian signé à 24 kHz mono, sans en-tête. La facturation ne se déclenche que quand le stream se termine.

Corps de la requête

textstringrequis
Texte à synthétiser. 1–650 caractères par requête de streaming.
languagestringoptionnel
Supporte actuellement english (par défaut) et french.
voice_idstringoptionnel
Identifiant de voix depuis GET /voices. Quand omis, la voix par défaut est utilisée ; les clients hérités peuvent passer default avec le même effet.

Erreurs

404Voix non liée à un modèle TTS actif

Vérifiez l'ID avec GET /voices, ou omettez voice_id.

413Texte trop long

Le text dépasse le plafond de sécurité de 650 caractères pour la synthèse TTS synchrone. La requête renvoie 413 avant le début de la synthèse.

Utilisez POST /tts/batch pour la génération longue, ou découpez le texte en segments plus courts et streamez-les séquentiellement.

422Erreur de validation

Utilisez 1–650 caractères et un code de langue supporté, et écrivez les longs codes avec des espaces entre les groupes. Pour les textes plus longs, utilisez POST /tts/batch.

503TTS non prêt

Le service de synthèse démarre ou est en cours de montée en charge.

Réessayez après un court délai.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/tts/stream \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  --output - \
  -d '{
    "text": "Hello, welcome to Aethex.",
    "language": "english"
  }' | aplay -f S16_LE -r 24000 -c 1

Réponse 200

json

{
  "Content-Type": "audio/pcm",
  "X-Sample-Rate": "24000",
  "X-Encoding": "pcm16",
  "body": "<PCM16 stream: contiguous little-endian 16-bit samples, 24 kHz mono>"
}

POST/tts/batch

Soumettre jusqu'à 50 textes pour une synthèse en arrière-plan. Récupérez des URLs de téléchargement signées.

Synthèse par lot

Met en file une liste de textes pour une synthèse asynchrone. Retourne immédiatement un batch_id avec status: "queued". Interrogez GET /tts/batch/{batch_id} ou passez un webhook_url pour être notifié. Les éléments longs sont découpés en interne en chunks sûrs pour l'inférence, puis retournés comme un WAV par élément d'origine. La facturation ne s'applique qu'aux éléments synthétisés avec succès.Champs webhook. webhook_status vaut null quand aucun webhook_url n'a été fourni. Lorsqu'un webhook est enregistré, il passe par pending → delivered, failed ou unsafe (l'URL a résolu vers un hôte privé ou bloqué au moment de la livraison). Les champs associés webhook_last_error, webhook_last_attempt_at et webhook_delivered_at ne sont renseignés que lorsqu'un webhook est en jeu.

Corps de la requête

itemsobject[]requis
Tableau d'éléments à synthétiser, 1–50 entrées. Chaque élément est { text: string, language?: "english" | "french" }. Chaque text doit contenir 1–3000 caractères ; le worker découpe les éléments longs en requêtes backend de 650 caractères ou moins.
languagestringoptionnel
Langue par défaut pour les éléments qui ne définissent pas la leur. Actuellement english (par défaut) ou french.
voice_idstringoptionnel
Identifiant de voix depuis GET /voices, appliqué à chaque élément du lot. Omettez ce champ pour utiliser la voix par défaut ; les clients hérités peuvent passer default avec le même effet. Soumettez des lots séparés pour différentes voix.
webhook_urlstringoptionnel
URL HTTPS invoquée quand le lot atteint un état terminal. La charge utile est signée avec votre secret webhook de compte.

Erreurs

404Voix non liée à un modèle TTS actif

Le voice_id est résolu mais aucun modèle TTS actif n'y est associé. Vérifié à la soumission, donc une voix défectueuse échoue rapidement et non au fond du worker. Le serveur renvoie le détail "Voice not linked to an active TTS model" tel quel — basez vos correspondances de chaîne sur cette valeur.

Vérifiez l'ID avec GET /voices, ou omettez voice_id.

422Erreur de validation

items est vide ou dépasse 50 entrées ; le text d'un élément est vide ou dépasse le plafond du schéma ; ou language n'est pas english/french.

Envoyez 1–50 éléments, chacun avec 1–3000 caractères de texte et un code de langue supporté.

503Service temporairement indisponible

Nous sommes actuellement à pleine capacité.

Réessayez la requête. Si cela persiste, contactez [email protected].

Requête

json

curl -X POST https://api.aethexai.com/api/v1/tts/batch \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "text": "Hello, welcome to Aethex." },
      { "text": "Bonjour et bienvenue.", "language": "french" }
    ],
    "language": "english"
  }'

201 Réponse

json

{
  "batch_id": "0f8b2c40-2c1f-4e1f-9e3d-1234567890ab",
  "status": "queued",
  "total": 2,
  "completed": 0,
  "failed": 0,
  "results": [],
  "webhook_status": null,
  "webhook_last_error": null,
  "webhook_last_attempt_at": null,
  "webhook_delivered_at": null,
  "created_at": "2026-05-08T10:00:00+00:00",
  "updated_at": "2026-05-08T10:00:00+00:00"
}

GET/tts/batch/:batch_id

Interroger un lot ; retourne des URLs de téléchargement signées pour chaque élément terminé.

Obtenir le statut du lot

Retourne le statut actuel et les résultats par élément pour un lot. status passe par queued → running → completed (ou failed). Le tableau results obtient une entrée par élément une fois traité ; audio_url est une URL signée qui expire (par défaut 15 minutes).

Chemin & Requête

batch_idstringrequis
L'UUID retourné par POST /tts/batch.

Erreurs

404Lot introuvable

Aucun lot avec cet ID n'existe sur votre compte.

Vérifiez le batch_id retourné par POST /tts/batch.

422batch_id invalide

batch_id n'est pas un UUID valide.

Passez l'UUID exact retourné par POST /tts/batch.

Réponse

json

{
  "batch_id": "0f8b2c40-2c1f-4e1f-9e3d-1234567890ab",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "status": "completed",
      "audio_url": "https://storage.aethexai.com/tts-batch/.../item0.wav?signature=...",
      "error": null,
      "duration_seconds": 1.5
    },
    {
      "index": 1,
      "status": "completed",
      "audio_url": "https://storage.aethexai.com/tts-batch/.../item1.wav?signature=...",
      "error": null,
      "duration_seconds": 1.2
    }
  ],
  "webhook_status": "delivered",
  "webhook_last_error": null,
  "webhook_last_attempt_at": "2026-05-08T10:00:31+00:00",
  "webhook_delivered_at": "2026-05-08T10:00:31+00:00",
  "created_at": "2026-05-08T10:00:00+00:00",
  "updated_at": "2026-05-08T10:00:30+00:00"
}