API Documentation for Text-to-Speech Integration

By FableSays editorial team · Updated 2026-11-19

This documentation provides a practical guide for teachers and methodologists integrating FableSays’ text-to-speech API into lesson planning tools or accessibility workflows. You will find clear instructions on generating audio files from text using standard HTTP requests or the OpenAI SDK, with specific examples relevant to reading children’s stories and fairy tales aloud.

Learn how to authenticate with your API key, select from eight clear voices, and handle character limits efficiently. The guide covers request parameters, response formats like MP3 and WAV, rate limits, and error handling, ensuring you can reliably convert text to speech for your students’ materials with minimal technical overhead.

API Documentation for Text-to-Speech Integration

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or an email and password. The page displays your active key, balance, and usage details. You can issue a new key at any time, which immediately invalidates the old one. Each account is tied to the specific site domain.

What is the base URL for the API?

The API base URL is https://api.cb125.info/v1. You send POST requests to https://api.cb125.info/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models for retrieving available voices and model information.

Does the API support streaming audio?

No, the API does not support streaming, WebSocket connections, or real-time partial audio. You send text and receive the complete audio file in the response. The endpoint returns the final synthesized audio once processing is complete.

Can I use the OpenAI Python SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.cb125.info/v1 and using your FableSays API key. The request shape matches the OpenAI speech endpoint, allowing you to use familiar SDK methods for integration.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key. If you exceed this, requests may wait in a queue. Before the first top-up, the limit is 10 requests per minute. Failed requests do not consume your character balance.

How do I split long texts into parts?

Split your text into parts of up to 4096 characters each. Send each part as a separate POST request to the speech endpoint. Then, join the resulting audio files on your end to create the final continuous audio file.

What is the character limit per request?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. If your text exceeds this length, you must split it into multiple requests and combine the resulting audio files afterward.

Can I specify the language explicitly?

Yes, you can set the optional 'language' field to an ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly setting the language ensures accurate synthesis.

How do I change the audio speed?

Include the 'speed' parameter in your request body. The value must be between 0.25 and 4.0. This allows you to adjust the playback speed of the generated audio to suit your specific educational or accessibility needs.

Is SSML supported in the API?

No, the API does not support SSML (Speech Synthesis Markup Language). You cannot use SSML tags to control pronunciation, pauses, or emphasis. Input is plain text only, processed directly by the TTS engine without markup interpretation.

What formats are available for download?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the 'response_format' field in your request. The API returns the audio file in the selected format within the response body.

How do I rotate my API key?

You can issue a new API key at any time via the dashboard. When a new key is generated, the old one stops working immediately. This allows you to rotate keys securely without downtime, ensuring only active keys are used.

First request

curl

curl https://api.cb125.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.cb125.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.cb125.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

Sound wave illustration for: Authentication

Access the FableSays API using a single active key per account. Generate your key at /get-api-key/ to begin sending text-to-speech requests immediately.

Include the key in the HTTP header as a Bearer token. Keep it secure; anyone with the key can use your balance.

API Key Format

API Key Format

Your API key starts with the prefix tts- followed by a unique alphanumeric string. This format ensures simple identification in your code and logs.

Keys are generated exclusively for your account on cb125.info. Each account holds exactly one active key at any time.

  • Prefix: tts-
  • Format: tts- + alphanumeric string
  • One key per account

Bearer Token Usage

Bearer Token Usage

Include the key in every request header: Authorization: Bearer tts-.... The API validates this token before processing synthesis.

If the token is missing or invalid, the request returns a 401 Unauthorized error without consuming any characters from your balance.

Key Rotation Policy

You can issue a new key at any time via your dashboard. When a new key is created, the old one stops working immediately.

This allows instant revocation if a key is exposed. Use this feature to maintain security without downtime for existing integrations.

Endpoints

Sound wave illustration for: Endpoints

The API provides three core endpoints for generating and managing audio. The primary endpoint handles text synthesis, while the secondary endpoints allow you to discover available voices and model configurations without making audio requests.

