API Documentation for Course Audio Generation

By Voicera editorial team · Updated 2026-11-18

This documentation guides course creators and LMS administrators through integrating Voicera’s text-to-speech API to convert lesson scripts into natural audio files. You will learn how to authenticate, structure requests, and manage character limits for educational content generation without requiring complex studio setups or expensive voice actors.

We cover practical integration steps using cURL and the OpenAI SDK, detailing supported formats like MP3 and WAV, rate limits, and error handling. The guide includes specific parameters for our eight preset voices and two models, ensuring you can efficiently produce high-quality audio for online courses directly within your existing workflows.

API Documentation for Course Audio Generation

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playe19.com/v1. You send POST requests to /v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available under this base URL. Use this URL when configuring your HTTP client or SDK to ensure requests reach the correct service endpoint for your account.

Does the API support the OpenAI Python SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.playe19.com/v1 and using your site's key. The request shape matches the OpenAI speech endpoint. This allows you to use familiar libraries without writing custom HTTP code, making integration into your LMS or course platform straightforward.

How do I handle rate limits in my LMS?

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 or simple retry logic in your LMS integration to handle temporary delays during high-volume lesson generation.

Can I send text longer than 4096 characters?

Yes, but you must split the text into parts of up to 4096 characters per request. Generate audio for each part, then join the resulting audio files. This manual splitting is required because the API accepts a maximum of 4096 characters in a single input field for each synthesis call.

Which audio format is best for web players?

MP3 is generally best for web players due to broad compatibility and reasonable file size. You can also use WAV, OPUS, FLAC, or PCM via the response_format field. MP3 offers a good balance of quality and bandwidth efficiency for audio lessons in most modern LMS environments.

Is there a limit on the number of API keys?

There is one active key per account. You can issue a new key at any time, which immediately stops the old one. This ensures simple security management for your LMS integrations without needing to track multiple active credentials simultaneously, reducing the risk of accidental exposure of your billing key.

How do I detect the language automatically?

If you do not set the language parameter, the API guesses it from the script. Latin script text defaults to English. For non-English Latin-script text, you should explicitly set the language parameter to ensure accurate pronunciation. The API supports 23 specific languages, including Arabic, Chinese, and Spanish.

Do I need to install a specific SDK?

No, you do not need a specific SDK. You can use the OpenAI SDK by adjusting the base URL, or use plain HTTP requests. There is no official custom SDK, mobile SDK, or WordPress plugin. Standard HTTP libraries in your preferred language are sufficient for all integrations.

What happens if the server is busy?

Requests are processed one after another, so under load, a request may wait in a queue. Typical speed is roughly real time for long texts. Short phrases take a few seconds. If the server is busy, your request will simply queue until processing begins, without immediate failure.

Are the API endpoints RESTful?

Yes, the endpoints follow RESTful conventions. Use POST for /v1/audio/speech to generate audio. Use GET for /v1/voices to list available voices, languages, and formats, and GET for /v1/models. This standard structure allows easy integration with most LMS platforms and programming languages that support standard HTTP methods.

Can I stream the audio directly?

No, there is no streaming, WebSocket, or real-time partial audio support. The API returns the complete audio file in the response after synthesis is finished. You must wait for the full file to be generated before playing it in your LMS or application, which may add latency for long texts.

How do I renew my API key?

You can issue a new key at any time from your account dashboard. When a new key is issued, the old one stops working immediately. This is done via the /get-api-key/ page on the site. You do not need to wait for expiration; you can rotate keys as needed.

Is the API key shared across devices?

Yes, the single active API key works across all devices and integrations using that account. Since there is only one key per account, any device or LMS instance using that key shares the same rate limits and billing balance. Ensure you secure the key if multiple devices access it.

What is the difference between tts-1 and tts-1-hd?

Both models use the same engine and have the same price. The difference is in the engine, with tts-1-hd using the HD engine. Both accept the same parameters and support the same voices and formats. Choose tts-1-hd if you prioritize audio quality for your course content, as the cost remains identical.

