Narrating Articles with Text-to-Speech

Making one /audio/speech call is easy. Narrating a real article is where the interesting problems show up: the endpoint accepts at most 4096 characters per request, every voice belongs to a specific model, audio formats differ from model to model, and text written to be read looks nothing like text written to be heard. In this tutorial we work through all four. The result is a script that turns a URL into a single audio file:

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

Run this tutorial in Google Colab

Every step below as an executable notebook, with the narration playing inline. Nothing to install.

We will:

Pick a model and a voice that suit long form narration
Make a single speech request and save the audio
Split a long article into chunks that fit the character limit
Join the synthesized chunks into one file with no audible seams
Rewrite the article into something worth listening to
Combine the pieces, then look at streaming for interactive use

Setup

You need Python 3.9 or newer, the requests package, and a Venice API key.

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

1. Choose a model and a voice

Voices belong to models. Sending a voice from one family to a model from another is the most common first mistake, so start by listing what each model actually accepts:

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-0-6b  formats=["mp3"]  voices=9
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 is the authoritative voice list for a model, and supported_formats tells you which response_format values it accepts. Drop the | length from the query to print the voice names themselves. We will use tts-xai-v1 with the voice eve. It supports pcm, which is what makes joining chunks straightforward in section 4.

Synthesis speed varies far more between TTS models than output quality does, and the gap is large enough to change your architecture. Time a realistic request against two or three candidates before committing. A chunk that one model returns in a few seconds can take another several minutes.

2. Make a single request

The response body is raw audio rather than JSON, so write the bytes straight to a file.

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

Mismatched combinations are rejected before any audio is generated, and the error tells you what would have worked instead:

{"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. Split text at the 4096 character limit

The input field accepts at most 4096 characters. Longer text is rejected outright rather than truncated silently:

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

So we split the article first. Splitting on sentence boundaries matters, because a chunk that ends mid sentence produces an audible stumble at the join. Create 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

On a 5362 character script this produces four chunks, each ending on a sentence:

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

The default max_chars is 1500 rather than something near the 4096 ceiling, and that is deliberate. Synthesis time grows with input length, so smaller chunks come back sooner and, because they run in parallel, finish the whole job faster. They also make retries cheap when one request fails.

4. Join the chunks into one file

Concatenating encoded audio such as MP3 is unreliable, because every chunk carries its own frame headers. Requesting pcm avoids the problem entirely. PCM is raw samples with no container, so joining is just appending bytes, and Python’s standard library wave module writes the header for us.

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

A single chunk returns quickly relative to how much audio it contains:

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

bytes   = 4269376
audio   = 88.9s

That request took about 13 seconds to produce 89 seconds of speech. Running the four chunks concurrently is what keeps the total reasonable: the full narration below took 15 seconds of wall clock time. ThreadPoolExecutor.map returns results in the order the inputs were submitted, so the chunks land in reading order even though they were synthesized at the same time.

Raw PCM carries no sample rate, so you have to supply the correct one when writing the WAV header, and it is model specific. tts-xai-v1 returns 24 kHz while tts-gradium-v1 returns 48 kHz. Guess wrong and the narration plays at the wrong speed and pitch.

To find the rate for any model, ask for one short clip as wav and read the header it comes back with:

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. Prepare text that sounds right

Scraped Markdown read aloud verbatim is close to unlistenable. URLs are the clearest example. A speech model spells them out one character at a time, so https://docs.venice.ai/llms.txt comes out as:

h t t p s colon slash slash docs dot venice dot a i l l m s dot t x t

Headings, bullet markers, tables, and code blocks cause smaller versions of the same problem. Rather than fighting Markdown with regular expressions, we can ask a chat model to rewrite the article as something meant to be spoken. Create 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()

The URL_PATTERN substitution stays in as a safety net for the occasional link the model leaves behind.

6. Put it together

The entry point scrapes, writes the script, saves it, and narrates:

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")

Saving script.txt next to the audio is worth the two lines. When a narration sounds wrong the script almost always shows why, and you can fix it without paying to synthesize again.

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)

