Narrer des articles avec la synthèse vocale

Faire un appel à /audio/speech est facile. C’est en narrant un vrai article que les problèmes intéressants apparaissent : le point de terminaison accepte au plus 4096 caractères par requête, chaque voix appartient à un modèle spécifique, les formats audio diffèrent d’un modèle à l’autre, et un texte écrit pour être lu ne ressemble en rien à un texte écrit pour être entendu. Dans ce tutoriel, nous traitons les quatre. Le résultat est un script qui transforme une URL en un seul fichier audio :

python article_to_audio.py https://docs.venice.ai/overview/privacy

Nous allons :

Choisir un modèle et une voix adaptés à la narration longue
Faire une seule requête de synthèse et enregistrer l’audio
Découper un long article en morceaux respectant la limite de caractères
Assembler les morceaux synthétisés en un seul fichier sans coutures audibles
Réécrire l’article en quelque chose qui vaut la peine d’être écouté
Combiner les pièces, puis examiner le streaming pour un usage interactif

Configuration

Vous avez besoin de Python 3.9 ou plus récent, du paquet requests et d’une clé API Venice.

pip install requests
export VENICE_API_KEY="your-api-key-here"

1. Choisir un modèle et une voix

Les voix appartiennent aux modèles. Envoyer une voix d’une famille à un modèle d’une autre famille est la première erreur la plus courante, alors commencez par lister ce que chaque modèle accepte réellement :

curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY" |
  jq -r '.data[] | "\(.id)  formats=\(.model_spec.supported_formats)  voices=\(.model_spec.voices | length)"'

tts-kokoro  formats=["mp3","opus","aac","flac","wav","pcm"]  voices=54
tts-qwen3-1-7b  formats=["mp3"]  voices=9
tts-xai-v1  formats=["mp3","wav","pcm"]  voices=26
tts-inworld-1-5-max  formats=["wav"]  voices=14
tts-chatterbox-hd  formats=["wav"]  voices=9
tts-orpheus  formats=["wav"]  voices=8
tts-elevenlabs-turbo-v2-5  formats=["mp3"]  voices=21
tts-minimax-speech-02-hd  formats=["mp3","pcm","flac"]  voices=15
tts-gemini-3-1-flash  formats=["mp3","opus","wav"]  voices=30
tts-gradium-v1  formats=["wav","pcm","opus"]  voices=12

model_spec.voices est la liste de voix qui fait autorité pour un modèle, et supported_formats vous indique les valeurs de response_format qu’il accepte. Retirez le | length de la requête pour afficher les noms de voix eux-mêmes. Nous utiliserons tts-xai-v1 avec la voix eve. Elle prend en charge pcm, ce qui rend l’assemblage des morceaux simple à la section 4.

La vitesse de synthèse varie bien plus entre modèles TTS que la qualité de sortie, et l’écart est suffisamment important pour modifier votre architecture. Chronométrez une requête réaliste sur deux ou trois candidats avant de vous engager. Un morceau qu’un modèle renvoie en quelques secondes peut prendre à un autre plusieurs minutes.

2. Faire une seule requête

Le corps de la réponse est de l’audio brut plutôt que du JSON, donc écrivez les octets directement dans un fichier.

import os
from pathlib import Path

import requests

response = requests.post(
    "https://api.venice.ai/api/v1/audio/speech",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "tts-xai-v1",
        "voice": "eve",
        "input": "Hello from Venice.",
        "response_format": "mp3",
    },
    timeout=300,
)

response.raise_for_status()
Path("hello.mp3").write_bytes(response.content)

import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.venice.ai/api/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "tts-xai-v1",
    voice: "eve",
    input: "Hello from Venice.",
    response_format: "mp3",
  }),
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

await writeFile("hello.mp3", Buffer.from(await response.arrayBuffer()));

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-xai-v1",
    "voice": "eve",
    "input": "Hello from Venice.",
    "response_format": "mp3"
  }' \
  --output hello.mp3

Les combinaisons incompatibles sont rejetées avant qu’aucun audio ne soit généré, et l’erreur vous indique ce qui aurait fonctionné à la place :

{"error":"Voice \"eve\" is not supported by model \"tts-kokoro\". Try using a supported voice: af_alloy, af_aoede, af_bella, af_heart, af_jadzia, ...."}

{"error":"response_format \"wav\" is not supported by model \"tts-elevenlabs-turbo-v2-5\". Supported formats: mp3."}

3. Découper le texte à la limite des 4096 caractères

Le champ input accepte au plus 4096 caractères. Un texte plus long est rejeté d’emblée plutôt que tronqué silencieusement :

{"error":"Invalid request parameters","issues":[{"code":"too_big","maximum":4096,"path":["input"]}]}

