Voice Synthesis API Documentation for Developers

By LinguaVoice team · Updated 2026-11-18

This documentation provides a technical reference for integrating LinguaVoice’s text-to-speech API into language learning applications. You will find the exact request shapes, parameter definitions, and response structures required to generate audio files programmatically. The guide assumes you are a developer familiar with RESTful services and JSON payloads, focusing on concrete implementation details rather than general product marketing.

We cover authentication via Bearer tokens, available endpoints for speech synthesis and voice listing, and the specific constraints of our engine, such as the 4096-character input limit and 60 requests per minute rate limit. You can configure speed, voice presets, and output formats like MP3 or WAV using standard HTTP methods. Examples use the OpenAI SDK compatible format, allowing you to switch endpoints with minimal code changes while maintaining predictable costs and clear technical boundaries.

Voice Synthesis API Documentation for Developers

Frequently asked questions

How do I get an API key for the first time?

Navigate to /get-api-key/ and sign up using Google or an email/password combination. Google sign-ups receive a $0.50 free trial valid for seven days, while email-based accounts start without trial credit. Your active key appears on the dashboard immediately, allowing you to begin sending requests to the API endpoint.

Can I use the OpenAI Python SDK with this API?

Yes. The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.play93k.com/v1 and providing your site-specific key. This allows you to integrate our text-to-speech service directly into existing OpenAI-compatible codebases without rewriting the integration logic.

What is the maximum character limit per request?

Each request supports a maximum of 4096 characters in the input field. Spaces and punctuation count toward this limit. For texts longer than 4096 characters, you must split the text into parts, generate audio for each part, and join the resulting audio files to create the final output.

How do I specify a language other than English?

Include the optional 'language' field in your JSON body with the ISO code for your target language. If omitted, the system guesses the language based on the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate synthesis for non-English Latin-script texts like Spanish or German.

Is the response format always audio?

The primary response is an audio file in your chosen format (mp3, wav, opus, flac, or pcm). If a request fails, the response contains error details. Failed requests are free, and any charges are returned in full. The audio itself is not stored by the API after delivery.

What happens if the server returns an error?

If synthesis fails, the charge is returned in full. You will receive an error response indicating the issue. You can retry the request or adjust parameters like speed or voice. Failed requests do not consume your character balance, ensuring you only pay for successfully generated audio files.

Can I change the voice mid-stream?

No. The API does not support streaming or WebSocket connections. Each request generates a complete audio file based on the specified voice preset. To change voices, you must send separate requests for each segment and join the resulting audio files manually in your application logic.

Does the API support SSML tags?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You control pacing and emphasis by adjusting the 'speed' parameter between 0.25 and 4.0. For more nuanced control, you can split text into separate requests using different voices or speeds for each segment.

How do I handle long texts exceeding 4096 characters?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate POST request to the speech endpoint. Once you receive the audio files for each part, join them in your application to create the final continuous audio file. This ensures compliance with the character limit.

Is the API key case-sensitive?

Yes. The Authorization header requires a Bearer token in the format 'tts-...'. Ensure you copy the key exactly as displayed in your dashboard. Using an incorrect or case-mismatched key will result in authentication errors. You can issue a new key at any time if needed.

Can I rotate my API key without downtime?

Yes. You can issue a new key from your dashboard at any time. The old key stops working immediately upon issuing the new one. This allows for seamless rotation without downtime, provided your application updates to use the new key promptly. Only one key is active per account.

What is the default speed setting?

The default speed is 1.0. You can adjust the 'speed' parameter between 0.25 and 4.0 to slow down or speed up the synthesis. This allows you to tailor the audio for language learning contexts, such as slower speech for learners or natural pace for native speakers.

Does the API return metadata with the audio?

The response primarily contains the audio file. Request metadata (time, characters, status) is kept for billing. You can track usage and characters left via the dashboard. Generated audio is returned in the response and not stored.

How do I test my integration before production?

Use the free trial credit of $0.50 (about 50,000 characters) if you sign up with Google. Alternatively, use the provided curl example on the /get-api-key/ page. Send small test requests to the endpoint to verify authentication, voice selection, and format handling before scaling up your integration.

First request

curl

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

Authentication and keys

Sound wave illustration for: Authentication and keys

Authentication is handled via a Bearer token passed in the Authorization header. You must include your unique API key with every request to identify your account and track usage against your balance.

Bearer token format for Authorization header

Bearer token format for Authorization header

Include your key as Bearer <your-key> in the HTTP header. The format is strict; any deviation results in a 401 Unauthorized error. Ensure the token is transmitted securely over HTTPS to prevent interception during transmission to the API endpoint.

One active key per account

One active key per account

Each account maintains a single active API key. This simplifies integration by removing the need to manage multiple credential sets or rotate keys periodically based on time. You use the same key for all requests within your application.

  • Single key per account
  • No time-based expiration
  • Unified access control

Issuing a new key invalidates the old one instantly

If you suspect a key is compromised or wish to rotate credentials, generating a new key immediately deactivates the previous one. Any requests using the old key will fail instantly, ensuring no unauthorized usage continues after rotation.

