API Documentation for Text-to-Speech Integration

By LinguaLoop editorial team · Updated 2026-11-19

This documentation provides a practical guide for integrating LinguaLoop’s text-to-speech API into language learning platforms and edtech applications. You will find precise technical details on authentication, endpoint structures, and parameter configurations required to generate consistent, multi-lingual audio narrations for educational exercises. The guide focuses on concrete implementation steps using standard tools, ensuring you can deploy reliable audio generation without managing complex infrastructure.

We assume you are a developer familiar with REST APIs and OpenAI SDK compatibility. The examples demonstrate how to configure base URLs, handle rate limits, and manage voice selection for 23 supported languages. This resource is designed for technical teams who need specific, verifiable data—such as character limits and pricing tiers—to build scalable audio pipelines for their platforms.

API Documentation for Text-to-Speech Integration

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.1234admin.info/v1. You configure your client library to use this endpoint instead of the standard OpenAI URL. All requests, including speech synthesis and voice listing, are directed to this address. This allows you to use existing OpenAI SDKs by simply changing the base_url configuration parameter in your code.

Does the API support OpenAI SDK?

Yes, the request shape matches the OpenAI speech endpoint exactly. You can use the official OpenAI SDKs by changing the base_url to https://api.1234admin.info/v1 and providing your site-specific API key. This ensures compatibility with existing OpenAI client implementations without requiring custom HTTP request handling or new library dependencies.

How do I authenticate my requests?

Include your API key in the Authorization header as a Bearer token. The format is: Authorization: Bearer tts-... Each account holds one active key at a time. Issuing a new key immediately invalidates the previous one, ensuring secure access control. You can generate a new key from your account dashboard at any time.

What is the maximum text length?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of 4096 characters or fewer, generate audio for each part, and join the resulting audio files. This ensures compatibility with the single-request processing model.

Can I use the API with Python?

Yes, you can use the official OpenAI Python SDK. Configure the base_url to https://api.1234admin.info/v1 and use your API key. Alternatively, you can send standard HTTP POST requests using any Python HTTP library. The JSON request body structure is identical to the OpenAI speech endpoint, ensuring straightforward integration.

How do I specify 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. For non-English Latin-script text, explicitly set the language parameter. Supported languages include Arabic, Chinese, English, French, German, Japanese, Spanish, and 18 others.

What formats are supported for output?

The API supports mp3, wav, opus, flac, and pcm output formats. Specify your preferred format in the response_format field of the request body. The generated audio is returned directly in the response. Choose mp3 for smaller file sizes or wav/flac for lossless quality, depending on your application requirements.

What happens if I exceed the rate limit?

The rate limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a 10 requests per minute limit until the first top-up. Failed requests are free, so exceeding limits does not incur charges, but processing may take longer due to queuing.

Is there an SDK for mobile devices?

No, there is no official mobile SDK. You can use the standard HTTP API or the OpenAI SDK, which works on any platform supporting HTTP requests. Since the API is RESTful, you can integrate it into iOS, Android, or other mobile applications using standard networking libraries available in your development environment.

Do I need to handle SSML tags?

No, the API does not support SSML. You provide plain text input, and the system generates audio without requiring SSML tag handling. If you need specific pronunciation or pacing, you can adjust the speed parameter or choose a voice preset that matches your desired tone. Complex SSML features are not available.

How do I list available voices?

Send a GET request to /v1/voices. This endpoint returns details about available voices, languages, and formats. You can see the eight preset voices (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) and their characteristics. Use this information to select the appropriate voice for your text-to-speech requests.

What is the speed range parameter?

The speed parameter accepts values between 0.25 and 4.0. A value of 1.0 is normal speed. Lower values slow down the narration, while higher values speed it up. This allows you to adjust the playback rate to suit different learning contexts, such as slower speech for language learners or faster narration for quick reviews.

Can I send custom pronunciation lexicons?

No, the API does not support custom pronunciation lexicons. You cannot upload phoneme dictionaries or define custom pronunciations for specific words. The system uses the voice model’s default pronunciation rules. If you need specific pronunciation, you may need to adjust the text input or use speed variations to achieve the desired effect.

How do I handle audio streaming?

The API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response after synthesis is finished. For real-time needs, you must wait for the full audio file to be generated. There is no partial audio streaming available in this API.

First request

curl

curl https://api.1234admin.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.1234admin.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.1234admin.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 and Keys

Sound wave illustration for: Authentication and Keys

