API Documentation for CourseCast Text-to-Speech

By CourseCast editorial team · Updated 2026-11-19

This guide helps edtech teams and startup founders integrate CourseCast’s text-to-speech API into their learning management systems. You will find concrete steps to generate audio from Hindi and other supported languages, manage your API key, and handle multilingual narration workflows efficiently.

We cover authentication, SDK compatibility, and rate limits with specific examples. The documentation explains how to split long texts, choose between models, and understand error codes. Everything you need to automate audio generation for accessibility and course content is included here.

API Documentation for CourseCast Text-to-Speech

Frequently asked questions

How do I authenticate with the API?

Include your API key in the request header as Authorization: Bearer tts-.... You receive one active key per account, which you can find on your dashboard. If you issue a new key, the old one stops immediately. Ensure you keep this key secure to prevent unauthorized usage of your balance.

Can I use the official OpenAI SDK?

Yes. The endpoint structure matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.xsmbthu7.info/v1 and providing your site-specific key. This allows you to integrate the API into your existing workflows without learning a new library.

What is the base URL for the API?

The base URL is https://api.xsmbthu7.info/v1. All API requests, including the speech generation endpoint and voice listing, originate from this domain. Ensure your SDK configuration points to this URL to route requests correctly to our infrastructure for text-to-speech synthesis.

How do I specify the language in Hindi?

Pass the ISO language code hi in the language field of your request body. Although the API guesses language from the script, explicitly setting the language ensures correct pronunciation for Hindi text. This is recommended for non-English Latin-script text to avoid default English interpretation.

What happens if I exceed the rate limit?

You are limited to 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a 10 requests per minute limit until the first top-up. Monitor your usage via the dashboard to avoid throttling during high-volume generation tasks.

Are failed requests refunded automatically?

Yes. If synthesis fails, the charge is returned in full to your balance. You do not need to manually request a refund. This ensures you only pay for successfully generated audio files, protecting your budget during unexpected errors or network issues during the generation process.

How do I handle texts longer than 4096 characters?

Split your input text into parts of up to 4096 characters. Send each part as a separate request and then join the resulting audio files. This ensures each request stays within the character limit while allowing you to generate audio for longer documents or course modules.

What audio formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format using the response_format field in the request body. These formats cover most use cases, from web playback to high-quality archival storage, ensuring compatibility with your LMS or application.

Is there a difference between tts-1 and tts-1-hd?

Both models use the same engine and have the same price. The only difference is the model identifier you send in the request. You can use either tts-1 or tts-1-hd without affecting the cost or the audio quality delivered to your application.

How do I get the list of available voices?

Make a GET request to /v1/voices. This endpoint returns details on available voices, languages, formats, and price. You can use this information to select the appropriate voice preset, such as aria or nova, for your specific content needs before generating the audio files.

Can I change the speed of the audio?

Yes, you can adjust the speed between 0.25 and 4.0 using the speed parameter. This allows you to slow down narration for clarity or speed it up for quick reviews.

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 content exceeds this, you must split the text into multiple requests. This limit ensures efficient processing and consistent generation times for your audio synthesis tasks.

How long does it take to generate audio?

Generation is roughly real-time, averaging 25 characters of text per second. Short phrases may take a few seconds, while longer texts process sequentially. Under load, requests may wait in a queue, so plan your integration accordingly to handle potential delays during peak usage periods.

Do I need a WebSocket for streaming audio?

No. The API returns the complete audio file in the response body. There is no streaming or WebSocket support. You receive the full file once generation is complete, which simplifies integration for standard LMS and web applications that do not require real-time partial audio delivery.

First request

curl

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

Authenticate requests by including your API key in the HTTP header as a Bearer token. This single key authorizes all endpoints and tracks your usage against your account balance.

Bearer Token Authorization

Bearer Token Authorization

Include the header Authorization: Bearer tts-... with every API call. The system validates this token to ensure requests are permitted and charges your balance correctly.

One Active Key Per Account

One Active Key Per Account

Each account maintains only one active key at a time. This simplifies integration for LMS plugins and automated workflows by removing the need to manage multiple credential sets.

Key Rotation Process

You can issue a new key from your dashboard at any time. The old key becomes invalid immediately, ensuring that lost or compromised credentials cannot be used for further generation.

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

Generate audio from text using a simple HTTP POST request. Replace <YOUR_API_KEY> with your key from the dashboard. The API accepts JSON input and returns the synthesized speech file directly in the response body.

This endpoint handles the core synthesis task. Ensure your input text does not exceed 4096 characters. For longer content, split the text into smaller chunks and concatenate the resulting audio files later in your workflow.