First request

curl

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

Getting Your API Key

Sound wave illustration for: Getting Your API Key

Access the /get-api-key/ page on playe19.com to create your account. You can sign in securely using your Google account or register with an email and password. This step establishes your unique identifier for the Voicera API.

Sign Up via Google or Email

Google sign-in provides immediate access, including a $0.50 trial credit valid for 7 days. Email-based accounts start without this trial credit but function identically for API usage.

  • Google sign-in includes $0.50 trial credit
  • Email sign-up has no trial credit
  • Accounts are specific to playe19.com

Retrieve Key from Dashboard

Once registered, the dashboard displays your active API key starting with tts-. You can also view your current balance, characters remaining, and a ready-to-use cURL example directly on this page.

Regenerate Key if Needed

You can issue a new API key at any time. The new key becomes active immediately, and the previous key stops working at once, ensuring secure access management for your course audio pipeline.

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

Generate course audio files instantly using standard HTTP requests. The API accepts plain text and returns synthesized speech in your preferred format. This method requires no external SDKs, making it ideal for simple scripts or quick testing environments.

Use the provided cURL command to send your lesson script to the endpoint. Ensure you replace the placeholder key with your actual credentials from the dashboard. The response contains the binary audio data ready for playback.

Basic POST Request Structure

Send a POST request to the speech endpoint with your text in the input field. The request body must be valid JSON containing the model, voice, and text parameters. The system processes the text and returns the audio file directly in the response body.

Headers and Authentication

Include your API key in the Authorization header using the Bearer scheme. This key is unique to your account and grants access to the generation engine. Without a valid key, the server rejects the request immediately.

Use the Content-Type: application/json header to specify the request format. This ensures the server correctly interprets your text and voice selection parameters without parsing errors.

Parsing JSON Response

The API returns the audio file directly as binary data, not as a JSON object. Save the response body to a file with the appropriate extension, such as .mp3 or .wav. Check the HTTP status code to confirm success.

If the request fails, the response contains a JSON error object with a code and message. Common errors include invalid keys or exceeding rate limits. Log these codes to troubleshoot integration issues quickly.

Quickstart with cURL

Using OpenAI SDK

Sound wave illustration for: Using OpenAI SDK

The Voicera TTS API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDK integrations with minimal changes. By adjusting the base URL to point to the Voicera API, you can leverage the official OpenAI libraries to handle authentication and request formatting seamlessly.

This approach ensures that your current codebase remains stable while accessing Voicera’s specific voice models and pricing. You only need to update the configuration to direct traffic to the correct endpoint, maintaining your preferred programming language and SDK version.

Change Base URL Configuration

Update your SDK client’s base_url property to https://api.playe19.com/v1. This redirects all subsequent API calls to Voicera’s infrastructure without altering your authentication logic or request payload structure.

Ensure your API key is passed via the standard Authorization: Bearer header. The SDK handles the header formatting automatically, so no additional configuration is required beyond the URL change.

  • Set base_url to https://api.playe19.com/v1
  • Keep existing Authorization header format
  • No SDK version changes needed

Use Official Speech Endpoint

Invoke the standard /v1/audio/speech endpoint using the Speech.create() method (or equivalent in your SDK). Pass the model, input, voice, and response_format parameters exactly as you would for OpenAI.

The API accepts the same JSON body structure, ensuring that your existing request logic for text input and voice selection works immediately without modification.

  • Use /v1/audio/speech endpoint
  • Send standard JSON body
  • Supports tts-1 and tts-1-hd models

Keep Existing Code Structure

Your existing code for handling the response remains valid. The API returns audio data in the specified format (e.g., MP3, WAV) within the response body.

You can continue to use your current error handling and logging mechanisms. Since the request shape is identical, any existing validation for parameters like speed or voice will continue to work as expected.

  • Reuse existing response parsing logic
  • Maintain current error handling
  • No code refactoring required

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

