Developer Documentation for Our Cloud Text-to-Speech API

By CourseSpeak editorial team · Updated 2026-11-19

This documentation provides the technical specifications for the CourseSpeak text-to-speech API, designed for engineering teams integrating with LMS platforms or generating large-scale audiobooks. You will find precise details on authentication, request parameters, and response handling to ensure reliable audio synthesis in your workflows.

Integrate using the standard OpenAI SDK by adjusting the base URL, or use direct cURL requests. The guide covers voice presets, audio formats, rate limits, and long-text splitting logic. All endpoints and error codes are defined here to help you build predictable, high-volume TTS solutions with clear engineering constraints.

Developer Documentation for Our Cloud Text-to-Speech API

Frequently asked questions

Do I need to install a specific SDK?

No. We do not provide an official SDK. You can use any HTTP client or the official OpenAI SDK by changing the base_url to https://api.m9871.info/v1. The request shape matches the OpenAI speech endpoint, so existing OpenAI SDK implementations work directly with our service.

Is the API compatible with OpenAI's Python client?

Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI Python SDK by setting the base_url to https://api.m9871.info/v1 and providing your CourseSpeak API key. This allows seamless integration for existing OpenAI workflows.

What happens if the API is rate-limited?

Requests are processed sequentially. If you exceed 60 requests per minute per key, new requests wait in a queue. Before your first top-up, the limit is 10 requests per minute. Failed requests are free. Queueing ensures fair processing under load.

Can I stream the audio as it generates?

No. The API does not support streaming or WebSocket connections. You send a POST request to /v1/audio/speech and receive the complete audio file in the response. You must wait for the full synthesis to complete before receiving the audio data in your application.

How do I handle long texts exceeding 4096 characters?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the speech endpoint. Then, join the resulting audio files in your application. This ensures compliance with the per-request character limit while allowing you to generate longer content.

Does the API support SSML tags?

No. The API does not support SSML tags, phoneme dictionaries, or custom pronunciation lexicons. You can adjust the speaking speed between 0.25 and 4.0, but fine-grained control over pauses or emphasis requires pre-processing your text or using the available voice presets for the desired tone.

What is the default audio format?

The default format is mp3. You can specify other formats like wav, opus, flac, or pcm in the request body. If you do not set the response_format field, the API returns the audio as an mp3 file.

Can I change the voice mid-sentence?

No. Each request generates audio for a single voice preset. To change voices, you must split the text, send separate requests for each voice, and concatenate the audio files. The API does not support dynamic voice switching within a single synthesis request or streaming response.

How do I rotate my API key?

You can issue a new key at any time from your account dashboard. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation without downtime. You can manage your keys directly on the /get-api-key/ page of the site.

Is there a webhook for completion notifications?

No. The API does not support webhooks or asynchronous callbacks. You must poll the API or wait for the synchronous response from the POST /v1/audio/speech endpoint. Since requests are processed sequentially, you may experience delays if the queue is long during high traffic periods.

What is the latency for short texts?

Short phrases take a few seconds to generate. For longer texts, generation is roughly real-time, about 25 characters per second. Under load, requests may wait in a queue, increasing latency. Failed requests are free.

Do I need to specify the language for English text?

No. If the language field is omitted, the API guesses the language from the script. Latin script text defaults to English. However, for non-English Latin-script text, you should explicitly set the language parameter to ensure accurate pronunciation and synthesis for the intended language.

Are there any deprecated endpoints?

No. The API currently supports POST /v1/audio/speech, GET /v1/voices, and GET /v1/models. These are the only active endpoints. We do not maintain a list of deprecated versions. Use the standard v1 path for all requests, consistent with the OpenAI endpoint structure.

How do I debug a failed request?

Check the HTTP status code and response body for error details. Failed requests are free, and the charge is returned in full. Ensure your text is under 4096 characters and your API key is valid. Use the /v1/voices endpoint to verify available voices and formats.

First request

curl

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

Authenticate every request by including your API key in the Authorization header as a Bearer token. This single key controls access to all endpoints and enforces the 60 requests per minute rate limit.

Keys are issued per account and remain active until rotated. You can generate a new key at any time via the dashboard, which immediately invalidates the previous key.

Bearer token usage

Bearer token usage