The LinguaLoop TTS API uses a single active API key for authentication. You generate this key on the /get-api-key/ dashboard, where it is displayed alongside your current balance and character usage. This key is the sole credential required to authorize your requests.

Generating Your API Key

Generating Your API Key

Sign in via Google or email on the /get-api-key/ page to retrieve your unique key, prefixed with tts-. Each account holds exactly one active key at any time, ensuring straightforward permission management for your edtech integration.

Bearer Token Format

Bearer Token Format

Include the key in every request header as Authorization: Bearer tts-your_key_here. The API validates this token against the request metadata to authorize character consumption from your balance.

Revoking Old Keys

If you suspect a leak or need to rotate credentials, issue a new key from the dashboard. The old key stops working immediately upon generation, preventing further unauthorized usage without requiring manual invalidation.

Base URL Configuration

Sound wave illustration for: Base URL Configuration

To integrate LinguaLoop’s TTS API, update the OpenAI SDK’s base_url to https://api.1234admin.info/v1. This allows existing client libraries to route requests directly to our speech endpoint without code refactoring.

OpenAI SDK Compatibility

The API mirrors the OpenAI speech endpoint structure, enabling immediate compatibility with standard SDKs. Developers can reuse existing initialization logic by simply pointing the client to our domain.

Base URL Change Requirement

Specify base_url="https://api.1234admin.info/v1" in your SDK configuration. Ensure your API key is passed via the Authorization: Bearer header to authenticate requests against our infrastructure.

Endpoint Structure

Send audio synthesis requests to POST /v1/audio/speech. Additional endpoints like GET /v1/voices provide metadata on available models and languages, ensuring precise configuration for your edtech applications.

  • POST /v1/audio/speech
  • GET /v1/voices
  • GET /v1/models

Speech Generation Endpoint

Sound wave illustration for: Speech Generation Endpoint

The core of LinguaLoop is the speech generation endpoint. Send a POST request to the API base URL with your JSON payload. The system processes text and returns synthesized audio files, supporting standard OpenAI SDK workflows for seamless integration into your language learning platform.

POST Request Body Structure

Send a JSON object containing the model, input text, and voice selection. The API accepts standard fields compatible with the OpenAI speech endpoint. Ensure your text does not exceed 4,096 characters per request to guarantee consistent synthesis results.

  • Content-Type: application/json
  • Max input length: 4,096 characters

Required Parameters

Every request must include model, input, and voice. The model accepts "tts-1" or "tts-1-hd". The input field holds your text string. The voice parameter selects from eight presets, such as aria or atlas, which determine the narrator's tone for your educational content.

Optional Parameters

You may specify response_format for output types like mp3, wav, opus, flac, or pcm. Adjust speed between 0.25 and 4.0 for pacing control. Set language to an ISO code (e.g., "de", "fr") to ensure correct pronunciation for non-English Latin-script text.

Voice and Language Selection

Sound wave illustration for: Voice and Language Selection

Retrieve the full list of supported voices, languages, and formats by calling the GET /v1/voices endpoint. This returns metadata for all eight preset voices, confirming which of the 23 supported languages each voice can render. Use this data to dynamically populate your language learning platform's voice selection dropdowns without hardcoding IDs.

When generating speech, you may optionally pass a language parameter using an ISO 639-1 code (e.g., es, fr, de). If omitted, the API guesses the language from the text script, defaulting to English for Latin characters. Explicitly setting the language ensures accurate pronunciation for non-English Latin-script texts, such as Spanish or German.

Listing Available Voices

The GET /v1/voices endpoint returns a structured JSON object containing all available voice IDs, their associated languages, and supported audio formats. This allows your edtech application to programmatically discover which narrator styles are available for each language pair, ensuring you only present valid options to end-users during exercise creation.

  • Returns voice ID, name, gender, and supported languages.
  • Includes metadata on available output formats (mp3, wav, etc.).

Specifying Language Codes

Pass the language field in your request body to enforce specific pronunciation rules. While the API can often infer the language from the text script, explicit codes prevent errors for ambiguous texts or mixed-language content. Supported ISO codes include: ar, zh, da, nl, en, fi, fr, de, el, he, hi, it, ja, ko, ms, no, pl, pt, ru, es, sw, sv, tr.

  • Use ISO 639-1 codes (e.g., 'ja' for Japanese).
  • Defaults to English for unmarked Latin-script text.
  • Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali.

Voice Preset Descriptions

Select one of eight voice presets optimized for clear, educational narration. Female voices include Aria (warm narrator), Nova (upbeat), Luna (soft storytelling), and Sage (calm instruction). Male voices include Felix (energetic promo), Milo (friendly conversation), 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.

