Developer Guide: Integrating TTS API for Audiobook Generation

By ScribeRead editorial team · Updated 2026-11-18

This guide details the integration process for converting large-scale text documents into audio files using the ScribeRead API. It is designed for developers and no-code publishers who require a reliable, character-based solution for generating audiobooks without manual formatting overhead. You will find concrete instructions on authenticating requests, configuring parameters, and handling long-form content efficiently.

The documentation covers essential workflows including sending synthesis requests, managing rate limits, and selecting appropriate audio formats. By following these steps, you can integrate our TTS engine into your publishing pipeline, ensuring consistent delivery of high-quality synthetic speech tailored for self-publishing and digital distribution needs.

Developer Guide: Integrating TTS API for Audiobook Generation

Frequently asked questions

Do I need to install a specific SDK?

No proprietary SDK is required. You can use the official OpenAI SDKs by changing the base_url to https://api.playjp77.com/v1 and providing your site-specific key. Alternatively, you may use plain HTTP requests to interact with the API endpoints directly.

How do I set the base_url for the OpenAI SDK?

Configure your OpenAI SDK client by setting the base_url parameter to https://api.playjp77.com/v1. Ensure you pass your authentication key via the Authorization header. This allows standard speech generation endpoints to function correctly with our infrastructure.

What is the maximum input length for a single request?

Each request supports a maximum of 4096 characters in the input field. For longer documents, split the text into parts of this size and join the resulting audio files. Spaces and punctuation count toward this character limit.

Can I stream the audio as it generates?

No streaming or WebSocket support is available. The API returns the complete audio file in the response body after synthesis finishes. Requests are processed sequentially, so longer texts may experience queue delays before generation begins.

How do I know which voices support which languages?

All eight voice presets support all 23 listed languages. You can retrieve the full list of voices, languages, and formats by sending a GET request to /v1/voices. Any voice can speak any supported language without restriction.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key. If you exceed this, subsequent requests may be queued or rejected. New accounts start with a 10 requests per minute limit until the first top-up is processed.

Is the API key secure if I embed it in client code?

Each account has one active key. Issuing a new key immediately invalidates the old one. If you embed the key in client code, you can regenerate it anytime to revoke access, though this stops all active sessions instantly.

How do I detect the language automatically?

If the language field is omitted, the system guesses the language from the script. Latin script text defaults to English. For non-English Latin text, explicitly set the language parameter to ensure correct synthesis.

Can I use the API in a serverless environment?

Yes, the API uses standard HTTP POST requests. You can integrate it into serverless functions or edge networks by sending JSON payloads with your authentication header. No special client-side libraries are required for basic integration.

First request

curl

curl https://api.playjp77.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playjp77.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playjp77.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication and API Keys

Sound wave illustration for: Authentication and API Keys

Access to the ScribeRead API requires a valid bearer token. You generate this key on the /get-api-key/ page after signing in with Google or an email account. The key identifies your account for billing and rate-limiting purposes.

Use the token in the HTTP Authorization header to authenticate every request to the speech endpoint. Each account maintains one active key at a time; issuing a new key immediately invalidates the previous one.

Generating your API key

Generating your API key

Navigate to the /get-api-key/ page to create your account. Sign in using Google or your email and password. The dashboard displays your unique API key, starting with tts-, along with your current balance and character usage.

For Google sign-ins, a free trial credit of $0.50 is applied immediately. Email-based accounts start with zero credit until you top up via USDT on the TRON network.

  • Sign up via Google or email on /get-api-key/
  • Locate the key starting with 'tts-' in the dashboard
  • Check initial balance and character limits

Bearer token format

Bearer token format

Include your API key in the request header as a Bearer token. The format is Authorization: Bearer tts-<your-key>. This header must be present in every POST request to the speech endpoint.

The system validates this token against the account associated with the key. Ensure the key is kept secure and not exposed in public client-side code.

  • Format: Authorization: Bearer tts-<key>
  • Required for all API requests
  • Validates account identity and balance

Managing active keys

Only one API key is active per account. When you generate a new key from the dashboard, the previous key is invalidated immediately. Any pending requests using the old key may fail.