Nous découpons donc l’article d’abord. Découper aux frontières de phrases est important, car un morceau qui se termine au milieu d’une phrase produit une hésitation audible à la jointure. Créez narrate.py :

from __future__ import annotations

import os
import re
import sys
import wave
from concurrent.futures import ThreadPoolExecutor

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

MODEL = "tts-xai-v1"
VOICE = "eve"
SAMPLE_RATE = 24000  # tts-xai-v1 returns 24 kHz mono signed 16-bit PCM.

SENTENCE_END = re.compile(r"(?<=[.!?])\s+")


def split_into_chunks(text: str, max_chars: int = 1500) -> list[str]:
    """Split text on sentence boundaries into chunks under the 4096-character cap."""
    chunks: list[str] = []
    current = ""

    for sentence in SENTENCE_END.split(text.strip()):
        if not sentence:
            continue
        if len(sentence) > max_chars:
            raise ValueError(f"Sentence longer than {max_chars} characters: {sentence[:80]}...")
        if len(current) + len(sentence) + 1 > max_chars:
            chunks.append(current)
            current = sentence
        else:
            current = f"{current} {sentence}" if current else sentence

    if current:
        chunks.append(current)
    return chunks

Sur un script de 5362 caractères, cela produit quatre morceaux, chacun se terminant sur une phrase :

chunks = split_into_chunks(script)
print(f"len(chunks) = {len(chunks)}")
for index, chunk in enumerate(chunks):
    print(f"chunk {index}: {len(chunk)} chars")

len(chunks) = 4
chunk 0: 1428 chars
chunk 1: 1410 chars
chunk 2: 1489 chars
chunk 3: 1015 chars

La valeur par défaut de max_chars est 1500 plutôt que quelque chose proche du plafond de 4096, et c’est délibéré. Le temps de synthèse croît avec la longueur d’entrée, donc les morceaux plus petits reviennent plus tôt et, comme ils s’exécutent en parallèle, terminent le travail global plus vite. Ils rendent aussi les nouvelles tentatives peu coûteuses lorsqu’une requête échoue.

4. Assembler les morceaux en un seul fichier

Concaténer de l’audio encodé comme le MP3 n’est pas fiable, car chaque morceau porte ses propres en-têtes de trame. Demander pcm évite complètement le problème. PCM est constitué d’échantillons bruts sans conteneur, donc l’assemblage se résume à ajouter des octets bout à bout, et le module wave de la bibliothèque standard Python écrit l’en-tête pour nous.

def synthesize(text: str, speed: float = 1.0) -> bytes:
    """Return raw PCM audio for one chunk."""
    response = requests.post(
        f"{BASE_URL}/audio/speech",
        headers=HEADERS,
        json={
            "model": MODEL,
            "voice": VOICE,
            "input": text,
            "response_format": "pcm",
            "speed": speed,
        },
        timeout=300,
    )
    if response.status_code != 200:
        raise RuntimeError(f"TTS failed ({response.status_code}): {response.text}")
    return response.content


def narrate(text: str, out_path: str) -> str:
    chunks = split_into_chunks(text)
    print(f"Synthesizing {len(chunks)} chunks", file=sys.stderr)

    with ThreadPoolExecutor(max_workers=4) as pool:
        audio = list(pool.map(synthesize, chunks))

    with wave.open(out_path, "wb") as output:
        output.setnchannels(1)
        output.setsampwidth(2)
        output.setframerate(SAMPLE_RATE)
        for part in audio:
            output.writeframes(part)

    seconds = sum(len(part) for part in audio) / 2 / SAMPLE_RATE
    print(f"Wrote {out_path} ({seconds:.1f}s of audio)", file=sys.stderr)
    return out_path

Un seul morceau revient rapidement par rapport à la quantité d’audio qu’il contient :

pcm = synthesize(chunks[0])
print(f"bytes   = {len(pcm)}")
print(f"audio   = {len(pcm) / 2 / SAMPLE_RATE:.1f}s")

bytes   = 4269376
audio   = 88.9s

Cette requête a pris environ 13 secondes pour produire 89 secondes de parole. Exécuter les quatre morceaux en parallèle est ce qui maintient le total raisonnable : la narration complète ci-dessous a pris 15 secondes de temps d’horloge. ThreadPoolExecutor.map renvoie les résultats dans l’ordre où les entrées ont été soumises, de sorte que les morceaux arrivent dans l’ordre de lecture même s’ils ont été synthétisés en même temps.

Le PCM brut ne transporte aucune fréquence d’échantillonnage, donc vous devez fournir la bonne lors de l’écriture de l’en-tête WAV, et elle est spécifique à chaque modèle. tts-xai-v1 renvoie 24 kHz tandis que tts-gradium-v1 renvoie 48 kHz. Trompez-vous et la narration est jouée à la mauvaise vitesse et à la mauvaise hauteur.

