Frequently asked questions
How do I get an API key?
Sign up on /get-api-key/ using Google or email. Accounts are per site. The dashboard displays your active key, balance, and usage metrics. You can issue a new key at any time; the old one stops immediately. Failed requests are free, and a $0.50 trial credit is available for Google sign-ins.
What is the base URL?
The API base URL is https://api.shweohh.info/v1. Use this for all requests, including POST /v1/audio/speech, GET /v1/voices, and GET /v1/models. Ensure your Authorization header uses the Bearer token format with your specific API key for authentication.
Can I use the OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint. Change the SDK's base_url to https://api.shweohh.info/v1 and use your CourseVoice key. The official OpenAI SDKs work directly without modification, allowing you to leverage existing integration code for your LMS.
What formats are supported?
Supported response formats are mp3, wav, opus, flac, and pcm. Specify the desired format in the request body. Each generated file includes an inaudible watermark marking it as synthetic speech. These formats ensure compatibility with most e-learning platforms and audio players.
How do I set the language?
Pass an optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting Latin text to English. For non-English Latin text, explicitly set the language to ensure accurate synthesis across the 23 supported languages.
What is the character limit?
Each request supports up to 4096 characters of input text. For longer texts, split them into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit, which is used for billing calculations.
Can I change the speed?
Yes, adjust the speed between 0.25 and 4.0. This allows you to control the pacing of the synthetic voice audio. The default speed is typically real-time, generating about 25 characters per second for long texts, though short phrases may take longer.
How do I handle rate limits?
The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load, a request may wait in a queue. Implement exponential backoff in your LMS integration to handle temporary delays.
Is the API synchronous?
Yes, the API is synchronous. You send a POST request and receive the audio file in the response. Requests are processed one after another, so under load, you may experience delays. There is no streaming or WebSocket support for partial audio.
What is the response format?
The response contains the generated audio file in the requested format (mp3, wav, opus, flac, or pcm). Failed requests return a response without charge. The audio file includes an inaudible watermark indicating it is synthetic speech, ensuring transparency for your users.
How do I revoke my key?
Issue a new API key from the dashboard. The old key stops working immediately. You can generate a new key at any time. This allows you to revoke access instantly without waiting for a manual review or expiration period.
Can I use multiple keys?
No, each account holds exactly one active key. Each key has a rate limit of 60 requests per minute. This allows you to distribute load across different services or environments within your LMS infrastructure, managing quotas independently.
What happens on timeout?
If synthesis fails, the charge is returned in full. The API is synchronous, so you wait for the result. If the request exceeds the queue time, it may fail, but you will not be billed for the characters processed. Check your dashboard for status.
Is SSML supported?
No, SSML is not supported. The API accepts plain text input up to 4096 characters. There are no phoneme dictionaries, custom pronunciation lexicons, or emotion tags. You control pacing via the speed parameter and voice selection for tone adjustments.
First request
curl
curl https://api.shweohh.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.shweohh.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.shweohh.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
Authenticate requests with an HTTP Bearer token in the Authorization header. This single key grants access to all endpoints and tracks your usage against your account balance.
Bearer token
Include Authorization: Bearer tts-... in every request. The key identifies your account for billing and rate limit enforcement.
One key per account
Each account holds exactly one active key. Issuing a new key immediately invalidates the previous one, ensuring only one active credential exists at any time.
Revoke key
To revoke, generate a new key via your dashboard. The old key stops working immediately, securing your API access without downtime for new integrations.
Endpoint Details
The API exposes three primary endpoints for generating and managing speech assets within your LMS infrastructure. Use the speech endpoint to convert text into audio, the voices endpoint to discover available presets, and the models endpoint to verify current engine configurations.
These endpoints allow your backend to dynamically fetch voice options and manage model versions without hardcoding constants. This structure supports automated course generation pipelines where audio assets are created on-demand based on user progress or content updates.
Speech endpoint
POST to /v1/audio/speech accepts a JSON body containing the text, voice, and format preferences. The endpoint returns the generated audio file directly in the response body. It processes requests sequentially, so high-volume courses may experience queuing during peak usage periods.
Ensure your LMS handles the response stream efficiently, as the audio is delivered as a single file per request. For texts exceeding 4096 characters, split the input and join the resulting audio files in your application logic.
- Endpoint: POST /v1/audio/speech
- Returns: Audio file in specified format
- Max input: 4096 characters per request
Voices endpoint
GET /v1/voices returns a list of all available voice presets, their associated languages, and supported output formats. This endpoint is essential for dynamically populating voice selection dropdowns in your course authoring interface.
The response includes metadata such as voice name (e.g., aria, nova) and language codes. Use this data to map user preferences to the correct voice parameter in speech requests.
- Endpoint: GET /v1/voices
- Returns: Voice list with languages and formats
- Supports: 23 languages across 8 presets
Models endpoint
GET /v1/models returns the available model identifiers, currently tts-1 and tts-1-hd. Both models use the same underlying engine and pricing, allowing you to switch between them based on quality needs without changing pricing logic.
This endpoint ensures your integration remains compatible if new models are added in the future. Always verify the model ID before sending speech requests to avoid compatibility issues.
- Endpoint: GET /v1/models
- Returns: Model IDs (tts-1, tts-1-hd)
- Same engine and price for both
Request Parameters
The API accepts plain text input for synthesis, supporting a maximum of 4096 characters per request. This limit applies to the entire string, including spaces and punctuation. For longer course content, split the text into chunks and join the resulting audio files.
The input is processed sequentially. If the text exceeds the limit, ensure your integration handles splitting logic before sending individual requests to the endpoint.
Input text
Send the text content directly in the input field of the JSON body. The engine supports up to 4096 characters per request. Characters include all spaces and punctuation marks. Longer narratives should be split into segments and concatenated by your application.
The language is auto-detected from the script. For Latin-script text that is not English, explicitly set the language field to ensure correct pronunciation. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
- Maximum length: 4096 characters per request
- Includes spaces and punctuation in character count
- Auto-detects language from script
- Set
languageexplicitly for non-English Latin text - Supports 23 languages total
Voice selection
Choose from 8 presets: Aria, Nova, Luna, Sage (female) and Felix, Milo, Atlas, Orion (male). Each voice has a distinct tone, from warm narration to deep documentary styles. Use the /v1/voices endpoint to retrieve the exact voice IDs for your integration.
All voices can speak any of the 23 supported languages. The voice choice remains consistent across segments if you split long texts. This ensures a uniform listening experience for your LMS users.
- 8 distinct voice presets available
- Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion
- All voices support all 23 languages
- Retrieable via GET /v1/voices
- Consistent tone across split segments
Speed control
Adjust the speech rate using the speed parameter, which accepts values between 0.25 and 4.0. The default speed is 1.0. Faster speeds can reduce processing time for short phrases, while slower speeds may improve clarity for complex instructional content.
The engine processes requests sequentially. Adjusting speed does not affect the queue position but changes the generation duration. Typical generation speed is roughly real-time, producing about 25 characters of text per second.
- Range: 0.25 to 4.0
- Default speed: 1.0
- Adjustable per request
- Affects generation duration
- Does not change queue position
Response Formats
The API returns generated audio in multiple formats, allowing your LMS to optimize playback based on the user’s device and network conditions. Each response includes the audio binary data along with standard HTTP headers indicating the content type.
MP3 output
MP3 is a supported format. It is widely supported across all modern browsers and mobile devices, making it ideal for general course playback.
WAV output
WAV provides uncompressed PCM audio. Use this format when precise audio quality is required or when downstream processing tools prefer raw audio data.
OPUS output
OPUS is a supported format. It is particularly effective for mobile learners where data conservation is a priority.
OpenAI SDK Integration
Developers can reuse existing OpenAI client libraries by simply redirecting the base URL to our API endpoint. This allows seamless integration into LMS platforms that already support standard TTS workflows without requiring custom HTTP clients or complex authentication handlers.
Base URL change
Set the base_url configuration to https://api.shweohh.info/v1. The request shape matches the OpenAI speech endpoint exactly, so no parameter mapping is required.
- Base URL: https://api.shweohh.info/v1
- Endpoint: /v1/audio/speech
- Auth: Bearer token in header
SDK compatibility
The API accepts standard parameters like model, voice, and input. Official OpenAI SDKs work out-of-the-box after the URL adjustment. Ensure your SDK version supports the audio/speech endpoint structure.
- Compatible with standard OpenAI SDKs
- Supports JSON request bodies
- Standard Bearer token authentication
Code example
Initialize the client with the new base URL and pass your course text to the speech endpoint. The response returns the audio file directly for playback or storage in your LMS.
- client = OpenAI(base_url="https://api.shweohh.info/v1", api_key="tts-...")
- audio = client.audio.speech.create(model="tts-1", voice="nova", input="Lesson 1: Introduction")
- with open('lesson.mp3', 'wb') as f: f.write(audio.content)