Regenerate your key if it is compromised. You can issue a new key at any time without affecting your existing balance or character limits.

  • One active key per account
  • New key invalidates the old one instantly
  • Regenerate anytime from the dashboard

Sending Your First Request

Sound wave illustration for: Sending Your First Request

To generate audio, send a POST request to the /v1/audio/speech endpoint. The API accepts standard JSON bodies, allowing you to specify the model, input text, voice preset, and output format in a single call. This structure ensures compatibility with existing OpenAI SDK integrations by simply adjusting the base URL.

Successful requests return the audio file directly in the response body, ready for immediate download. The system processes requests sequentially, so longer texts may experience slight delays depending on current queue load.

cURL example for speech generation

Use the following command to generate a short audio clip. Replace <YOUR_API_KEY> with your active key from the dashboard. The example uses the 'tts-1' model with the 'nova' voice.

```bash curl https://api.playjp77.com/v1/audio/speech \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "Welcome to ScribeRead audio generation.", "voice": "nova", "response_format": "mp3" }' \ --output audio.mp3 ```

Required JSON body fields

The request body must include the model ("tts-1" or "tts-1-hd"), input text (max 4096 characters), and voice preset. The response_format field accepts mp3, wav, opus, flac, or pcm. The speed parameter allows adjustment between 0.25 and 4.0. The language field is optional but recommended for non-English Latin script text to ensure accurate generation.

Texts exceeding 4096 characters must be split by the client into chunks. Each chunk generates a separate audio file that must be joined sequentially by your application.

  • model: "tts-1" or "tts-1-hd"
  • input: string, max 4096 chars
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25–4.0
  • language: optional ISO code

Understanding response codes

A 200 OK response indicates successful synthesis. The response body contains the raw audio bytes corresponding to the requested format. No additional JSON metadata is returned in the body for successful requests.

Rate limit errors (429) occur if you exceed 60 requests per minute. Authentication failures (401) indicate an invalid or expired API key. Input errors (400) typically result from exceeding the character limit or using an unsupported voice preset.

  • 200: Success, audio data returned
  • 400: Bad request, invalid parameters
  • 401: Unauthorized, invalid API key
  • 429: Too many requests, rate limited

Using OpenAI SDKs

Sound wave illustration for: Using OpenAI SDKs

The ScribeRead TTS API follows the OpenAI speech endpoint structure, allowing developers to leverage existing OpenAI SDKs with minimal configuration. By adjusting the base_url to https://api.playjp77.com/v1, you can utilize standard libraries for seamless integration into your audiobook generation pipeline.

Setting the base_url

Initialize your client by setting the base URL to https://api.playjp77.com/v1. Ensure your API key is passed via the Authorization: Bearer tts-... header. This configuration directs all requests to the correct endpoint while maintaining compatibility with standard HTTP clients.

  • Base URL: https://api.playjp77.com/v1
  • Header: Authorization: Bearer <your-key>

Configuring model parameters

Specify the model as tts-1 or tts-1-hd in your JSON body. Both use the same engine and pricing. Include required fields like input (text), voice (e.g., 'aria'), and response_format (e.g., 'mp3'). Optional parameters include speed (0.25–4.0) and language (ISO code).

Compatibility with official SDKs

Official OpenAI SDKs work directly by overriding the base URL. No custom SDK is required. This ensures consistent behavior for standard TTS operations, including handling of audio responses and error codes, without needing additional wrapper libraries.

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

Select the appropriate output format based on your audiobook distribution channel. MP3 offers efficient compression for web delivery, while WAV provides uncompressed high-quality audio suitable for archival or professional editing workflows.

MP3 for web delivery

MP3 is the recommended format for most digital distribution platforms. It balances file size and audio fidelity, suitable for web delivery without excessive bandwidth consumption. This format is ideal for direct download links embedded in your self-publishing portal.

WAV for high quality

Choose WAV when you require lossless audio for professional mastering or archival purposes. The uncompressed nature of WAV files preserves the full dynamic range of the generated speech, making it suitable for high-end audiobook production pipelines where post-processing is planned.

FLAC and OPUS options

FLAC provides lossless compression, reducing file size while retaining all original data, which is useful for internal storage optimization. OPUS is optimized for smaller file sizes, suitable for mobile applications or constrained network environments.

