API Documentation for Audiobook Creators and Developers

By ReadCast editorial team · Updated 2026-11-19

This documentation guides audiobook creators and developers through the ReadCast API, enabling seamless text-to-speech integration for self-publishing workflows. You will find precise specifications for authentication, endpoint usage, and parameter tuning, ensuring consistent audio generation from manuscript to final file.

The guide covers essential technical details including OpenAI SDK compatibility, voice selection, and handling long texts beyond the 4096-character limit. With predictable character-based pricing and clear rate limits, you can reliably scale your audiobook production without enterprise contracts or hidden fees.

API Documentation for Audiobook Creators and Developers

Frequently asked questions

What is the base URL for the API?

The base URL is https://api.link02.info/v1. All requests, including speech synthesis and voice listing, are sent to this endpoint. You must include your Bearer token in the Authorization header for authentication.

Can I use the official OpenAI Python SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.link02.info/v1. Use your ReadCast API key as the API key. The request shape matches the OpenAI speech endpoint exactly.

How do I specify a different language for the voice?

Pass the optional 'language' field with an ISO code in the JSON body. If omitted, the language is guessed from the script, defaulting to English for Latin text. Explicitly setting it ensures correct pronunciation for non-English languages.

What is the maximum input length per request?

The maximum input length is 4096 characters per request. If your text exceeds this limit, you must split it into parts, generate audio for each part, and join the resulting audio files manually.

Do I need to install any specific libraries?

No specific library is required. You can use plain HTTP requests or the official OpenAI SDK. No custom SDK, mobile SDK, or WordPress plugin is provided by ReadCast API.

How do I handle rate limit errors?

The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so under load, a request may wait in a queue. Implement retry logic with exponential backoff for rate limit errors.

Is the API key the same for all endpoints?

Yes, one active Bearer key per account works for all endpoints, including /v1/audio/speech and /v1/voices. A new key issued replaces the old one immediately.

Can I preview voices before buying?

The API does not provide a dedicated preview endpoint. You can generate short audio samples using the free trial credit ($0.50) to test voice quality and language support before making a top-up.

What happens if I exceed the 4096 character limit?

The request will likely fail or truncate. You should split your text into chunks of up to 4096 characters, generate audio for each chunk, and join the resulting audio files.

How do I know which model to use?

Use 'tts-1' for standard quality or 'tts-1-hd' for high definition. Both models use the same engine and price ($0.01 per 1,000 characters). Choose based on your audio quality requirements.

Are the audio files returned as base64 or binary?

The API returns the audio file directly in the response body. The format depends on the 'response_format' parameter (mp3, wav, opus, flac, or pcm). It is not base64 encoded unless specified by your client.

Can I stream the audio directly to a player?

No, the API does not support streaming or WebSocket connections. The entire audio file is returned after synthesis is complete. You must wait for the full response before playing the audio.

How do I retrieve the list of available voices?

Send a GET request to /v1/voices. This endpoint returns details about available voices, languages, formats, and pricing information. It helps you select the appropriate voice for your text.

Is there a webhook for completion notifications?

No, there is no webhook support. The API is synchronous; you receive the audio file in the response after synthesis completes. You must poll or wait for the response to get the audio.

First request

curl

curl https://api.link02.info/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.link02.info/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.link02.info/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 Keys

Sound wave illustration for: Authentication and Keys

ReadCast API uses a single active bearer token for authentication, sent via the Authorization: Bearer header. You generate this key on the /get-api-key/ dashboard page, where it appears alongside your current balance and usage statistics.

Generating Your API Key

Generating Your API Key

Sign in with Google or an email account to create your initial key. The dashboard displays the key immediately; copy it securely, as it is shown only once during creation.

  • Available on the /get-api-key/ page
  • Visible immediately after account creation

Key Security Practices

Key Security Practices

Treat your key like a password. Include it in the HTTP header Authorization: Bearer <key> for every request to https://api.link02.info/v1. Do not expose it in client-side JavaScript or public Git repositories.

  • Include in Authorization header
  • Avoid client-side exposure

Rotating Keys

