> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradium.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Synthèse vocale (REST)

> Synthèse en un appel d'un bloc de texte complet via HTTP POST

Utilisez l'endpoint REST lorsque vous disposez d'un bloc de texte
complet et voulez une seule requête HTTP, sans WebSocket à gérer. La
réponse peut être soit les octets audio bruts (pour écrire directement
un fichier), soit un flux JSON qui reprend le protocole WebSocket.

<Card title="Besoin de streaming ?" icon="waveform-lines" href="/fr/guides/text-to-speech">
  Pour une synthèse à faible latence de textes longs ou générés, la
  synthèse vocale en streaming via le SDK vous fournit les fragments
  audio au fur et à mesure de leur production.
</Card>

## Démarrage rapide

`only_audio=true` renvoie directement les octets audio bruts : c'est le
plus simple pour un usage « texte en entrée, fichier en sortie ».

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X POST https://api.gradium.ai/api/post/speech/tts \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"text": "Hello, world!", "voice_id": "YTpq7expH9539ERJ", "output_format": "wav", "only_audio": true}' \
    > output.wav
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.gradium.ai/api/post/speech/tts",
      json={
          "text": "Hello, world!",
          "voice_id": "YTpq7expH9539ERJ",
          "output_format": "wav",
          "only_audio": True,
      },
      headers={"x-api-key": "your_api_key"},
  )
  resp.raise_for_status()
  with open("output.wav", "wb") as f:
      f.write(resp.content)
  ```
</CodeGroup>

Pour choisir un modèle, ajoutez `model_name` au premier niveau du corps
JSON. Si vous l'omettez, `default` est utilisé, ce qui sélectionne le
dernier modèle TTS de production. Voir
[Choix du modèle](/fr/guides/text-to-speech#choix-du-modèle).

## Modes de réponse

Le champ `only_audio` du corps de la requête détermine l'une des deux
formes de réponse :

* **`only_audio: true`** : le corps de la réponse est l'audio brut dans
  le `output_format` demandé (WAV, PCM, Opus, …). Enregistrez-le
  directement dans un fichier ou envoyez-le vers un lecteur. Le
  `Content-Type` reflète le format (`audio/wav`, `audio/ogg`,
  `audio/pcm`).
* **`only_audio: false`** (ou omis) : la réponse est un flux JSON qui
  utilise le même format de message que l'endpoint WebSocket, avec
  notamment `audio` (base64), `text` (avec horodatages) et `error`.
  Lisez le corps ligne par ligne jusqu'à sa fermeture.

### Lire la réponse JSON en streaming

Passez `only_audio: false` et lisez le corps au fur et à mesure de son
arrivée. Avec cURL, l'option `-N` (`--no-buffer`) affiche chaque ligne
dès que le serveur l'envoie.

<CodeGroup>
  ```bash cURL theme={null}
  curl -N -L -X POST https://api.gradium.ai/api/post/speech/tts \
    -H "x-api-key: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"text": "Hello, world!", "voice_id": "YTpq7expH9539ERJ", "output_format": "wav", "only_audio": false}'
  ```

  ```python Python theme={null}
  import base64
  import json

  import requests

  audio_chunks = []
  text_segments = []

  with requests.post(
      "https://api.gradium.ai/api/post/speech/tts",
      json={
          "text": "Hello, world!",
          "voice_id": "YTpq7expH9539ERJ",
          "output_format": "wav",
          "only_audio": False,
      },
      headers={"x-api-key": "your_api_key"},
      stream=True,
  ) as resp:
      resp.raise_for_status()
      for line in resp.iter_lines(decode_unicode=True):
          if not line:
              continue
          msg = json.loads(line)
          if msg["type"] == "audio":
              audio_chunks.append(base64.b64decode(msg["audio"]))
          elif msg["type"] == "text":
              text_segments.append(msg)

  with open("output.wav", "wb") as f:
      f.write(b"".join(audio_chunks))
  ```
</CodeGroup>

Pour le schéma complet de la requête, les formats de sortie pris en
charge et la forme des erreurs, consultez la
[référence de l'endpoint TTS POST](/fr/api-reference/endpoint/tts-post).

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Référence API TTS POST" icon="code" href="/fr/api-reference/endpoint/tts-post">
    Schéma complet du corps de requête, formats de sortie, contrats
    d'erreur.
  </Card>

  <Card title="Streaming avec le SDK" icon="waveform-lines" href="/fr/guides/text-to-speech">
    Sortie audio par fragments, voix personnalisées, flush, horodatages.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.