Endpoints and methods

Sound wave illustration for: Endpoints and methods

The API provides three primary endpoints for interacting with the text-to-speech engine. Use POST /v1/audio/speech to generate audio files from text input. Use GET /v1/voices to retrieve available voice presets, languages, formats, and price. Use GET /v1/models to fetch details about the underlying synthesis models.

POST /v1/audio/speech for generation

Send a JSON body containing the text, voice, and model to generate audio. The endpoint returns the audio file directly in the response body. Text is limited to 4096 characters per request. For longer texts, split the input and join the resulting audio files.

  • Accepts JSON input with fields like 'input', 'voice', and 'model'.
  • Returns audio data in the specified format (mp3, wav, opus, flac, pcm).

GET /v1/voices for voice list and details

Retrieve a list of all available voice presets. Each entry includes the voice name, gender, supported languages, formats, and price. This endpoint helps developers select the appropriate voice for their language learning content without guessing IDs.

  • Returns a list of 8 voice presets.
  • Details include voice name, gender, and language support.

GET /v1/models for available model info

Fetch information about the available synthesis models. The API currently supports 'tts-1' and 'tts-1-hd', which use the same engine and pricing. This endpoint allows you to verify model availability and characteristics programmatically.

  • Lists available models like 'tts-1' and 'tts-1-hd'.
  • Useful for verifying model capabilities before making synthesis requests.

Request parameters

Sound wave illustration for: Request parameters

The API accepts plain text input with a strict limit of 4096 characters per request. This constraint applies to all characters, including spaces and punctuation. For longer content, split the text into chunks and join the resulting audio files sequentially.

Each request must specify the desired voice from our eight presets. The system does not support custom voice cloning, SSML markup, or emotion tags. Input is processed as standard text strings, ensuring predictable generation behavior for language learning applications.

Input text up to 4096 characters

Send your text in the input field. The limit is strict; exceeding it returns a 400 error. For texts longer than 4096 characters, split the content into smaller parts and concatenate the returned audio files to maintain continuity.

Spaces and punctuation count toward the character limit. For example, a 10,000-character article requires three separate requests. This approach ensures stable generation and clear cost tracking, as each chunk is billed individually.

  • Maximum length: 4096 characters per request.
  • Includes all spaces and punctuation marks.
  • Split long texts manually or via script.
  • Concatenate audio files for continuous playback.

Voice selection from 8 presets

Choose from eight distinct voice presets using the voice parameter. Options include female voices like Aria and Nova, or male voices like Felix and Milo. Each voice offers a specific tonal quality suitable for different language learning contexts.

The selected voice determines the synthesis engine behavior. All voices support the same range of languages and formats. There is no emotion tagging or dynamic pitch adjustment; the tone remains consistent throughout the generated clip.

  • Female: aria, nova, luna, sage.
  • Male: felix, milo, atlas, orion.
  • Static tone, no emotion tags.
  • Consistent quality across all voices.

Optional language ISO code specification

Provide the language parameter with an ISO 639 code to ensure accurate pronunciation. While the system guesses the language from the script, explicit codes prevent errors, especially for Latin-script text that might not be English. Supported languages include Arabic, Chinese, French, and Spanish.

If omitted, Latin text defaults to English. For non-English Latin-script content, always set the language code. Unsupported languages like Vietnamese or Thai will result in default English pronunciation or errors, depending on the input script.

  • Set language for non-English Latin text.
  • Defaults to English for Latin scripts.
  • Supports 23 specific languages.
  • Ensures correct phoneme generation.

Response formats

Sound wave illustration for: Response formats

The API returns generated audio in the format you specify, allowing you to balance file size and quality based on your application’s needs. Supported formats include MP3, WAV, OPUS, FLAC, and PCM, ensuring compatibility with various playback environments and storage constraints.

Each response contains the binary audio data directly, eliminating the need for additional conversion steps. You can select the format that best suits your integration, whether prioritizing web delivery efficiency or preserving lossless fidelity for local processing.

MP3 for web compatibility

MP3 is the default choice for web-based applications due to its broad browser support and efficient compression. It provides a good balance between audio quality and file size, making it ideal for downloading in language learning apps.

Use MP3 when you need to embed audio directly into HTML5 players or when bandwidth efficiency is a priority for end-users.

  • Optimal for web playback
  • Small file sizes
  • Universal browser support

WAV for high-quality local storage

WAV provides uncompressed, high-fidelity audio suitable for local storage or further processing. It is ideal when you need to preserve the exact audio quality without any loss, such as for offline language learning modules.

Choose WAV when file size is less critical than maintaining pristine audio clarity for educational materials.

  • Uncompressed quality
  • Ideal for local storage
  • No lossy compression

OPUS, FLAC, and PCM options

OPUS offers advanced compression with high quality, suitable for modern web and mobile applications. FLAC provides lossless compression, reducing file size while maintaining original quality. PCM delivers raw, uncompressed audio data for maximum compatibility with specialized audio hardware or processing tools.