Generate a new key from the dashboard at any time. The previous key stops working immediately upon issuance of the new one, ensuring no overlap in active credentials. Revoke old keys instantly if you suspect a leak.

  • Old key invalidates immediately
  • No waiting period for rotation

First Request with cURL

Sound wave illustration for: First Request with cURL

The core of the ReadCast API is a single HTTP endpoint that converts your manuscript text into audio. By sending a POST request to the speech endpoint, you receive a direct audio file ready for integration into your audiobook workflow.

Basic Speech Endpoint

Send your request to https://api.link02.info/v1/audio/speech. This endpoint accepts your text and configuration parameters, processing them to generate the audio file. Ensure you include your API key in the authorization header.

JSON Body Structure

The request body must be JSON containing the model, input text, voice, response_format, and optional speed or language fields. The input text is limited to 4096 characters per request.

  • model: "tts-1" or "tts-1-hd"
  • input: your text string
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, or pcm

Response Handling

On success, the API returns the audio file directly in the response body. Failed requests are free: if synthesis fails, the charge is returned in full. Handle the binary audio data to save it locally or integrate it into your publishing pipeline.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

The ReadCast API uses the same request shape as the OpenAI speech endpoint, allowing developers to leverage existing SDKs with minimal configuration. By simply adjusting the base URL, you can use the official OpenAI client to generate audiobooks without learning a new library.

This approach simplifies integration for independent authors and developers who already utilize OpenAI’s SDKs. You authenticate with your ReadCast key and send text payloads exactly as you would for the OpenAI speech endpoint.

Base URL Configuration

Set the base_url to https://api.link02.info/v1 in your OpenAI client instance. This directs all requests to the ReadCast infrastructure while maintaining the standard JSON request shape.

Ensure your OPENAI_API_KEY environment variable or client initialization contains your ReadCast key (starting with tts-...). The SDK will automatically attach this key to every request header.

  • Base URL: https://api.link02.info/v1
  • Standard OpenAI SDK compatibility
  • No custom library required

Client Initialization

Initialize the OpenAI client using your standard Python, Node.js, or other language client. Pass the ReadCast API key and the configured base URL.

The client handles authentication and request formatting automatically. You do not need to modify the underlying request structure or headers manually.

  • Use standard OpenAI Python/JS SDKs
  • Pass base_url parameter
  • Inject tts-... key

Code Examples

Below is a Python example using the OpenAI SDK to generate speech. Replace YOUR_API_KEY with your ReadCast key.

The code sends a text input and receives an audio file in the specified format, ready for saving or playback in your audiobook pipeline.

  • Python SDK example
  • Node.js SDK example
  • Error handling integration

Audio Formats and Models

Sound wave illustration for: Audio Formats and Models

ReadCast API supports five output formats to suit different playback environments. Choose MP3 for broad compatibility, WAV for lossless quality, or OPUS and FLAC for efficient compression. PCM provides raw uncompressed data for direct processing.

MP3 vs WAV

MP3 is the default choice for web players and mobile apps due to its small file size and universal support. WAV offers uncompressed, lossless audio ideal for archival or further editing in professional software.

OPUS and FLAC Options

OPUS provides high-quality audio at significantly lower bitrates, making it efficient for bandwidth-constrained environments. FLAC offers lossless compression, preserving every detail of the synthesis while reducing file size compared to WAV.

PCM Raw Audio

PCM returns raw, uncompressed audio samples. This format is useful when you need to process the audio stream directly without decoding overhead, such as in custom audio pipelines or specific hardware integrations.

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

ReadCast API enforces a rate limit of 60 requests per minute per API key. This limit applies to all endpoints. It ensures stable performance for high-volume audiobook production workflows.

60 Requests Per Minute

Each active key allows up to 60 requests every minute. This capacity supports standard batch processing. Exceeding this limit returns a 429 Too Many Requests error. You must wait until the window resets before sending additional requests.

Pre-Top-up Limits

Accounts without a top-up are restricted to 10 requests per minute. This lower limit applies to free trial accounts and those with insufficient balance. It prevents resource exhaustion while allowing basic testing of voice quality and format options.

Queue Behavior

Requests are processed sequentially. If the system is busy, your request may wait in a queue before synthesis begins. This can extend generation time for short phrases beyond the typical few seconds. Longer texts generally process at roughly real-time speed (25 characters per second).

