Bulk Generation

Process massive documents and long-form content in a single API request.

By default, the standard TTS endpoints are optimized for speed and low latency, restricting payloads to 5,000 characters per request. However, when building audiobooks, podcasts, or reading long articles, you may need to generate hours of continuous audio.

Our Bulk Generation mode removes these restrictions, allowing you to pass texts up to 1,000,000 characters at once, governed by your plan's specific Bulk Character limit.

---

How to Enable Bulk Mode

Using Bulk Mode is as simple as adding the "mode": "bulk" parameter to your standard /api/v1/tts/generate request. The API Gateway will automatically switch to a background processing flow that accepts larger payloads without timing out.

---

Bulk Limits by Plan

Your ability to use bulk generation is determined by your subscription tier. While standard limits are 5,000 characters, bulk limits scale up with your plan:

Note: If you exceed your plan's maximum bulk limit, the API will return a 429 Too Many Requests or 400 Bad Request indicating the limit has been surpassed. Custom limits can also be applied per-user by administrators.

---

Model & Language Optimization

Regional Accents Fallback Behavior

While our standard API supports a wide variety of specific regional accents, bulk generation may automatically fall back to the primary language region if the requested specific regional accent is not fully supported for bulk synthesis. When this happens, the API will not throw an error; it will automatically use the default regional accent.

If you strictly require a specific regional accent for long text and it is falling back, we recommend breaking the text into smaller chunks and using the standard generation endpoint instead.

---

Code Example: Python

The following example demonstrates how to process a long document using the bulk mode parameter while properly extending the network timeout.

import requests
import sys

API_URL = "https://yourvoic.com/api/v1/tts/generate"
API_KEY = "your_api_key_here"

# A very long text document
long_text = "Your very long text goes here... " * 1000

print(f"Generating audio for {len(long_text):,} characters...")

try:
    response = requests.post(
        API_URL,
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "text": long_text,
            "voice": "Peter",
            "language": "en-US",
            "model": "aura-prime",
            "mode": "bulk"  # Enable bulk processing
        },
        timeout=600  # Increase timeout to 10 minutes for long generations
    )
except requests.exceptions.Timeout:
    print("Error: The request timed out. Try reducing text size or increasing timeout.")
    sys.exit(1)

if response.status_code == 200:
    with open("audiobook_chapter.mp3", "wb") as f:
        f.write(response.content)
    print("Success! Audio saved to audiobook_chapter.mp3")
else:
    print(f"Error {response.status_code}: {response.text}")