Basic Speech Request

Send a POST request to the speech endpoint. Include your Bearer token in the Authorization header. The request body must contain the model, input text, voice selection, and desired audio format.

Use this structure for immediate integration. The API processes requests sequentially, so under heavy load, you may experience slight delays. Typical generation speed is roughly real-time, producing about 25 characters of text per second of audio.

  • Endpoint: POST https://api.xsmbthu7.info/v1/audio/speech
  • Header: Authorization: Bearer <YOUR_API_KEY>
  • Content-Type: application/json

JSON Body Structure

The request body is a JSON object with specific required fields. The input field holds the text to convert, limited to 4096 characters. Spaces and punctuation count toward this limit. Set the voice to one of the eight available presets, such as aria or felix.

Optional fields include response_format, speed, and language. If you omit the language parameter, the system guesses it from the script, defaulting to English for Latin text. For Hindi or other specific languages, explicitly set the language code to ensure accurate pronunciation.

  • model: "tts-1" or "tts-1-hd"
  • input: string, max 4096 chars
  • voice: e.g., "aria", "nova"
  • response_format: "mp3", "wav", "opus"
  • speed: 0.25 to 4.0
  • language: optional ISO code

Response Format

On success, the API returns the audio file directly in the response body with the specified Content-Type. The HTTP status code will be 200 OK. You can save this binary data directly to a file on your server.

If the request fails, the response will contain a JSON error object with a message and status code. Failed requests are free, and any charged amount is returned in full. Check the status code to determine if synthesis completed successfully or if an error occurred.

Using OpenAI SDK

Sound wave illustration for: Using OpenAI SDK

The CourseCast API is fully compatible with the official OpenAI SDKs. You do not need a custom client library; simply adjust the connection endpoint to point to our infrastructure.

Change Base URL

Initialize your OpenAI client by setting the base_url parameter to https://api.xsmbthu7.info/v1. This directs all requests to our TTS endpoints while keeping the standard authentication logic intact.

Same Request Shape

The JSON body structure for POST /v1/audio/speech remains identical to the OpenAI standard. Pass your model, input, voice, and response_format exactly as you would for native OpenAI audio generation.

Official SDK Compatibility

Because the request schema matches the OpenAI specification, you can use the official Python, Node.js, or Go SDKs without modification. This ensures a reliable, standard integration for your LMS automation workflows.

  • Supports Python, Node.js, Go, and other official SDKs
  • No custom client library required
  • Standard POST request structure

Endpoints and Parameters

Sound wave illustration for: Endpoints and Parameters

The API exposes three primary endpoints for generating speech and managing resources. The core generation happens via POST, while GET endpoints provide metadata about available voices and model configurations.

POST /v1/audio/speech

Send text to receive an audio file. The JSON body requires model, input, voice, response_format, and optional speed or language. The input field accepts up to 4096 characters. Authentication uses a Bearer token.

  • Required fields: model, input, voice, response_format
  • Optional: speed (0.25–4.0), language (ISO code)

GET /v1/voices

Returns a list of the 8 available voice presets with their attributes. This endpoint helps you select the appropriate voice for your LMS content, such as aria for narrations or felix for promos.

  • Lists all 8 voice presets
  • Includes voice metadata and supported languages

GET /v1/models

Returns the available models: tts-1 and tts-1-hd. Both models use the same engine and price point, allowing you to choose based on preference without cost differences.

  • Returns tts-1 and tts-1-hd
  • Both models share identical pricing

Supported Formats and Models

Sound wave illustration for: Supported Formats and Models

The API supports five standard audio formats to suit different LMS and accessibility needs. You can choose between MP3, WAV, OPUS, FLAC, or PCM. Each format serves a specific use case, from web-friendly compression to high-fidelity archival storage.

Both tts-1 and tts-1-hd models use the exact same underlying engine. This means switching between them changes only the model identifier, not the voice quality or generation speed. The price remains identical for both models, simplifying your cost calculations.

MP3, WAV, OPUS, FLAC, PCM

Select the format that best fits your integration. MP3 and OPUS offer smaller file sizes for web delivery, while WAV and FLAC provide lossless quality for archival purposes. PCM is available for raw audio processing needs.

  • MP3: Compressed, widely supported
  • WAV: Lossless, uncompressed
  • OPUS: Efficient compression
  • FLAC: Lossless compression
  • PCM: Raw audio data

tts-1 and tts-1-hd Models

Both model identifiers point to the same synthesis engine. There is no quality difference in the voice output. This allows you to standardize your model version without worrying about feature gaps.

  • Identical engine performance
  • No quality difference
  • Simple model switching