These formats give you flexibility depending on whether you prioritize compression efficiency, lossless fidelity, or raw data integrity.

  • OPUS: efficient compression
  • FLAC: lossless compression
  • PCM: raw uncompressed data

Speed and voice controls

Sound wave illustration for: Speed and voice controls

Speed control allows fine-tuning of playback rate between 0.25 and 4.0, enabling precise synchronization with language learning exercises. This parameter directly affects the duration of the generated audio file, allowing educators to create slower, clearer pronunciations for beginners or faster natural speech for advanced listeners.

Adjustable speed from 0.25 to 4.0

The speed field accepts values from 0.25 to 4.0. Setting a lower speed (e.g., 0.5) stretches the audio, which is useful for dictation practice. Higher speeds compress the timeline, fitting more content into limited lesson slots without sacrificing intelligibility.

Selecting specific voice presets

Choose from eight distinct voice presets to match your content’s tone. Female voices like Aria (warm narrator) and Nova (bright) suit interactive lessons, while Male voices like Atlas (neutral news) or Orion (deep documentary) work well for structured reading materials. All voices support all 23 languages.

  • Aria: Warm, clear narrator
  • Atlas: Neutral, news-style delivery
  • Orion: Deep, documentary tone
  • Nova: Bright, upbeat energy

Handling audio duration vs text length

Generation takes roughly real-time duration on long texts, processing about 25 characters per second. Short phrases may take a few seconds to synthesize due to initialization overhead. Under load, requests queue sequentially, so duration estimates should account for potential wait times during peak usage.

Speed and voice controls

Error handling and status codes

Sound wave illustration for: Error handling and status codes

Effective error handling ensures your language learning application can gracefully manage API constraints. Understanding specific status codes allows product teams to implement robust retry logic and user feedback mechanisms without unnecessary infrastructure overhead.

400 errors for invalid parameters

A 400 status indicates a client-side mistake, such as exceeding the 4096-character input limit or providing an unsupported voice name. The API returns precise details about the failed field, allowing immediate correction without consuming billing credits.

429 errors for rate limit exceeded

New accounts start with a 10 requests per minute limit, increasing to 60 requests per minute after the first top-up. If you exceed this quota, the API returns a 429 error. Implement exponential backoff to handle queue delays during peak usage.

500 errors for synthesis failures

Internal synthesis errors return a 500 status. Unlike client errors, these do not consume your character balance. The API returns the full credit amount for the failed request.

SDK integration examples

Sound wave illustration for: SDK integration examples

Integrate LinguaVoice’s TTS API by adjusting the OpenAI SDK’s base URL to point to our endpoint. This allows you to use existing client libraries without rewriting core logic, simply by directing requests to https://api.play93k.com/v1.

The API mirrors the OpenAI speech endpoint structure, ensuring compatibility with standard SDK implementations. You can authenticate using your Bearer token and generate audio files with minimal code changes, leveraging familiar request shapes for seamless integration into language learning applications.

Configuring base_url for OpenAI SDK

Set the base_url parameter in your OpenAI SDK client configuration to https://api.play93k.com/v1. This redirects all speech generation requests to our infrastructure while maintaining the standard request body format.

  • Initialize client with custom base URL
  • Use standard model and voice parameters
  • Maintain existing SDK methods like .create()

Using official SDKs with new endpoint

Since the request shape matches the OpenAI specification, you can use the official OpenAI SDKs for Python, Node.js, or other languages. Pass your API key via the Authorization header as usual.

  • Python SDK example
  • Node.js SDK example
  • Standard JSON body structure

Plain HTTP request examples with curl

For direct integration, send a POST request to the speech endpoint with your JSON payload. Include the Authorization: Bearer tts-... header with your active key.

Example: `curl -X POST https://api.play93k.com/v1/audio/speech -H 'Authorization: Bearer YOUR_KEY' -d '{"model": "tts-1", "input": "Hello", "voice": "nova"}'`

Rate limits and quotas

Sound wave illustration for: Rate limits and quotas

Usage is capped at 60 requests per minute for standard accounts, ensuring stable throughput for language learning applications. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed.

60 requests per minute per key

Each API key allows up to 60 synthesis requests per minute. This limit applies per key, so using multiple keys can increase throughput if needed.

10 requests per minute for new accounts

Accounts created with email and password start without trial credit and are limited to 10 requests per minute. This restriction lifts after the first USDT top-up is credited, usually within minutes.

Queue processing under high load

Requests are processed sequentially. Under high load, additional requests may wait in a queue before synthesis begins. Typical speed is roughly 25 characters of text per second of generation, so longer texts may take time to complete.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. We must design intuitive learning paths that adapt to each user's unique pace and style for maximum engagement.

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. openai-node on GitHub
  3. curl documentation
  4. OpenAI API reference: create speech
  5. LibriTTS-R corpus (OpenSLR 141)
  6. LibriVox public-domain audiobooks
  7. FFmpeg documentation
  8. Node.js documentation
  9. MDN: Web Speech API
  10. Creative Commons Attribution 4.0
  11. W3C WAI: making audio and video accessible
  12. IETF RFC 7845: Ogg Opus

More on this site