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.mp3Python (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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
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
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 charsvoice: e.g., "aria", "nova"response_format: "mp3", "wav", "opus"speed: 0.25 to 4.0language: 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
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
POSTrequest structure
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
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

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
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
voiceandmodelparameters 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
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.
23 languages
Any voice speaks any of these languages.