Each endpoint follows a standard JSON structure, ensuring compatibility with common HTTP clients and SDKs. You can retrieve voice metadata to select the best narrator for your educational materials, then generate the audio file using the speech endpoint.

POST /v1/audio/speech

Send text to receive an audio file. The endpoint accepts a JSON body with the text, voice selection, and output format. It returns the synthesized audio directly in the response, ready for download or playback.

This is the main endpoint for creating lesson audio or accessibility content. You can specify the speed and language to ensure clear pronunciation for students.

  • Accepts text up to 4096 characters
  • Returns audio in mp3, wav, opus, flac, or pcm
  • Supports speed adjustment from 0.25 to 4.0

GET /v1/voices

Retrieve a list of all available voices, their associated languages, and supported formats. This endpoint helps you choose the right narrator for your content, such as Aria for clear storytelling or Felix for energetic promos.

Use this endpoint to verify which voices support the specific languages you need, such as Japanese, English, or German, before making synthesis requests.

  • Lists all 8 voice presets
  • Shows supported languages per voice
  • Displays available output formats

GET /v1/models

View the available TTS models, including tts-1 and tts-1-hd. Both models use the same engine and pricing. Use this endpoint to confirm the model IDs required for your API calls.

The models endpoint ensures you are using the correct identifiers for your integration, avoiding errors in your request payload.

  • Lists available model IDs

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis parameters to match your lesson content. The API accepts plain text input and returns audio files in standard formats. Ensure your requests include the correct model, voice, and language settings to achieve the desired narration style for your students.

Model Selection (tts-1, tts-1-hd)

Select "tts-1" or "tts-1-hd"; both use the same engine and pricing. Both models use the same engine and pricing, allowing you to test quality without extra cost.

Input Text Limit

Each request supports up to 4,096 characters, including spaces and punctuation. For longer stories, split the text into parts and join the resulting audio files sequentially.

  • Maximum 4,096 characters per request

Voice and Language Options

Choose from eight preset voices, such as Luna for storytelling or Felix for energetic promos. Set the "language" field to an ISO code (e.g., "ja") to ensure correct pronunciation for non-English texts.

If the language is omitted, the system guesses from the script, defaulting to English for Latin text. This is useful for mixed-language classroom materials.

  • 8 voices available (e.g., Aria, Nova, Luna)

Response Formats

Sound wave illustration for: Response Formats

Each synthesis request returns a single audio file containing the entire generated speech. The format is determined by the response_format parameter in your request body.

MP3 Output

MP3 is the default and most compatible format. It offers a good balance between file size and quality, making it ideal for web playback and general distribution.

WAV Output

WAV provides uncompressed, high-fidelity audio. Use this format if you need raw audio data for editing software or strict quality requirements without compression artifacts.

Opus and FLAC Options

Opus offers efficient compression for storage-constrained environments. FLAC provides lossless compression, preserving exact audio quality while reducing file size compared to WAV.

Rate Limits

Sound wave illustration for: Rate Limits

Understanding rate limits ensures your lesson audio generation remains smooth and predictable. Our API enforces strict quotas to maintain stability for all teachers and methodologists using the service simultaneously. Knowing these boundaries helps you plan your text-to-speech workflows effectively without unexpected interruptions during class preparation or student accessibility tasks.

60 Requests Per Minute

Each API key is allowed a maximum of 60 requests per minute once your account is fully active. This limit applies to all requests.

  • Limit is per API key, not per account.

10 Requests Before Top-Up

New accounts start with a reduced limit of 10 requests per minute until the first top-up is processed. This allows you to test the integration with your curriculum materials before committing to larger volumes. Once your USDT transfer is confirmed, the limit automatically increases to the standard 60 requests per minute.

Queue Behavior

Requests are processed sequentially. For longer texts split into multiple parts, each part counts as one request. Under high load, a request may wait in a queue before synthesis begins, which can slightly extend the total time required to generate a full chapter. Short phrases typically generate within a few seconds.