Pour trouver la fréquence pour n’importe quel modèle, demandez un court clip en wav et lisez l’en-tête qu’il renvoie :

import wave

response = requests.post(
    f"{BASE_URL}/audio/speech",
    headers=HEADERS,
    json={"model": MODEL, "voice": VOICE, "input": "Probe.", "response_format": "wav"},
    timeout=300,
)
response.raise_for_status()
with open("probe.wav", "wb") as handle:
    handle.write(response.content)

with wave.open("probe.wav") as probe:
    print(probe.getframerate(), probe.getnchannels(), probe.getsampwidth())

24000 1 2

5. Préparer un texte qui sonne bien

Le Markdown extrait, lu à voix haute tel quel, est proche de l’inécoutable. Les URL en sont l’exemple le plus clair. Un modèle vocal les épelle caractère par caractère, si bien que https://docs.venice.ai/llms.txt sort ainsi :

h t t p s deux points barre oblique barre oblique docs point venice point a i l l m s point t x t

Les titres, les puces, les tableaux et les blocs de code causent des versions plus discrètes du même problème. Plutôt que de combattre le Markdown avec des expressions régulières, nous pouvons demander à un modèle de chat de réécrire l’article comme quelque chose destiné à être parlé. Créez article_to_audio.py :

from __future__ import annotations

import os
import re
import sys

import requests

from narrate import narrate

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

URL_PATTERN = re.compile(r"https?://\S+|www\.\S+")


def scrape(url: str) -> str:
    response = requests.post(
        f"{BASE_URL}/augment/scrape", headers=HEADERS, json={"url": url}, timeout=120
    )
    response.raise_for_status()
    return response.json()["content"]


def write_script(markdown: str, minutes: int = 6) -> str:
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=HEADERS,
        json={
            "model": "zai-org-glm-5-1",
            "messages": [
                {
                    "role": "system",
                    "content": (
                        "You rewrite articles as scripts to be read aloud. Output plain prose only: "
                        "no Markdown, no headings, no bullet points, no URLs, no code, no emoji. "
                        "Spell out abbreviations and numbers the way a narrator would say them. "
                        "Use short sentences with clear punctuation so speech synthesis paces well."
                    ),
                },
                {
                    "role": "user",
                    "content": f"Rewrite this article as a {minutes}-minute spoken summary.\n\n{markdown[:20000]}",
                },
            ],
            "temperature": 0.4,
        },
        timeout=300,
    )
    response.raise_for_status()
    script = response.json()["choices"][0]["message"]["content"]
    return URL_PATTERN.sub("", script).strip()

La substitution URL_PATTERN reste en place comme filet de sécurité pour le lien occasionnel que le modèle laisserait derrière lui.

6. Assembler le tout

Le point d’entrée extrait la page, rédige le script, l’enregistre et le narre :

if __name__ == "__main__":
    url = sys.argv[1]

    print("Scraping", url, file=sys.stderr)
    markdown = scrape(url)

    print(f"Writing script from {len(markdown)} characters of Markdown", file=sys.stderr)
    script = write_script(markdown)

    with open("script.txt", "w") as handle:
        handle.write(script)

    narrate(script, "article.wav")

Enregistrer script.txt à côté de l’audio vaut bien deux lignes. Quand une narration sonne mal, le script en montre presque toujours la raison, et vous pouvez la corriger sans payer une nouvelle synthèse.

python article_to_audio.py https://docs.venice.ai/overview/privacy

Scraping https://docs.venice.ai/overview/privacy
Writing script from 7582 characters of Markdown
Synthesizing 4 chunks
Wrote article.wav (355.0s of audio)

Juste moins de six minutes de narration, produites en environ quinze secondes. Le script s’ouvre désormais sur de la prose plutôt que du mobilier de navigation :

Venice est bâti sur un principe simple mais puissant. La confidentialité de l’utilisateur passe avant tout. Toute l’architecture de la plateforme découle de cet engagement philosophique.

Pour vérifier une narration sans l’écouter entièrement, renvoyez l’audio dans /audio/transcriptions et comparez la transcription à script.txt. Transcrire les vingt dernières secondes est un moyen rapide de confirmer que les morceaux ont été assemblés dans le bon ordre, et cela repère en quelques secondes les morceaux perdus et les URL épelées.

Streaming pour un usage interactif

La narration par lots optimise le temps total. Une interface vocale a la priorité inverse, qui est d’obtenir le premier audio aussi vite que possible. Régler streaming: true renvoie le corps phrase par phrase au fur et à mesure de la génération, si bien que la lecture peut démarrer en environ une seconde au lieu d’attendre le clip complet.

import time

import requests

start = time.time()
first_byte = None