Handling Long Texts

Sound wave illustration for: Handling Long Texts

PDF documents often exceed the 4,096-character limit per request. Clients must split input text into chunks before sending POST requests to /v1/audio/speech. Each chunk generates a separate audio file.

After synthesis, clients join the resulting files sequentially to create a continuous audiobook. This approach ensures compatibility with the API’s character constraints while preserving the narrative structure of long-form content.

Splitting text into 4096 char chunks

Text must be divided so each segment contains no more than 4,096 characters. Spaces and punctuation count toward this limit. Use your preferred language tool to split the source PDF text into valid segments before iterating through them with API calls.

Joining audio files sequentially

Each request returns a single audio file. To reconstruct the full document, concatenate the output files in the same order as the input chunks. This creates a seamless listening experience for the final audiobook.

Managing queue delays

Requests are processed one after another. Under load, a request may wait in a queue before synthesis begins. Plan your integration timing accordingly, as generation speed is roughly real-time, producing about 25 characters of text per second of audio.

Handling Long Texts

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

Efficient API usage requires adherence to strict rate limits to ensure stable audio generation for your audiobook projects. Understanding these constraints prevents interruptions during bulk processing of long-form content.

60 requests per minute limit

The standard rate limit is 60 requests per minute per API key. This throughput is sufficient for most self-publishing workflows, allowing steady processing of chapter-length texts without significant bottlenecks.

10 requests per minute baseline

New accounts or those without recent top-ups operate at a baseline limit of 10 requests per minute. This lower threshold applies until the first top-up is processed.

Handling 429 errors

When the limit is reached, the API returns a 429 status code. Implement exponential backoff in your integration to retry requests automatically. Under load, requests may also queue, causing slight delays beyond the standard generation time.

  • Check the Retry-After header if provided.
  • Implement client-side queuing for large document batches.
  • Monitor your usage dashboard for real-time limit status.

Error Handling Guide

Sound wave illustration for: Error Handling Guide

Errors in the TTS API return specific HTTP status codes to indicate the nature of the failure. Understanding these responses allows your automation scripts to retry or adjust requests efficiently without consuming unnecessary credits.

Invalid model parameters

The API accepts only "tts-1" or "tts-1-hd" for the model field. Providing an unsupported string results in a 400 error.

Input text too long

Each request is limited to 4096 characters. Sending larger blocks returns a 400 error. You must split the text and join the resulting audio files sequentially.

Authentication errors

A missing or incorrect Bearer token returns a 401 Unauthorized error. Ensure the key starts with "tts-" and matches the account credentials exactly.

Voice and Language Parameters

Sound wave illustration for: Voice and Language Parameters

Select one of eight voice presets to define the narration style. Options include female voices like Aria or Luna, and male voices such as Felix or Orion, all capable of rendering the full range of supported languages.

Selecting a voice preset

Each voice offers a distinct tone, from the warm narration of Aria to the deep documentary style of Orion. The API accepts the voice ID directly in the request body to ensure consistent audio generation across your project.

  • Aria: Warm, clear narrator
  • Felix: Energetic, promo style
  • Atlas: Neutral, news tone
  • Orion: Deep, documentary style

Setting language ISO codes

Specify the ISO language code to ensure accurate pronunciation, particularly for non-English Latin-script text. If omitted, the system guesses the language, defaulting to English for Latin scripts, which may cause errors for other languages.

  • Supported: Arabic, Chinese, French, German, Japanese, Spanish, and others listed in the documentation.
  • Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali and all others not in the list.

Adjusting playback speed

Adjust the speed parameter between 0.25 and 4.0 to control the generation rate. Slower speeds may increase processing time, while faster speeds reduce character-per-second output. This allows fine-tuning for specific audiobook pacing requirements.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. His style keeps long-form non-fiction engaging without sacrificing clarity.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. curl documentation
  3. FFmpeg documentation
  4. openai-node on GitHub
  5. Python documentation
  6. IETF RFC 7845: Ogg Opus
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. Node.js documentation
  9. TRON developer hub: TRC-20
  10. Tether (USDT)
  11. LibriTTS-R corpus (OpenSLR 141)
  12. ISO 639 language codes

More on this site