Python TTS API Documentation for Developers

By LectioLab editorial team · Updated 2026-11-19

This documentation provides the technical reference for integrating LectioLab’s text-to-speech API into your Python workflows. It covers authentication, endpoint specifications, and request parameters for generating audio from course materials. The guide is designed for developers and technical methodologists who need to automate the conversion of educational content into MP3 or WAV files.

You will find concrete examples for using the OpenAI SDK with our custom base URL, handling rate limits, and processing long texts. This page assumes familiarity with standard HTTP requests and Python libraries. It focuses on the engineering details required to reliably generate synthetic speech for LMS integration without unnecessary abstraction.

Python TTS API Documentation for Developers

Frequently asked questions

How do I install the Python SDK?

Install the official OpenAI Python library via pip: pip install openai. This library supports our API endpoints directly by changing the base_url. No proprietary SDK is required for Python integration. The standard library handles JSON serialization and HTTP requests efficiently, allowing you to generate audio files with minimal code overhead for your course materials.

What is the base_url for the API?

The API base URL is https://api.788t.info/v1. Configure your OpenAI SDK client to use this base_url instead of the default OpenAI endpoint. This ensures all requests, including speech generation and voice listing, are routed correctly to the LectioLab infrastructure for processing your text-to-speech conversions.

Can I use the official OpenAI SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.788t.info/v1. Use the same request shape as the OpenAI speech endpoint. This allows you to leverage familiar Python libraries without learning a new interface, making integration into your existing LMS workflows straightforward and reliable.

How do I handle rate limits in Python?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so queueing may occur under load. Implement exponential backoff in your Python code to handle 429 Too Many Requests errors gracefully, ensuring stable audio generation for batch course processing.

What is the maximum text length?

The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. If your course material exceeds this length, you must split the text into smaller chunks. Each chunk generates a separate audio file that you can join later to create the full lesson audio.

How do I split long texts?

Split your text into parts of up to 4096 characters. Generate an audio file for each part using the API. Then, join the resulting audio files into a single track. This approach ensures reliable synthesis and avoids hitting character limits while maintaining the continuity of your educational content delivery.

Which audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Select the format via the response_format field in your API request. MP3 and WAV are standard for LMS compatibility. Opus and FLAC offer compression or lossless quality options depending on your storage and bandwidth constraints for the generated audio files.

How do I authenticate requests?

Include your API key in the Authorization header as: Authorization: Bearer tts-... . Obtain this key from the /get-api-key/ page after signing in. Each account has one active key. If you issue a new key, the old one stops immediately. Ensure your Python client sends this header with every request.

What are common error codes?

Common errors include 401 for invalid authentication, 429 for rate limits, and 400 for invalid parameters like unsupported voices or formats. Failed synthesis requests are free, and charges are returned in full. Check the response body for specific details on missing fields or invalid character counts to debug your integration quickly.

Is streaming supported?

No, streaming or WebSocket support is not available. The API returns the complete audio file in the response body after synthesis finishes. You must wait for the full file to be generated before processing it. This synchronous approach simplifies integration but means you cannot play audio incrementally as it is created.

Do I need a separate SDK?

No, you do not need a separate proprietary SDK. The official OpenAI Python SDK works by pointing it to our base_url. This allows you to use standard HTTP libraries or the OpenAI package directly. It reduces dependency overhead and leverages well-maintained code for handling JSON requests and responses in your Python environment.

How do I regenerate my API key?

Generate a new key from the /get-api-key/ page in your account dashboard. Issuing a new key immediately invalidates the previous one. Ensure you update your Python configuration with the new key promptly to avoid authentication errors. This process is instant, allowing you to rotate keys securely without downtime in your production LMS.

First request

curl

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

Authentication relies on a single bearer token passed in the request header. Each account holds one active key; if a new key is issued, the previous one becomes invalid immediately.

Bearer token

Bearer token

Include the header Authorization: Bearer tts-<your-key> with every API call. The key is visible on the /get-api-key/ dashboard alongside your usage metrics.

One active key