with requests.post(
    "https://api.venice.ai/api/v1/audio/speech",
    headers=HEADERS,
    json={
        "model": "tts-xai-v1",
        "voice": "eve",
        "input": "Streaming returns audio while the rest is still being generated.",
        "response_format": "mp3",
        "streaming": True,
    },
    stream=True,
    timeout=300,
) as response:
    response.raise_for_status()
    with open("streamed.mp3", "wb") as audio:
        for chunk in response.iter_content(chunk_size=4096):
            if first_byte is None:
                first_byte = time.time() - start
            audio.write(chunk)

print(f"first byte: {first_byte:.2f}s   complete: {time.time() - start:.2f}s")

first byte: 0.85s   complete: 1.43s

Préférez pcm à mp3 lorsque vous alimentez directement l’API Web Audio d’un navigateur ou un périphérique audio, puisqu’il n’a besoin d’aucune étape de décodage.

Options de requête à connaître

Paramètre	Notes
`speed`	Accepte de `0.25` à `4.0`, par défaut `1.0`. Restez à peu près entre `0.8` et `1.3` pour la narration. Au-delà, le rendu cesse de sonner naturel.
`language`	Indication facultative dont la forme acceptée dépend du modèle. xAI et ElevenLabs prennent des codes ISO 639-1 comme `en`, tandis que Qwen 3 et MiniMax prennent des noms complets comme `English`. Les valeurs non prises en charge sont ignorées.
`prompt`	Indice de style et d’émotion, jusqu’à 500 caractères, actuellement pris en compte uniquement par les modèles Qwen 3. Pour les autres familles, c’est le choix de la voix qui porte le ton.
`temperature`	Plage `0` à `2`, prise en charge par Qwen 3, Orpheus et Chatterbox HD. Augmentez-la pour plus de variation entre les prises.

Erreurs

Statut	Cause	Solution
`400`	`input` de plus de 4096 caractères	Découpez le texte comme à la section 3
`400`	Voix non valide pour le modèle	Utilisez une voix issue de `model_spec.voices` du modèle
`400`	Format non pris en charge par le modèle	Vérifiez `model_spec.supported_formats`
`401`	Clé manquante ou invalide	Vérifiez l’en-tête `Authorization: Bearer`
`402`	Solde insuffisant	Rechargez le compte
`429`	Limite de débit atteinte	Baissez `max_workers` et réessayez avec un backoff
`500` ou `503`	Capacité ou échec d’inférence	Réessayez le morceau concerné avec du jitter

Comme les morceaux sont indépendants, un échec ne coûte jamais que l’un d’eux, et relancer synthesize pour ce morceau est toujours sûr.

Étapes suivantes

Quelques extensions naturelles à partir d’ici :

Mettez en cache l’audio par un hash du texte, de la voix et du modèle afin que les paragraphes inchangés ne soient jamais re-synthétisés.
Substituez une voix clonée avec le Clonage vocal pour que la narration utilise la vôtre.
Générez le texte source au lieu de l’extraire, en utilisant Réponses sourcées avec la recherche web.
Ajoutez un audio d’introduction ou de fond avec Musique et effets sonores.

Synthèse vocale

Référence du point de terminaison speech et de ses paramètres.

Clonage vocal

Narrer avec une voix personnalisée plutôt qu’un préréglage.

Réponses sourcées avec la recherche web

Générez le texte que cet outil narre.

Reconnaissance vocale

Transcrivez de l’audio pour vérifier une narration de bout en bout.

Documentation

Démarrage

Texte et chat

Image

Vidéo

Audio

Recherche et RAG

Agents et intégrations

Outils de code

Outils pour agents

SDK et frameworks

Configuration

1. Choisir un modèle et une voix

2. Faire une seule requête

3. Découper le texte à la limite des 4096 caractères

4. Assembler les morceaux en un seul fichier

5. Préparer un texte qui sonne bien

6. Assembler le tout

Streaming pour un usage interactif

Options de requête à connaître

Erreurs

Étapes suivantes

Synthèse vocale

Clonage vocal

Réponses sourcées avec la recherche web

Reconnaissance vocale

​Configuration

​1. Choisir un modèle et une voix

​2. Faire une seule requête

​3. Découper le texte à la limite des 4096 caractères

​4. Assembler les morceaux en un seul fichier

​5. Préparer un texte qui sonne bien

​6. Assembler le tout

​Streaming pour un usage interactif

​Options de requête à connaître

​Erreurs

​Étapes suivantes

Synthèse vocale

Clonage vocal

Réponses sourcées avec la recherche web

Reconnaissance vocale

Configuration

1. Choisir un modèle et une voix

2. Faire une seule requête

3. Découper le texte à la limite des 4096 caractères

4. Assembler les morceaux en un seul fichier

5. Préparer un texte qui sonne bien

6. Assembler le tout

Streaming pour un usage interactif

Options de requête à connaître

Erreurs

Étapes suivantes