Equal Engine and Price

Since both models use the same engine, they cost exactly the same: $0.01 per 1,000 characters. You can choose the model ID based on your preference or existing code structure without affecting your billing or generation speed.

  • Same price per character
  • Same generation speed
  • Same voice presets available
Supported Formats and Models

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Rate limits protect the stability of the audio generation engine. Your API key allows up to 60 requests per minute once your account is active. Each request consumes characters from your balance, so high-volume LMS content generation requires careful batching.

60 Requests per Minute

Each API call counts toward this limit. If you exceed 60 requests in a single minute, the API returns a 429 Too Many Requests error. Plan your automated narration workflows to stay within this threshold, especially when processing large course libraries.

  • Limit: 60 requests/minute per key
  • Applies to all /v1/audio/speech calls
  • Exceeding returns HTTP 429

10 Requests Before Top-up

New accounts start with a lower limit of 10 requests per minute. This applies until you add funds. Once you top up via USDT (TRC-20), the limit increases to the full 60 requests per minute immediately.

  • Initial limit: 10 requests/minute
  • Increases to 60 after first top-up
  • No subscription required to upgrade

Queue Handling on Load

During high demand, requests may wait in a queue before processing begins. This can increase generation time, especially for longer texts. Short phrases typically take a few seconds, while long texts generate at roughly real-time speed.

  • Requests are processed sequentially under load
  • Waiting times vary based on queue length
  • Use retries with exponential backoff for robustness

Handling Long Texts

Sound wave illustration for: Handling Long Texts

When your course script exceeds 4096 characters, you must split the text into chunks of that size before sending requests. Each chunk generates a separate audio file. This ensures the API processes each segment efficiently without truncation.

4096 Character Split

Divide your lesson content into segments, ensuring each is under the 4096-character limit. Spaces and punctuation count toward this limit. Send each segment as a separate POST request to the /v1/audio/speech endpoint.

  • Split text at natural breaks (sentences or paragraphs) where possible.
  • Count all characters, including spaces and punctuation.
  • Maintain the same voice and model parameters for all chunks.

Join Audio Files

After receiving the audio files for each chunk, concatenate them in the correct order. Since requests are processed sequentially, the output files will naturally follow the order of your requests. Use a standard audio library or CLI tool to merge the MP3, WAV, or OPUS files into a single lecture file.

Real-Time Speed Estimate

Generation takes roughly one second of audio per 25 characters of text. For long lectures, this means processing time scales linearly with length. Under load, requests may queue, so plan your automation to handle delays gracefully without timing out prematurely.

Error Codes and Responses

Sound wave illustration for: Error Codes and Responses

The API returns standard HTTP status codes to indicate request outcomes. Use these codes to determine whether your integration needs immediate retry logic or if the issue requires user attention or input correction.

Understanding these responses ensures smooth automation for your LMS content generation workflows without unnecessary delays or wasted credits.

Common HTTP Errors

Errors fall into four categories. 400 Bad Request means invalid JSON, missing fields, or an invalid voice. 401 Unauthorized indicates an expired or incorrect API key. 429 Too Many Requests triggers when you exceed 60 requests per minute. 500 Internal Server Errors are rare but may occur during peak load.

  • 400: Check payload structure and character limits.
  • 401: Verify your Bearer token in the Authorization header.
  • 429: Wait or reduce request frequency.
  • 500: Retry after a short delay.

Failed Request Refunds

If synthesis fails due to server errors or invalid inputs that prevent generation, the charge is returned in full to your balance. You will not be billed for characters consumed during a failed attempt. This ensures you only pay for successfully generated audio files.

Check your dashboard balance after a failure to confirm the refund appears automatically within minutes.

Debugging Tips

Start by verifying your JSON structure matches the OpenAI speech endpoint schema. Ensure your API key is correctly formatted with the 'tts-' prefix. Check that the voice name exists in the /v1/voices endpoint response.

If a request hangs, consider that long texts may queue under load. Use the /v1/models endpoint to confirm model availability before bulk generation.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This pay-as-you-go structure allows edtech teams to scale audio generation up or down without committing to a fixed budget.

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. ISO 639 language codes
  4. LibriTTS-R corpus (OpenSLR 141)
  5. MDN: Web Speech API
  6. OpenAI API reference: create speech
  7. TRON developer hub: TRC-20
  8. openai-python on GitHub
  9. Python documentation
  10. curl documentation
  11. FFmpeg documentation
  12. Tether (USDT)

More on this site