Get Started with the Text-to-Speech API Integration

By LingoVoice editorial team · Updated 2026-11-18

This documentation provides the technical specifications for integrating LingoVoice’s text-to-speech API into language education applications. It covers authentication, request parameters, response formats, and error handling to enable reliable audio generation workflows. The guide is designed for developers building scalable TTS solutions who require precise control over voice selection, speed, and output formats.

Readers will find concrete examples for cURL requests and OpenAI SDK compatibility, along with details on rate limits, character-based pricing, and language handling. The API supports 23 languages and eight voice presets, with input text limited to 4096 characters per request. Failed requests are refunded automatically, and billing is transparent with no hidden fees or subscriptions.

Get Started with the Text-to-Speech API Integration

Frequently asked questions

How do I get an API key?

Sign up at /get-api-key/ via Google or email. The page displays your active API key, balance, trial status, characters remaining, usage history, and a ready curl example. Each account holds one active key; issuing a new one immediately invalidates the previous key.

What is the base URL?

The API base URL is https://api.play2jj.com/v1. You send POST requests to https://api.play2jj.com/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models for retrieving configuration details and available assets.

Can I use the OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. Configure your OpenAI SDK client to use the base URL https://api.play2jj.com/v1 and provide your LingoVoice API key. This allows you to use official OpenAI SDKs without modification.

What models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing. Select the model in your request body. The API returns audio files based on the specified input text, voice, and format parameters.

How do I set the language?

Pass the optional language parameter with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English Latin-script inputs.

What are the rate limits?

The limit is 60 requests per minute per key. New accounts without top-ups are limited to 10 requests per minute. Requests are processed sequentially, so high load may cause queuing delays. Exceeding limits may result in temporary throttling.

How do I handle errors?

The API returns standard HTTP status codes for errors. Failed requests do not consume your character balance. Check the response body for details. Implement retry logic with exponential backoff to handle transient network issues or temporary server load spikes.

Are failed requests refunded?

Yes. If synthesis fails, the charge is returned in full. You are only billed for successful audio generation. Failed requests do not deduct from your balance, ensuring you pay only for usable audio output.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format in the response_format field of your request body. The API returns the audio file directly in the response according to your selected format.

Can I change the voice?

Yes. Select from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Pass the voice name in the voice field. Each voice has a distinct tone, suitable for different content types like narration or conversation.

How do I adjust the speed?

Use the speed parameter, accepting values between 0.25 and 4.0. This controls the playback rate without affecting pitch or voice characteristics. The API does not define a default speed value if omitted. For consistent results in your language education tools, explicitly specify the speed parameter in every request to ensure predictable generation behavior.

Is the API RESTful?

Yes. The API follows RESTful conventions. Use POST to generate audio and GET to retrieve voice and model details. It accepts standard JSON bodies and returns audio files. Integration is straightforward for developers familiar with HTTP-based APIs, requiring only standard authentication and request formatting.

Do I need to install a library?

No. You can use plain HTTP requests or the OpenAI SDK. No proprietary library is required. Use standard HTTP clients or the official OpenAI SDK by pointing it to our base URL. This keeps dependencies minimal.

How do I rotate my API key?

Issue a new key from your dashboard at /get-api-key/. The new key becomes active immediately, and the old key stops working at once. You can rotate keys as needed without downtime or additional configuration steps.

First request

curl

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

Sound wave illustration for: Authentication

LingoVoice uses a single active API key for all requests. The key format is tts- followed by alphanumeric characters. This key authorizes your account and tracks usage against your balance.

API key format

Keys are issued upon account creation on the /get-api-key/ page. Ensure the key begins with the prefix tts- to be recognized by the authentication system.

Bearer token header

Include the key in the HTTP header for every request. Use the standard authorization header format: Authorization: Bearer tts-.... Incorrect formatting will result in a 401 Unauthorized error.

Key rotation

Generate a new key from your dashboard at any time. The previous key becomes invalid immediately upon issuance of the new one. Update your client configuration promptly to avoid service interruption.

First Request with Curl

Sound wave illustration for: First Request with Curl

Send a POST request to the speech endpoint with your API key and the text payload. The service returns a complete binary audio file, not a stream, ensuring reliable delivery for batch processing in language learning applications.

Basic POST request

Use curl to send your request to the endpoint. Include the Authorization header with your Bearer token. The request body must be valid JSON containing the text and voice parameters.

JSON body structure

The payload requires the model, input, and voice fields. You may optionally specify response_format, speed, and language. Ensure the input text does not exceed 4096 characters per request.

  • model: tts-1 or tts-1-hd
  • input: string up to 4096 chars
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, or pcm

Response format

On success, the API returns the audio binary directly in the response body. You receive no JSON envelope, allowing you to save the file immediately for playback in your educational tools.

First Request with Curl

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

LingoVoice implements the OpenAI speech endpoint schema, allowing teams to leverage existing infrastructure. By adjusting the base URL, your application routes requests to our TTS engine without modifying the core request payload structure.

Base URL configuration

Configure your client to point to https://api.play2jj.com/v1. This ensures all speech generation requests target the correct LingoVoice endpoint while maintaining standard OpenAI compatibility.

SDK compatibility

The official OpenAI SDKs work directly with LingoVoice. No custom client library is required; simply update the base_url parameter to use our service for text-to-speech operations.

Code example

Initialize the client with your API key and the adjusted base URL. Pass the model, input, voice, and response_format parameters as you would for standard OpenAI speech generation.

  • Set base_url to https://api.play2jj.com/v1
  • Use tts-1 or tts-1-hd models
  • Pass Authorization: Bearer <key> header
  • Receive audio file in specified format

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis parameters to control audio quality, voice identity, and playback speed. These fields define how the API processes your input text into the final audio file.