One active key

Only one key is active per account. Generating a new key instantly revokes the old one, ensuring no concurrent valid credentials.

  • Use a single key for all integrations.

Regenerate key

Generate a new key anytime from the dashboard. The old key stops working immediately, preventing unauthorized use if the previous key was compromised.

Quickstart

Sound wave illustration for: Quickstart

LectioLab’s TTS API is compatible with the OpenAI Python SDK, allowing you to use familiar tools with minimal configuration. This approach simplifies integration into existing LMS workflows and course material pipelines without requiring a custom client library, as the official OpenAI SDK works by changing the base_url.

Install OpenAI SDK

Install the official SDK via pip. This provides the necessary classes for handling API requests and audio responses.

  • pip install openai

Set base_url

Configure the SDK to point to the LectioLab endpoint. Replace the default OpenAI base URL with the API base URL for 788t.info.

  • base_url="https://api.788t.info/v1"

Send first request

Use the configured client to call the speech endpoint. Pass your API key, the desired model, voice, and text input. The response contains the audio file binary.

Endpoint details

Sound wave illustration for: Endpoint details

The API exposes three primary endpoints for integration. The speech endpoint handles synthesis, while the voices and models endpoints provide metadata for configuration. All endpoints require a valid Bearer token in the Authorization header.

Use the voices endpoint to discover available presets and supported formats. The models endpoint returns the current engine versions. These endpoints help you verify capabilities before sending synthesis requests.

POST /v1/audio/speech

Sends text to the TTS engine and returns an audio file. Accepts JSON bodies with model, input, voice, and format parameters. Supports up to 4096 characters per request.

  • Returns binary audio data in the specified format (mp3, wav, opus, flac, pcm).

GET /v1/voices

Returns a list of available voices with their properties, including ID, name, language, and format options. Use this to select the appropriate voice preset for your course materials.

  • Voices include aria, nova, luna, sage, felix, milo, atlas, and orion.

GET /v1/models

Returns the available model versions. Currently supports 'tts-1' and 'tts-1-hd', which share the same engine and pricing structure. Use this to verify model availability.

Request parameters

Sound wave illustration for: Request parameters

Configure the synthesis parameters to control audio quality, text handling, and voice output. Select the model, manage text length constraints, and define the voice identity and language context for accurate generation.

Model selection

Choose between "tts-1" for standard quality or "tts-1-hd" for higher fidelity. Both models use the same underlying engine and incur identical pricing, allowing you to switch based on your specific audio clarity needs without cost changes.

  • tts-1: Standard quality, real-time processing.
  • tts-1-hd: Higher fidelity, same price.

Input text limit

Each request accepts up to 4096 characters, including spaces and punctuation. For longer course materials, split the text into chunks of this size, generate each segment, and join the resulting audio files to create a complete lecture.

  • Maximum 4096 characters per request.
  • Spaces and punctuation count toward the limit.

Voice and language

Select from eight voice presets such as aria or atlas. Specify the language using an ISO code if the text is in a Latin script but not English, as the system defaults to English for unmarked Latin text.

  • 8 preset voices available.
  • 23 supported languages.
  • Auto-detects script but requires explicit language for Latin non-English text.

Response formats

Sound wave illustration for: Response formats

The API returns the synthesized audio as binary data in the response body. You can choose from five formats: MP3, WAV, Opus, FLAC, or PCM, depending on your storage and playback needs.

MP3, WAV, Opus, FLAC, PCM

Select the response_format parameter to specify the output type. MP3 and Opus offer smaller file sizes suitable for web delivery, while WAV and FLAC provide lossless quality for archival or professional editing. PCM is available for raw data processing.

  • MP3: Compressed, widely compatible
  • WAV: Lossless, standard for LMS
  • Opus: Efficient compression for web
  • FLAC: Lossless, smaller than WAV
  • PCM: Raw uncompressed audio

Binary audio data

The audio content is delivered as raw binary data. When using the OpenAI Python SDK, the response object provides methods to save this data directly to a file or process it in memory.

JSON metadata