Audio Format Options

Sound wave illustration for: Audio Format Options

The response_format field in your request body determines the output audio type. You can choose between mp3, wav, opus, flac, or pcm to suit your application's bandwidth and compatibility requirements.

MP3 Output Configuration

MP3 is the default and most widely supported format. It offers a good balance between file size and audio quality, making it ideal for web-based language learning exercises where bandwidth efficiency matters.

WAV and FLAC Options

WAV provides uncompressed audio, while FLAC offers lossless compression. These formats are suitable for high-fidelity archival storage or when your edtech platform requires raw audio data without decoding artifacts.

Opus and PCM Support

Opus provides efficient compression, while PCM returns raw linear audio data. Use PCM if you need to process the audio samples directly in your application logic.

Audio Format Options

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

The LinguaLoop API enforces a strict rate limit of 60 requests per minute per API key. This quota applies to all /v1/audio/speech calls, regardless of the text length or voice selected. For language learning platforms processing batch exercises, exceeding this limit results in a 429 Too Many Requests response, ensuring stable infrastructure without unexpected overages.

Requests Per Minute Limit

Each account is allocated 60 requests per minute. This limit is consistent across all tiers and applies to the single active API key associated with your account. If you are generating audio for a large library of phrases, you must implement client-side logic to queue requests and respect the 60-per-minute ceiling to avoid delays.

  • Limit: 60 requests/minute/key
  • Applies to all models (tts-1, tts-1-hd)
  • Shared across all endpoints

Pre-Top-Up Limit

Before your first top-up, the rate limit is reduced to 10 requests per minute. This lower threshold applies to all accounts. Once you complete a USDT (TRC-20) top-up of at least $5, the limit automatically increases to the standard 60 requests per minute.

  • Pre-top-up: 10 requests/minute
  • Standard limit: 60 requests/minute
  • Auto-adjusts after USDT transfer

Handling 429 Errors

When you exceed the quota, the API returns an HTTP 429 status code. Your application should implement exponential backoff or simple retry logic with a delay of at least one second. Since requests are processed sequentially, a brief pause often resolves the queue congestion without requiring manual intervention or key rotation.

  • HTTP 429 status code
  • Implement exponential backoff
  • Retry after 1–2 seconds

Error Handling and Responses

Sound wave illustration for: Error Handling and Responses

The API returns standard HTTP status codes to indicate request outcomes. A 200 OK signifies successful synthesis, while 400-level errors indicate client-side issues like invalid parameters or insufficient balance. 500-level errors are rare and typically transient.

Common Error Codes

Use 400 Bad Request when the input text exceeds 4096 characters or the voice ID is invalid. A 401 Unauthorized error appears if the Bearer token is missing or expired. 429 Too Many Requests occurs when you exceed the 60 requests per minute limit per key.

  • 400: Invalid input or parameter format.
  • 401: Missing or invalid API key.
  • 429: Rate limit exceeded (60 req/min).

Response Body Format

Successful responses return the audio binary data directly, with the Content-Type matching your requested format (e.g., audio/mpeg for MP3). Error responses return a JSON object containing an 'error' field with a message and type, aiding quick debugging without parsing audio streams.

Debugging Failed Requests

If a request fails, check the error message in the JSON response for specific parameter violations. Ensure your text does not exceed the 4096 character limit per request. Failed synthesis requests are free, so no charge is applied to your balance for these errors.

Code Examples

Sound wave illustration for: Code Examples

Integrating LinguaLoop with the OpenAI SDK requires only a base URL adjustment, leveraging familiar client libraries for immediate deployment. This approach simplifies voice synthesis for edtech prototypes and production environments alike.

Python OpenAI SDK Example

Configure the client with your API key and the LinguaLoop base URL. Pass the desired voice, model, and input text to generate audio instantly.

Node.js Request Example

Use standard HTTP libraries or the OpenAI Node client. Ensure the base URL points to api.1234admin.info/v1 to route requests correctly through our infrastructure.

cURL Command Line Example

For quick testing, send a POST request with JSON body containing your text and voice preset. This method verifies connectivity before building complex integrations.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Check the response for the audio file and confirm the rate limit status.

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. ISO 639 language codes
  3. Creative Commons Attribution 4.0
  4. OpenAI API reference: create speech
  5. LibriVox public-domain audiobooks
  6. openai-node on GitHub
  7. Node.js documentation
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. MDN: Web Speech API
  10. Python documentation
  11. W3C WAI: making audio and video accessible
  12. Tether (USDT)

More on this site