Include the header Authorization: Bearer tts-... in every POST and GET request. The key is tied to your account’s balance and rate limits.

  • Format: Authorization: Bearer tts-yourkey

Key management

Key management

Each account holds one active key. View your current key, balance, and usage stats on the dashboard page after signing in with Google or email.

  • One active key per account

Key rotation

Generate a new key from the dashboard at any time. The old key stops working immediately upon issuance of the new one, ensuring zero overlap in access.

No downtime occurs during rotation as the new key becomes active instantly.

  • Old key stops immediately
  • No overlap period

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints for integration. Use the speech endpoint to convert text into audio files. The voices and models endpoints provide metadata for configuration.

Speech generation

POST https://api.m9871.info/v1/audio/speech accepts JSON input and returns an audio file. This endpoint handles the synthesis logic, including language detection and speed adjustments.

  • Endpoint: POST /v1/audio/speech
  • Input: JSON body with model, input, voice, response_format, speed

List voices

GET /v1/voices returns available presets, supported languages, and formats. Use this to build dynamic voice selectors in your LMS interface without hardcoding options.

  • Endpoint: GET /v1/voices
  • Returns: voice ID, name, language support, and format availability

List models

GET /v1/models lists available engine versions. Currently, only tts-1 and tts-1-hd are supported, both sharing the same engine and pricing structure.

  • Endpoint: GET /v1/models
  • Returns: model ID, name, and associated metadata

Parameters

Sound wave illustration for: Parameters

The API accepts two model identifiers, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing tier. The distinction lies solely in audio fidelity; both process input text up to 4096 characters per request without any difference in base cost.

Model selection

Select tts-1 for standard generation or tts-1-hd for higher fidelity. Both models support the same eight voice presets and language settings, ensuring consistent behavior across quality tiers.

Voice presets

Choose from eight licensed presets tailored for different LMS and audiobook contexts. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male options offer Felix (energetic), Milo (conversational), 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

Speed and format

Adjust playback speed between 0.25 and 4.0 to fit course pacing requirements. The API supports MP3, WAV, Opus, FLAC, and PCM output formats. While MP3 is efficient for web delivery, WAV and FLAC provide lossless quality for archival purposes. Opus and PCM are available for specific integration needs.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

To use the official OpenAI SDKs, configure the base_url to https://api.m9871.info/v1 and set the Authorization header with your Bearer token. This allows you to use existing client libraries without rewriting request logic, ensuring consistent integration across your LMS or audiobook pipeline.

Pass your API key (starting with tts-) as the Bearer token. The SDK handles the HTTP POST to /v1/audio/speech, returning audio files directly in memory or saving them to disk, depending on your implementation preferences.

Base URL configuration

Initialize your client with the base URL https://api.m9871.info/v1. This endpoint mirrors the OpenAI speech structure, allowing seamless substitution of the standard OpenAI base URL. Ensure your API key is passed via the Authorization: Bearer <key> header for authentication.

  • Base URL: https://api.m9871.info/v1
  • Auth Header: Authorization: Bearer tts-...
  • Compatible with official OpenAI SDKs

Python SDK example

Import the OpenAI client and set the base URL. The audio.speech.create() method accepts standard parameters like model, input, voice, and response_format. The response object contains the audio bytes, which you can write directly to a file or process further.

  • Use openai.OpenAI(base_url=...)
  • Call client.audio.speech.create()
  • Handle response.content for audio bytes

Node.js SDK example

In Node.js, initialize the OpenAI client with the custom base URL. Invoke audio.speech.create() with your text and voice settings. The method returns the audio data, which you can write to a file or process further.

  • Initialize client with base_url
  • Use audio.speech.create()
  • Handle response as stream or buffer

cURL Example

Sound wave illustration for: cURL Example

The API accepts standard JSON payloads via POST requests. This section provides concrete examples for immediate integration into your LMS or audiobook generation pipeline.

Basic request

Send a POST request to the speech endpoint with your Bearer token in the Authorization header.

JSON body structure

Include the model, input text, voice, and response format in the body. Text must not exceed 4096 characters.

  • model: "tts-1" or "tts-1-hd"
  • input: string up to 4096 chars
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, or pcm

Response handling

The response contains the binary audio data or an error JSON. Failed requests return zero charges.

cURL Example

Limits and Errors

Sound wave illustration for: Limits and Errors