In addition to the audio, the API may return JSON metadata containing details about the request. This includes the model used, the voice selected, and the duration of the audio, depending on the SDK implementation. This data helps in logging and tracking character usage.

Response formats

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 regardless of the model used and is enforced on a rolling window basis. You can monitor your current usage through the dashboard or by checking the response headers of your API calls.

When you first create an account, your rate limit starts at 10 requests per minute. This lower threshold helps prevent abuse before the account is fully verified or funded. You can upgrade to the full 60 requests per minute limit by topping up your balance with USDT (TRC-20).

60 requests per minute

Each API key is allowed a maximum of 60 requests per minute. This limit is consistent across all models, including tts-1 and tts-1-hd. If you exceed this limit, you will receive a 429 Too Many Requests error. You can monitor your usage in the dashboard.

  • 60 requests per minute per key
  • Applies to all models
  • Returns 429 when exceeded

10 req/min initially

New accounts start with a reduced rate limit of 10 requests per minute. This limit applies until you make a top-up. Once you add funds via USDT, your limit increases to the full 60 requests per minute. This helps ensure fair usage while the account is new.

  • 10 requests per minute for new accounts
  • Increases to 60 req/min after top-up
  • Applies before any payment is made

Queue processing

Requests are processed sequentially, which means they may wait in a queue during high load. This can cause slight delays in response times, especially for longer texts. However, the system ensures that all requests are eventually processed. You can split long texts into smaller chunks to improve throughput.

  • Requests processed sequentially
  • May wait in queue during high load
  • No guaranteed real-time response

Error handling

Sound wave illustration for: Error handling

Errors return standard HTTP status codes with a JSON body containing code and message. Always check the status code before parsing the audio data. Failed synthesis requests are free, so a non-200 response means no charge was applied.

Handle 429 by implementing exponential backoff. The system processes requests sequentially under load, so queuing delays are normal. Use 400 errors to validate input constraints before sending large batches.

429 Too Many Requests

Returned when you exceed 60 requests per minute. New accounts start with a 10 req/min limit. The API queues requests, so you may experience latency even before hitting the hard limit.

  • Implement retry logic with exponential backoff.
  • Monitor the Retry-After header if provided.
  • Split large texts into chunks to stay within limits.

400 Bad Request

Returned when input exceeds 4096 characters or parameters are malformed. Ensure model is tts-1 or tts-1-hd, and voice matches one of the 8 presets. Invalid response_format values also trigger this error.

  • Validate character count before sending.
  • Check voice names against GET /v1/voices.
  • Ensure input is a non-empty string.

401 Unauthorized

Returned if the Bearer token is missing, invalid, or expired. Ensure the header is Authorization: Bearer tts-.... Regenerate your key via the dashboard if you suspect compromise; the old key stops immediately.

  • Check for typos in the API key.
  • Ensure no extra whitespace in the header.
  • Regenerate key via /get-api-key/ if needed.

Code examples

Sound wave illustration for: Code examples

Use the OpenAI Python SDK for direct integration. Point it at our base URL and pass your Bearer token to synthesize audio instantly.

Python snippet

Install the official SDK, set the base URL to https://api.788t.info/v1, and call client.audio.speech.create. Pass your text, voice preset, and desired format like mp3 or wav.

Curl command

Send a POST request to /v1/audio/speech with a JSON body containing model, input, voice, and response_format. Include your Authorization: Bearer header.

Long text splitting

Split input text into chunks of 4096 characters. Send each chunk to the API and concatenate the resulting audio files to create the final course audio.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. We retain only request metadata—timestamp, character count, and status—for billing and operational purposes.

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. LibriTTS-R paper (arXiv 2305.18802)
  4. OpenAI API reference: create speech
  5. LibriVox public-domain audiobooks
  6. openai-python on GitHub
  7. FFmpeg documentation
  8. LibriTTS-R corpus (OpenSLR 141)
  9. MDN: Web Speech API
  10. ISO 639 language codes
  11. openai-node on GitHub
  12. Python documentation

More on this site