Selecting the correct output format ensures your audio files integrate smoothly with your Learning Management System (LMS) or course platform. The API supports MP3, WAV, FLAC, and OPUS, allowing you to balance file size against quality requirements for different educational contexts.

MP3 for Web Players

MP3 is the standard for web-based audio players due to its small file size and universal compatibility. Use this format for lessons embedded in course pages to ensure fast loading times on mobile devices and standard browsers.

  • Small file size reduces bandwidth usage
  • Universal support across all modern LMS platforms
  • Ideal for playback in course modules

WAV for High Quality

WAV provides uncompressed, high-fidelity audio suitable for professional-grade course materials or downloadable resources. This format preserves the full quality of the generated speech without data loss, making it ideal for listeners who require clear, crisp audio.

  • Uncompressed, lossless quality
  • Best for downloadable course assets
  • Preserves full audio fidelity

FLAC for Lossless Archiving

FLAC offers lossless compression, retaining 100% of the audio data while reducing file size compared to WAV. This is optimal for long-form educational content where you want to save storage space without sacrificing any audio quality.

  • Lossless compression for smaller files
  • Perfect for archival storage
  • Maintains original audio integrity

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Rate limits protect the API’s stability during high-volume course production. Each API key allows 60 requests per minute once funded. This limit applies per key, so multiple keys can increase throughput if needed.

60 Requests Per Minute

After topping up, you can send up to 60 synthesis requests per minute. This handles most LMS batch uploads efficiently.

10 Requests Before Top-Up

New accounts start with a lower limit of 10 requests per minute. This ensures fair usage during the free trial or before your first USDT top-up.

Queued Processing Under Load

Requests are processed sequentially. If the queue is full, new requests wait briefly. Long texts take longer to generate, so plan your upload schedule accordingly to avoid delays.

Rate Limits and Quotas

Handling Long Text Inputs

Sound wave illustration for: Handling Long Text Inputs

The API enforces a strict 4096-character limit per request, counting all spaces and punctuation. This constraint ensures consistent processing times and prevents timeouts during synthesis. For longer lesson scripts or detailed course modules, you must divide the text into smaller chunks that fit within this boundary before sending them to the endpoint.

To handle texts exceeding this limit, split your script programmatically using character count logic. Ensure each chunk is a complete sentence or logical phrase to avoid audio discontinuities. The API processes these requests sequentially, so efficient splitting helps maintain a smooth workflow without unnecessary waiting.

4096 Character Limit Per Request

Each API call accepts a maximum of 4096 input characters. This limit applies to the input field in the JSON body. Spaces, punctuation, and special characters are all counted toward this total. Exceeding this limit will result in an error, so validate your text length before submission.

This constraint allows for predictable processing times. Typical generation speed is roughly real-time, meaning longer texts naturally take longer to synthesize. By respecting the character limit, you avoid unexpected failures and ensure each segment is processed efficiently by the engine.

  • Count all characters including spaces and punctuation
  • Validate length before sending to the endpoint
  • Prevents processing timeouts and errors

Split Text Programmatically

Split your lesson script into chunks of up to 4096 characters. Use a simple script to divide the text at sentence boundaries or logical breaks. This ensures each audio segment is coherent and easy to stitch together later. You can use the input field to pass each chunk individually.

Maintain consistent voice and speed settings across all splits. This ensures seamless audio playback when the segments are joined. The API does not store state between requests, so you must manage the splitting logic in your own application. Each split is a separate API call.

  • Divide text at logical breaks
  • Maintain consistent voice and speed
  • Manage splitting in your application

Join Audio Files Sequentially

After receiving audio files for each chunk, join them sequentially to create the final lesson audio. Use standard audio processing libraries or tools to concatenate the files. Ensure the format matches (e.g., all MP3 or all WAV) to avoid compatibility issues during merging.