Curl Example
Use curl to test the API directly from your terminal. This method bypasses SDK overhead and helps verify network connectivity before full integration.
The request sends your text payload to the speech endpoint. The API returns the audio file directly in the response body.
Basic request
Send a POST request to the speech endpoint. Replace YOUR_API_KEY with your token from /get-api-key/.
The request body includes the model, input text, and voice selection.
Headers
Include the Authorization header with your Bearer token. Ensure the content type is set to application/json.
JSON body
The JSON body defines the synthesis parameters. Use tts-1 or tts-1-hd for the model. Specify voice and input text. Limit text to 4096 characters.
model: "tts-1" or "tts-1-hd"voice: e.g., "aria", "nova"input: "Your course content here"response_format: "mp3"
Rate Limits
The API enforces a standard rate limit of 60 requests per minute per key. This limit applies to all synthesis endpoints and ensures fair usage across your LMS infrastructure. Monitor your usage via the dashboard to stay within these bounds.
60 requests per minute
Each API key is allowed 60 requests per minute.
Initial limit
New accounts without a top-up start with a lower limit of 10 requests per minute. This initial threshold allows you to test integration before scaling up with a minimum $5 USDT top-up.
Queue handling
Requests are processed sequentially. Under high load, requests may wait in a queue. Expect roughly real-time generation speed, meaning long texts will take time proportional to their length. Short phrases typically take a few seconds.
Error Handling
Errors indicate request status. Failed synthesis returns zero charge and refunds the character count immediately.
4xx errors
Client errors include invalid keys, malformed JSON, or exceeding the 4096-character input limit. Verify your bearer token and request body structure before retrying.
- 401 Unauthorized: Invalid or expired API key
- 400 Bad Request: Invalid parameters or input length
- 429 Too Many Requests: Exceeded rate limits
5xx errors
Server errors (500–503) occur during temporary processing failures. These do not consume your balance. The system guarantees a full refund for failed requests.
Retry logic
Implement exponential backoff for 429 and 5xx responses. Since requests process sequentially under load, short delays prevent queue saturation. Retries succeed once capacity is available.
- Use exponential backoff for 429 and 5xx errors
- Immediate retry is safe for 400 errors
- Failed requests are always refunded
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. You only pay for what you use, with no monthly minimums or seats to manage.
23 languages
Any voice speaks any of these languages.