Selecting the appropriate model and voice ensures the output matches your educational content requirements, while speed adjustments allow for varied listening experiences without re-synthesis.

Model selection

The API accepts two model identifiers: tts-1 and tts-1-hd. Both utilize the same underlying engine and pricing structure, allowing you to switch between them seamlessly. Use tts-1 for standard generation and tts-1-hd if higher fidelity is required for specific language lessons, though the character cost remains identical.

Voice presets

Choose from eight distinct voice presets tailored for different educational contexts. Female voices include aria (warm narrator), nova (upbeat), luna (storytelling), and sage (instructional). Male options feature felix (energetic promo), milo (conversational), atlas (neutral news), and orion (documentary). Each voice supports all 23 available languages.

Ensure correct spelling for milo to avoid voice not found errors. All voices are based on licensed recordings and carry an inaudible synthetic watermark.

Speed control

Adjust the speed parameter between 0.25 and 4.0 to modify the playback rate. Slower speeds (e.g., 0.5) aid learners in processing complex phonetics, while faster rates (e.g., 2.0) suit review sessions. The API processes requests sequentially, so extreme speed variations may affect queue times during high volume.

Response Formats

Sound wave illustration for: Response Formats

Your API responses return the synthesized audio file directly in the body, allowing seamless integration into your application’s audio pipeline. The format you select determines the file structure and encoding, ensuring compatibility with your specific playback or processing requirements.

MP3 output

MP3 is the default response format, providing a compressed audio file with a standard bitrate. This format balances file size and quality effectively, making it suitable for most web-based language learning applications where bandwidth efficiency is a priority.

WAV output

WAV provides an uncompressed container format for audio data. Unlike raw PCM, WAV includes file header metadata, making it compatible with standard audio players and editors that expect a structured container rather than raw byte streams.

OPUS and FLAC

OPUS offers high-quality audio at very low bitrates, ideal for bandwidth-constrained mobile environments. FLAC provides lossless compression, preserving the exact audio quality of the synthesis engine while reducing file size compared to uncompressed formats.

Response Formats

Rate Limits

Sound wave illustration for: Rate Limits

Each API key supports 60 requests per minute, or 10 per minute before the first top-up. Requests are processed sequentially, meaning a request may wait in a queue under load. Longer texts take roughly real time to generate, which influences throughput.

60 requests per minute

The rate limit is strictly enforced per key. You may send up to 60 requests in any 60-second window. Accounts without a top-up are limited to 10 requests per minute.

Queue behavior

Requests are processed one after another. If multiple requests are submitted simultaneously, subsequent requests wait in a queue until a processing slot becomes available. There is no defined queue capacity limit; requests wait until they can be processed.

Retry logic

Implement exponential backoff for temporary errors. Failed requests are free, so retrying after a brief pause is safe. Avoid sending requests faster than the rate limit allows to minimize queuing delays.

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request outcomes. A 4xx error typically signals invalid input or authentication issues, while a 5xx error indicates a transient server issue. You can identify the specific cause by inspecting the error message in the JSON response body.

Common error codes

The API uses standard HTTP status codes to indicate request outcomes. A 4xx error typically signals invalid input or authentication issues, while a 5xx error indicates a transient server issue. You can identify the specific cause by inspecting the error message in the JSON response body.

  • 400 Bad Request: Invalid JSON or missing required fields.
  • 401 Unauthorized: Invalid or expired API key.
  • 429 Too Many Requests: Exceeded 60 requests per minute limit.
  • 500 Internal Server Error: Temporary processing failure.

Failed request refund

If synthesis fails due to a server-side error, the charge is returned in full. Failed requests do not deduct from your balance. This ensures you only pay for successfully generated audio files, maintaining transparent billing for high-volume language education tools.

Status codes

The API adheres to standard HTTP conventions. Use 200 for successful synthesis and 400–499 for client errors. Monitor these codes to automate retry logic and handle billing discrepancies efficiently in your integration workflow.

Error Handling

Language Specification

Sound wave illustration for: Language Specification

LingoVoice supports 23 languages, allowing any voice preset to speak any supported language. The API attempts to detect the language automatically based on the input script. This simplifies integration for multilingual applications without requiring explicit language flags for every request.

Auto-detection

The system identifies the language from the character set. For example, Cyrillic text is recognized as Russian, and Han characters as Chinese. This reduces configuration overhead for developers managing diverse content types.

Manual ISO code

You can explicitly set the language parameter using an ISO 639-1 code. This ensures precise control, especially when the text contains mixed scripts or when auto-detection might be ambiguous. Supported codes include 'en', 'es', 'fr', 'de', 'ja', 'ko', 'zh', and others listed in our voices endpoint.

  • ISO 639-1 code format
  • Overrides automatic detection
  • Ensures consistent voice behavior

Latin script default

If the language parameter is omitted and the input uses Latin script, the API defaults to English. For non-English text in Latin script (e.g., German or Spanish), you must specify the language field to avoid incorrect pronunciation. This prevents misinterpretation of accented characters or common Latin words in different languages.

  • Latin script defaults to English
  • Set language for other Latin-based languages
  • Prevents pronunciation errors

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Mastering new languages empowers your startup to expand globally and connect with diverse talent pools effortlessly.

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. Node.js documentation
  3. openai-node on GitHub
  4. IETF RFC 7845: Ogg Opus
  5. curl documentation
  6. MDN: Web Speech API
  7. LibriTTS-R corpus (OpenSLR 141)
  8. Creative Commons Attribution 4.0
  9. TRON developer hub: TRC-20
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. W3C WAI: making audio and video accessible
  12. Python documentation

More on this site