Queue Behavior

Requests are processed sequentially. For longer texts split into multiple parts, each part counts as one request. Under high load, a request may wait in a queue before synthesis begins, which can slightly extend the total time required to generate a full chapter. Short phrases typically generate within a few seconds, while longer texts may take longer due to this sequential processing.

Rate Limits

Error Handling

Sound wave illustration for: Error Handling

Robust error handling ensures your lesson plans stay on track. When synthesis fails, FableSays returns standard HTTP status codes to indicate the issue, allowing your integration to adapt gracefully without losing context.

Common Error Codes

Use 401 for invalid keys, 429 for rate limits, and 500 for server-side synthesis failures. Each response includes a clear error message to help you debug quickly.

  • 401: Unauthorized (invalid or expired key)
  • 429: Too Many Requests (rate limit exceeded)
  • 500: Internal Server Error (synthesis failure)

Retry Logic

For 429 errors, wait briefly before retrying, as requests are processed sequentially. For 500 errors, implement exponential backoff to handle temporary queue congestion. Avoid rapid-fire retries to respect the 60 requests per minute limit.

Billing on Errors

Failed requests are free. If synthesis fails, the charge is returned in full, ensuring you only pay for successful audio generations.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The FableSays API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDKs with minimal configuration. By simply adjusting the base URL, you can generate audio files directly in your classroom preparation scripts or accessibility tools without learning a new library.

Base URL Configuration

Set the SDK's base URL to https://api.cb125.info/v1. This directs all requests to our infrastructure while maintaining the standard request shape. Your authentication header remains Bearer <your-key>, identical to the OpenAI standard.

SDK Compatibility

Any official OpenAI SDK works because we use the same JSON body structure. This includes support for the tts-1 and tts-1-hd models, voice selection, and speed adjustments. You do not need a custom FableSays SDK; the standard libraries handle the integration seamlessly.

  • Compatible with official OpenAI SDKs
  • Uses standard POST /v1/audio/speech structure
  • No proprietary client required

Code Examples

Initialize your client with the new base URL and your API key. Pass the text, voice, and format parameters just as you would for OpenAI. The response will contain the audio bytes, ready to be saved as an MP3 or WAV file for student use.

  • Example: client.base_url = "https://api.cb125.info/v1"
  • Example: audio = client.audio.speech.create(...)

CURL Example

Sound wave illustration for: CURL Example

Use this cURL command to generate audio directly from your terminal. Replace YOUR_API_KEY with your key from the dashboard and adjust the voice or text as needed for your lesson materials.

Basic Request Structure

The command sends a POST request to the speech endpoint. The JSON body defines the model, input text, voice preset, and output format. This structure mirrors the standard OpenAI compatibility layer, making it easy to test locally before integrating into your classroom tools.

Headers and Body

Include the Bearer token in the Authorization header. The input text must not exceed 4096 characters. You can specify the response format as mp3, wav, opus, flac, or pcm. The speed parameter accepts values between 0.25 and 4.0, allowing you to adjust reading pace for students.

  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json
  • model: tts-1
  • voice: nova
  • input: "Once upon a time..."
  • response_format: mp3

Response Handling

On success, the API returns the audio file directly in the response body. You can save this output to a file using the -o flag. If the request fails, check the status code and error message to debug issues like invalid keys or rate limits.

  • Save output: curl -o output.mp3 ...
  • Check status codes for errors
  • Handle JSON error messages if present

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. It works well for young adult fiction or modern stories where a traditional fairy tale voice might feel too juvenile.

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. Creative Commons Attribution 4.0
  3. LibriVox public-domain audiobooks
  4. openai-python on GitHub
  5. openai-node on GitHub
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. W3C WAI: making audio and video accessible
  8. OpenAI API reference: create speech
  9. FFmpeg documentation
  10. Python documentation
  11. ISO 639 language codes
  12. curl documentation

More on this site