The API enforces strict rate limits to ensure stable service for high-volume LMS integrations. Each API key is limited to 60 requests per minute once your account is active. Before your first top-up, the limit is lower at 10 requests per minute. Requests are processed sequentially, so under heavy load, a request may wait in a queue before synthesis begins.

For typical long-form content, generation speed is roughly real-time, averaging about 25 characters of text per second. Short phrases may take a few seconds to process. Understanding these limits helps engineering teams design robust retry logic and manage billing predictability for large-scale audiobook generation.

Rate limits per minute

Your API key allows a maximum of 60 requests per minute. This limit applies per key, so distributing load across multiple keys can increase throughput. If you exceed the limit, the API returns a 429 Too Many Requests error.

Before your first top-up, the rate limit is reduced to 10 requests per minute. After topping up via USDT (TRC-20), the limit increases to the standard 60 requests per minute.

  • 60 requests/minute for active accounts
  • 10 requests/minute before first top-up
  • Sequential processing may cause queuing under load

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 4096 characters, you must split it into smaller chunks and join the resulting audio files.

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

  • Maximum 4096 characters per request
  • Spaces and punctuation count as characters
  • Failed requests are free

Common error codes

401 Unauthorized: Invalid or expired API key. Ensure your Authorization header includes 'Bearer tts-...' and verify your key in the dashboard.

429 Too Many Requests: Rate limit exceeded. Wait before retrying or distribute load across multiple keys.

400 Bad Request: Invalid parameters or missing required fields. Check your JSON body structure and ensure the text does not exceed 4096 characters.

  • 401: Invalid or expired key
  • 429: Rate limit exceeded
  • 400: Invalid parameters

Audio Formats

Sound wave illustration for: Audio Formats

The API supports five distinct output formats to suit various LMS playback engines and storage constraints. You select the desired format via the response_format parameter in the request body. Each format balances file size, compatibility, and audio fidelity differently.

MP3 support

MP3 is the default and most widely supported format. It offers good compression with acceptable quality for speech, making it ideal for web-based course players that need to minimize bandwidth usage.

  • Best for web playback and mobile apps.
  • Smallest file size among lossy formats.

WAV and FLAC

WAV provides uncompressed audio, ensuring maximum compatibility with legacy LMS platforms. FLAC offers lossless compression, reducing storage costs while preserving bit-perfect audio quality for archival purposes.

  • WAV: Universal compatibility, larger files.
  • FLAC: Lossless compression, smaller than WAV.

Opus and PCM

Opus is a modern, efficient codec suitable for streaming and low-bandwidth environments. Raw PCM provides uncompressed linear audio data, useful for direct audio processing pipelines that handle encoding themselves.

  • Opus: High efficiency, modern standard.
  • PCM: Raw data for custom processing.

Long Text Handling

Sound wave illustration for: Long Text Handling

Text exceeding 4096 characters must be split into chunks before sending separate requests. Each chunk generates its own audio file, requiring client-side logic to manage the sequence. This approach ensures consistent character counting and predictable billing for long-form content like audiobooks or course lectures.

The API does not automatically join files; your integration must concatenate the returned audio streams in order. This gives engineering teams full control over the final output structure and error handling during the synthesis pipeline.

Splitting at 4096 chars

Break input text into segments of up to 4096 characters. Spaces and punctuation count toward this limit. Send each segment as a distinct POST request to ensure accurate character billing and reliable processing.

Joining audio files

Receive individual audio files for each chunk. Your application must concatenate these files in the correct sequence to reconstruct the full narration. Supported formats include MP3, WAV, OPUS, FLAC, and PCM.

Queue behavior

Requests are processed sequentially. Under load, a request may wait in a queue before synthesis begins. Typical speed is roughly 25 characters of text per second of generation for long texts.

image]:

image

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. These errors stem from assuming consumer-grade features or overlooking technical constraints defined in the specification.

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. Node.js documentation
  3. LibriVox public-domain audiobooks
  4. openai-node on GitHub
  5. LibriTTS-R corpus (OpenSLR 141)
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. MDN: Web Speech API
  8. FFmpeg documentation
  9. TRON developer hub: TRC-20
  10. W3C WAI: making audio and video accessible
  11. OpenAI API reference: create speech
  12. curl documentation

More on this site