API Documentation for Text-to-Speech Integration

By LinguaPulse editorial team · Updated 2026-11-18

This guide provides the essential details for integrating LinguaPulse’s text-to-speech API into your SaaS notifications, IVR systems, and in-app voice interfaces. You will find concrete examples for authentication, endpoint usage, and parameter configuration, enabling product teams to move quickly from setup to production without unnecessary complexity.

We cover practical workflows, including handling long texts, managing rate limits, and troubleshooting common errors. By following these step-by-step instructions, you can reliably generate clear, licensed audio files using standard HTTP requests or the OpenAI SDK, ensuring seamless integration with your existing infrastructure.

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.play3n3.com/v1. You send POST requests to https://api.play3n3.com/v1/audio/speech to generate audio. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.

How do I authenticate requests?

Include your API key in the request header as Authorization: Bearer tts-<your_key>. Each account has one active key. You can issue a new key at any time, which immediately invalidates the previous one, ensuring secure access to the TTS service.

Which models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing. You can select either model in your request body to generate audio. The choice does not affect the cost.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.play3n3.com/v1 and using your site-specific key. The request shape matches the OpenAI speech endpoint, allowing you to integrate our API into existing workflows without rewriting your client code.

What is the character limit per request?

Each request supports up to 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, and join the resulting audio files.

How do I change the voice speed?

Adjust the speed parameter in your request body. Valid values range from 0.25 to 4.0. The default speed is 1.0. This allows you to slow down narration for clarity or speed up content for concise notifications and IVR systems.

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. Exceeding limits results in immediate rejection until the window resets.

Are failed requests charged?

No, failed requests are free. If synthesis fails, the charge is returned in full. You only pay for successful audio generation. This ensures you are not billed for errors or network issues during the text-to-speech conversion process.

How do I handle long texts?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the /v1/audio/speech endpoint. Then, join the returned audio files to create a continuous audio track. This approach handles texts of any length.

What formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the response_format field in your request body. This flexibility allows integration with various players and systems, from web browsers to telephony interfaces.

Can I stream the audio?

No, streaming is not supported. The API returns the complete audio file in the response after synthesis is finished. Requests are processed sequentially, so longer texts may take time. You must wait for the full response before playing or storing the audio.

Is SSML supported?

No, SSML is not supported. You can only pass plain text in the input field. There are no emotion tags, phoneme dictionaries, or custom pronunciation lexicons available. The system guesses the language from the script if not explicitly set.

How do I rotate my API key?

Issue a new key from your account dashboard at /get-api-key/. The new key becomes active immediately, and the old one stops working at once. This allows you to revoke access to compromised keys without downtime for your applications.

What is the response structure for errors?

Errors return a standard HTTP error code and a JSON body with an error message. The specific structure follows standard API error conventions. Failed requests are free: if synthesis fails, the charge is returned in full.

First request

curl

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

Access the API by generating a key on the /get-api-key/ page. Authenticate every request using a Bearer token in the Authorization header.

Maintain a single active key per account. You can rotate keys at any time, ensuring the previous key stops immediately.

Generating your API key

Generating your API key

Create your key via the /get-api-key/ page using Google or email. The dashboard displays your key, balance, and usage stats.

Bearer token authorization header

Bearer token authorization header

Include Authorization: Bearer tts-... in every request header. The key grants access to your account's quota and billing.

Rotating keys and invalidation

Issue a new key anytime from the dashboard. The old key becomes invalid instantly, providing immediate security control.

Endpoints Overview

Sound wave illustration for: Endpoints Overview

The API provides three core endpoints for generating speech and managing resources. The primary endpoint handles audio synthesis, while the other two provide metadata about available voices and model configurations.

POST /v1/audio/speech

This is the main endpoint for converting text into audio files. Send a JSON body with the text, voice selection, and format preference to receive a binary audio response.

GET /v1/voices

Retrieve a list of all available voice presets, their associated languages, and supported audio formats. This helps you select the right voice for your SaaS notifications or IVR systems.

GET /v1/models

Fetch the current model versions and their specifications. Use this to ensure compatibility with your integration setup before sending synthesis requests.

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis engine and input constraints for each TTS request. The API accepts a fixed set of parameters that define voice, language, and output structure. Understanding these limits ensures consistent audio generation without unexpected failures.

Model selection: tts-1 vs tts-1-hd

Both "tts-1" and "tts-1-hd" use the same underlying engine and incur identical pricing. The choice does not affect voice quality or character count billing, allowing you to switch models without changing your integration logic or cost expectations.

Input text limit: 4096 characters

Each API call accepts a maximum of 4096 characters, including spaces and punctuation. For longer texts, split the input into chunks and join the resulting audio files client-side. This approach keeps individual requests lightweight and predictable.

Voice presets and language codes

Select one of eight voice presets (e.g., aria, nova, atlas) and optionally specify an ISO language code. If omitted, the system guesses the language, defaulting to English for Latin script. Explicitly setting the language ensures correct pronunciation for non-English texts.

Available languages include Arabic, Chinese, English, German, Japanese, Spanish, and others. All voices can speak any supported language, providing flexibility for international SaaS notifications and IVR systems.

  • 8 voice presets: aria, nova, luna, sage, felix, milo, atlas, orion
  • Supports 23 languages including English, Spanish, German, Japanese, and Hindi
  • Language detection defaults to English if not specified for Latin script

Response Formats

Sound wave illustration for: Response Formats

The API returns audio data as a binary response in the requested format. Supported output types include MP3, WAV, OPUS, FLAC, and PCM. You select the desired format using the response_format parameter in your request body.