This approach allows you to handle long course content without hitting character limits. The resulting audio file will play continuously, providing a natural listening experience for students. Verify the total duration and quality before distributing the final file to your LMS.

  • Concatenate audio files in order
  • Ensure format consistency
  • Verify final audio quality

Error Codes and Handling

Sound wave illustration for: Error Codes and Handling

When integrating Voicera into your LMS, handling API responses correctly ensures smooth audio generation workflows. Errors typically stem from authentication issues, rate limits, or invalid parameters. Understanding these responses helps you debug integration problems quickly without disrupting your course delivery.

Each error type includes a specific status code and message. You should implement retry logic for temporary issues like rate limits and validate inputs before sending requests to avoid unnecessary charges.

Authentication Errors

If your API key is missing, expired, or incorrect, the API returns a 401 Unauthorized error. Ensure you pass the key in the Authorization: Bearer tts-... header. Regenerate your key in the dashboard if it stops working.

Failed authentication prevents any audio generation. Check that you are using the correct key from your account dashboard and that it hasn’t been replaced by a new issuance.

  • Status 401: Invalid or missing Bearer token.
  • Solution: Retrieve a fresh key from /get-api-key/.

Rate Limit Exceeded

Voicera enforces a limit of 60 requests per minute per key. If you exceed this, you receive a 429 Too Many Requests error. Before your first top-up, the limit is 10 requests per minute.

Under heavy load, requests may also queue. Implement exponential backoff in your integration to handle retries gracefully without overwhelming the API.

  • Status 429: Rate limit exceeded.
  • Limit: 60 req/min (10 before top-up).
  • Action: Wait and retry with backoff.

Invalid Voice Selection

If you specify a voice that does not exist or is incompatible with the selected language, the API returns a 400 Bad Request error. Ensure the voice parameter matches one of the eight presets.

Check the GET /v1/voices endpoint to verify available voices and their supported languages. Incorrect language codes can also cause failures if the voice cannot render the text.

  • Status 400: Invalid voice or language.
  • Voice: aria, nova, luna, sage, felix, milo, atlas, orion.
  • Fix: Use valid voice names and ISO language codes.
Error Codes and Handling

Voice and Model Details

Sound wave illustration for: Voice and Model Details

The API offers two model identifiers, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing structure. Selecting either model provides identical character consumption rates, allowing you to switch without changing your billing logic. Both models support the full range of eight voice presets and all supported languages.

Each voice preset is derived from licensed recordings or public domain audiobooks, ensuring a consistent, professional tone suitable for educational content. The system automatically detects the language from the script if not explicitly defined, though specifying the ISO code is recommended for non-English Latin texts to prevent misidentification.

Two Models: tts-1 and tts-1-hd

Both model identifiers use the same engine and price: $0.01 per 1,000 characters. Choose either for identical output quality and billing behavior.

Eight Preset Voices

Voices include female presets like aria (warm narrator) and nova (bright), and male presets like atlas (neutral news) and orion (deep documentary). All voices support all 23 listed languages.

  • aria: warm, clear narrator
  • nova: bright, upbeat
  • luna: soft, storytelling
  • sage: calm, instructional
  • felix: energetic, promo
  • milo: friendly, conversational
  • atlas: neutral, news
  • orion: deep, documentary

Language Code Parameters

Pass an optional ISO language code to force specific pronunciation. If omitted, the system guesses from the script, defaulting to English for Latin text.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Launch your own courses and manage students easily with our intuitive platform.

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. Tether (USDT)
  3. curl documentation
  4. openai-python on GitHub
  5. MDN: Web Speech API
  6. Python documentation
  7. LibriTTS-R corpus (OpenSLR 141)
  8. FFmpeg documentation
  9. TRON developer hub: TRC-20
  10. IETF RFC 7845: Ogg Opus
  11. W3C WAI: making audio and video accessible
  12. ISO 639 language codes

More on this site