Rate Limits and Throttling

Error Handling and Status Codes

Sound wave illustration for: Error Handling and Status Codes

When processing manuscripts, network interruptions or invalid inputs may occur. Understanding HTTP status codes helps you distinguish between transient issues and permanent failures.

Common Error Codes

Use 400 Bad Request when input text exceeds 4096 characters or contains invalid JSON structure. A 401 Unauthorized response indicates an expired or incorrect Bearer token, requiring immediate key rotation via your dashboard. Rate limiting returns 429 when you exceed 60 requests per minute, signaling that you should pause and retry.

  • 400: Invalid input or character limit exceeded
  • 401: Invalid or revoked API key
  • 429: Rate limit exceeded (60 req/min)

Retry Strategies

Implement exponential backoff for 429 and 500-level errors. Wait briefly between retries to allow queued requests to process, as synthesis occurs sequentially under load. Avoid rapid-fire retries for 400 errors, as the input error will persist until corrected.

  • Use exponential backoff for 429 and 5xx errors
  • Wait briefly to allow queued requests to process
  • Avoid rapid retries for persistent 400 errors

Billing on Errors

Failed synthesis requests are free. If the API returns an error before audio generation completes, the charge is returned in full. You only pay for successful audio files, ensuring predictable costs even when handling large manuscript batches with occasional hiccups.

Voice Selection and Parameters

Sound wave illustration for: Voice Selection and Parameters

ReadCast API provides eight distinct voice presets, categorized by gender and tonal quality, designed to suit various narrative styles. Users can retrieve the full list of available voices, their associated languages, and supported formats via the GET /v1/voices endpoint.

Each voice is derived from licensed recordings. The API allows precise control over delivery speed and language detection.

Listing Available Voices

The /v1/voices endpoint returns metadata for all eight presets, including Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. This data helps developers map specific character traits to the appropriate voice model before generating audio.

Setting Speed and Language

Speed ranges from 0.25 to 4.0, allowing for slower, deliberate narration or faster, energetic delivery. The optional language parameter accepts ISO codes; if omitted, the system guesses the language from the script, defaulting to English for Latin text.

Voice Characteristic Mapping

Female voices include Aria (warm narrator), Nova (bright), Luna (soft storytelling), and Sage (calm instruction). Male options cover Felix (energetic promo), Milo (friendly conversation), Atlas (neutral news), and Orion (deep documentary).

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational
  • Atlas: Neutral, news
  • Orion: Deep, documentary

Handling Long Texts

Sound wave illustration for: Handling Long Texts

Manuscripts often exceed the 4096-character limit per request. This section covers how to handle texts larger than this limit by splitting them into manageable chunks.

4096 Character Limit

Each POST request accepts up to 4096 characters of input text. Spaces, punctuation, and special characters count toward this limit. If your text exceeds this, you must split it before sending.

Splitting Logic

Split your manuscript into segments of no more than 4096 characters. Preserve sentence boundaries where possible to ensure natural audio transitions. Use character counting libraries in your preferred language to calculate chunk sizes accurately.

  • Count spaces and punctuation as characters.
  • Preserve sentence structure for better audio flow.
  • Use standard string length functions for splitting.

Audio Joining Strategies

After receiving audio files for each chunk, concatenate them in order. Use audio processing libraries like FFmpeg or your language's built-in tools. Ensure consistent audio formats (e.g., all MP3 or all WAV) to avoid compatibility issues during joining.

  • Maintain original order of chunks.
  • Use consistent audio formats.
  • Verify final audio continuity.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The ability to specify language codes ensures accurate pronunciation for non-native speakers, enhancing accessibility for diverse student demographics.

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. openai-node on GitHub
  3. MDN: Web Speech API
  4. OpenAI API reference: create speech
  5. ISO 639 language codes
  6. LibriTTS-R corpus (OpenSLR 141)
  7. Python documentation
  8. IETF RFC 7845: Ogg Opus
  9. FFmpeg documentation
  10. W3C WAI: making audio and video accessible
  11. Tether (USDT)
  12. LibriTTS-R paper (arXiv 2305.18802)

More on this site