Supported formats: MP3, WAV, OPUS, FLAC, PCM

Choose MP3 for standard web delivery or WAV for high-quality archival. OPUS offers efficient compression, while FLAC provides lossless quality. PCM returns raw uncompressed audio data.

Audio binary response

The response body contains the raw audio bytes directly. There is no JSON wrapper around the audio data. Your client must handle the binary stream appropriately based on the selected format.

Error response structure

Errors return a JSON object with an error field containing type, message, and code. Failed synthesis requests incur no charge, and the cost is returned to your balance automatically.

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

LinguaPulse enforces a hard limit of 60 requests per minute per API key. This quota applies to all synthesis endpoints and ensures stable performance for your SaaS notifications or IVR systems. Exceeding this limit results in immediate rejection until the window resets.

60 requests per minute per key

The 60 RPM limit applies per key. Requests are processed one after another, so under load a request may wait in a queue. Plan your integration to handle standard HTTP 429 responses gracefully during brief spikes.

  • Limit: 60 requests/minute/key
  • Applies to POST /v1/audio/speech
  • Sequential processing may cause minor latency

10 requests per minute before first top-up

New accounts start with a reduced quota of 10 requests per minute. This applies immediately upon key creation, regardless of whether you have a free trial balance. You must perform a top-up to increase this to the standard 60 RPM.

  • Initial quota: 10 RPM
  • Requires a top-up to upgrade
  • Applies immediately after key generation

Handling rate limit errors

When you exceed the limit, the API returns an HTTP 429 status code. Implement exponential backoff in your client code to retry requests automatically. Failed requests are free: if synthesis fails, the charge is returned in full.

  • HTTP 429 status code
  • Use exponential backoff for retries
  • No charge for rate-limited requests
Rate Limits and Quotas

SDK Integration

Sound wave illustration for: SDK Integration

Integrate LinguaPulse into your SaaS notifications or IVR systems using existing tools. The API mirrors the OpenAI speech endpoint structure, allowing you to reuse familiar SDKs with minimal configuration changes.

Use the OpenAI SDK by overriding the base_url to https://api.play3n3.com/v1. Alternatively, send standard JSON payloads via plain HTTP or use the provided curl command for immediate testing.

Using the OpenAI SDK with custom base_url

Configure your client to point to our API base URL. Pass your API key in the Authorization header. The request body shape matches OpenAI's speech endpoint, ensuring compatibility with official SDKs.

Set model to tts-1 or tts-1-hd. Define the voice preset and input text. The SDK handles serialization automatically, returning the audio binary directly.

  • Base URL: https://api.play3n3.com/v1
  • Auth Header: Authorization: Bearer tts-...
  • Supported SDKs: Official OpenAI SDKs

Plain HTTP requests example

Send a POST request to /v1/audio/speech with a JSON body. Include the model, voice, input, and response_format fields. The API returns the audio file in the requested format.

Ensure the Authorization header contains your active Bearer token. If the synthesis fails, the response indicates the error without charging your balance.

  • Content-Type: application/json
  • Authorization: Bearer YOUR_API_KEY
  • Body: {"model": "tts-1", "voice": "nova", "input": "Hello", "response_format": "mp3"}

Ready curl command example

Use this command to test integration immediately. Replace YOUR_API_KEY with your key from the dashboard. Replace nova with any of the 8 available voices.

The command sends the text "Welcome to LinguaPulse" and saves the resulting MP3 file. Adjust --data fields for different voices or formats like WAV or OPUS.

  • curl -X POST https://api.play3n3.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • --data '{"model":"tts-1","voice":"nova","input":"Welcome to LinguaPulse","response_format":"mp3"}'

Handling Long Texts

Sound wave illustration for: Handling Long Texts

The API accepts up to 4,096 characters per request. For longer texts, split your input into chunks of this size and send each as a separate POST request to /v1/audio/speech. Each call returns a distinct audio file.

Collect the returned audio files in order and join them client-side. Split into parts of up to 4096 characters and join the audio files.

Splitting text into chunks

Divide your text into segments not exceeding 4,096 characters. Count spaces and punctuation as characters. Send each segment individually to the speech endpoint.

Joining audio files client-side

Receive multiple audio files from separate requests. Concatenate them in the correct order using your preferred audio library or tool. This method keeps the workflow transparent and avoids server-side formatting issues.

Managing queue delays

Requests are processed sequentially. Under load, you may experience delays. Short phrases take a few seconds; longer texts take roughly real-time duration. Plan your integration to handle asynchronous responses gracefully.

Troubleshooting Common Errors

Sound wave illustration for: Troubleshooting Common Errors

Even with correct setup, integration hiccups occur. This section covers three frequent issues: authentication failures, input limits, and voice selection errors, with immediate remediation steps.

Invalid API key

A 401 error indicates the provided key is missing, expired, or incorrect. Verify the Authorization: Bearer tts-... header matches your key from /get-api-key/. If you issued a new key, the old one stops immediately.

  • Check for trailing spaces in the key string.
  • Ensure no https:// prefix is included in the token.

Text too long

The API rejects inputs exceeding 4096 characters. Split your text into smaller chunks client-side, process each request, and join the resulting audio files. Short phrases may also take a few seconds due to queue processing under load.

  • Count spaces and punctuation as characters.
  • Monitor queue delays if sending many requests concurrently.

Voice not found

A 400 error occurs if the voice parameter is not one of the eight presets (e.g., aria, nova, felix). Fetch the valid list via GET /v1/voices before synthesis. Any voice can speak any of these languages.

  • Verify ISO language codes match the voice capabilities.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Accurate language detection prevents unnatural accents and improves user experience.

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

More on this site