Integrate Text-to-Speech API for Learning Management Systems

By CourseVoice editorial team · Updated 2026-11-19

This documentation provides the technical reference for integrating CourseVoice API into LMS and e-learning platforms. It covers the single POST /v1/audio/speech endpoint, parameter configuration for voice and speed, and the GET /v1/voices endpoint for available presets. You will find exact request shapes, response formats, and authentication details required to generate synthetic audio for course content.

The guide is designed for engineering teams building course engines. It includes OpenAI SDK compatibility instructions, allowing you to swap the base URL and use existing client libraries. You will also find curl examples, rate limit specifications (60 req/min), and error handling strategies to ensure reliable audio generation during high-volume course publishing workflows.

Integrate Text-to-Speech API for Learning Management Systems

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.mp3

Python (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
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 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

Bearer token

Include Authorization: Bearer tts-... in every request. The key identifies your account for billing and rate limit enforcement.

One key per account

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

Sound wave illustration for: 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

Sound wave illustration for: 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 language explicitly 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

Sound wave illustration for: 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

Sound wave illustration for: 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)
OpenAI SDK Integration

Curl Example

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. curl documentation
  3. ISO 639 language codes
  4. openai-node on GitHub
  5. LibriTTS-R corpus (OpenSLR 141)
  6. Python documentation
  7. Tether (USDT)
  8. Node.js documentation
  9. TRON developer hub: TRC-20
  10. MDN: Web Speech API
  11. IETF RFC 7845: Ogg Opus
  12. LibriTTS-R paper (arXiv 2305.18802)

More on this site