Just under six minutes of narration, produced in about fifteen seconds. The script now opens with prose instead of navigation furniture:

Venice is built on a simple but powerful principle. User privacy comes first. The platform’s entire architecture flows from this philosophical commitment.

To check a narration without sitting through it, send the audio back through /audio/transcriptions and compare the transcript against script.txt. Transcribing the last twenty seconds is a quick way to confirm the chunks were joined in the right order, and it catches dropped chunks and spelled out URLs in seconds.

Streaming for interactive use

Batch narration optimizes total time. A voice interface has the opposite priority, which is getting the first audio out as fast as possible. Setting streaming: true returns the body sentence by sentence as it is generated, so playback can start in about a second instead of waiting for the complete clip.

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

Prefer pcm over mp3 when you are feeding a browser’s Web Audio API or an audio device directly, since it needs no decoding step.

Request options worth knowing

Parameter	Notes
`speed`	Accepts `0.25` to `4.0`, default `1.0`. Stay roughly within `0.8` to `1.3` for narration. Beyond that the delivery stops sounding natural.
`language`	Optional hint whose accepted form is model specific. xAI and ElevenLabs take ISO 639-1 codes such as `en`, while Qwen 3 and MiniMax take full names such as `English`. Unsupported values are ignored.
`prompt`	Style and emotion cue, up to 500 characters, currently honored only by the Qwen 3 models. For other families the voice choice carries the tone.
`temperature`	Range `0` to `2`, supported by Qwen 3, Orpheus, and Chatterbox HD. Raise it for more variation between takes.

Errors

Status	Cause	Fix
`400`	`input` over 4096 characters	Chunk the text as in section 3
`400`	Voice not valid for the model	Use a voice from that model’s `model_spec.voices`
`400`	Format not supported by the model	Check `model_spec.supported_formats`
`401`	Missing or invalid key	Confirm the `Authorization: Bearer` header
`402`	Insufficient balance	Top up the account
`429`	Rate limited	Lower `max_workers` and retry with backoff
`500` or `503`	Capacity or inference failure	Retry the affected chunk with jitter

Because the chunks are independent, a failure only ever costs you one of them, and retrying synthesize for that chunk is always safe.

Next steps

A few natural extensions from here:

Cache audio by a hash of the text, voice, and model so unchanged paragraphs are never re-synthesized.
Swap in a cloned voice with Voice Cloning so the narration uses your own.
Generate the source text instead of scraping it, using Cited Answers with Web Search.
Add intro or background audio with Music and Sound Effects.

Text-to-Speech

Reference for the speech endpoint and its parameters.

Voice Cloning

Narrate with a custom voice instead of a preset.

Cited Answers with Web Search

Generate the text this tool narrates.

Speech-to-Text

Transcribe audio to verify a narration end to end.

Docs

Getting Started

Text & Chat

Image

Video

Audio

Search & RAG

Agents & Integrations

Coding Tools

Agent Tooling

SDKs & Frameworks

Narrating Articles with Text-to-Speech

Run this tutorial in Google Colab

Setup

1. Choose a model and a voice

2. Make a single request

3. Split text at the 4096 character limit

4. Join the chunks into one file

5. Prepare text that sounds right

6. Put it together

Streaming for interactive use

Request options worth knowing

Errors

Next steps

Text-to-Speech

Voice Cloning

Cited Answers with Web Search

Speech-to-Text

Run this tutorial in Google Colab

​Setup

​1. Choose a model and a voice

​2. Make a single request

​3. Split text at the 4096 character limit

​4. Join the chunks into one file

​5. Prepare text that sounds right

​6. Put it together

​Streaming for interactive use

​Request options worth knowing

​Errors

​Next steps

Text-to-Speech

Voice Cloning

Cited Answers with Web Search

Speech-to-Text

Setup

1. Choose a model and a voice

2. Make a single request

3. Split text at the 4096 character limit

4. Join the chunks into one file

5. Prepare text that sounds right

6. Put it together

Streaming for interactive use

Request options worth knowing

Errors

Next steps