Cloud TTS API: Documentation & Integration Guide

By LexiSpeak editorial team · Updated 2026-11-18

This guide helps legal teams integrate LexiSpeak’s cloud text-to-speech API into their document workflows. You will find precise specifications for converting case files, contracts, and briefs into audio for internal review or accessibility. The documentation covers authentication, endpoint structures, and voice models, ensuring your team can process large volumes of text efficiently without manual formatting overhead.

We provide concrete examples for Python developers using the OpenAI SDK and standard curl requests for quick testing. All endpoints, rate limits, and error codes are listed with exact parameters. This page is designed for technical integrators who need reliable, deterministic audio generation for legal documents, with clear instructions on handling character limits and response formats.

Cloud TTS API: Documentation & Integration Guide

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playokpk.com/v1. All requests, including audio synthesis and voice listing, are sent to this base URL. You can use this URL to configure your HTTP client or SDK for connecting to the LexiSpeak service.

Can I use the OpenAI 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.playokpk.com/v1 and using your LexiSpeak API key for authentication.

How do I rotate my API key?

You can issue a new key at any time from your account dashboard. When a new key is issued, the old one stops working immediately. This ensures secure access control for your legal team's integrations.

What is the maximum input length?

The maximum input length is 4096 characters per request. Spaces and punctuation count toward this limit. For longer documents, split the text into parts and join the resulting audio files.

Which audio formats are supported?

We support mp3, wav, opus, flac, and pcm formats. You can specify your preferred format in the response_format field of your request. This allows flexible integration with various legal transcription and playback systems.

How does the rate limit apply?

The limit is 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. Requests are processed sequentially, so high volume may cause queuing delays during peak usage.

Is SSML supported in the request?

No, SSML is not supported. You send plain text in the input field. The system does not offer phoneme dictionaries or custom pronunciation lexicons, so pronunciation relies on the voice model's default behavior.

How do I handle long legal documents?

Split your document into chunks of up to 4096 characters. Send each chunk as a separate request and join the returned audio files. This ensures you stay within the single-request character limit while processing large files.

What happens if the server returns 500?

If synthesis fails, the charge is returned in full. You can retry the request without incurring additional costs. This protects your budget during temporary service interruptions or processing errors.

Can I stream audio directly?

No, streaming is not supported. You receive the complete audio file in the response after processing. There is no WebSocket endpoint or real-time partial audio generation available for this API service.

Is there a WebSocket endpoint?

No, there is no WebSocket endpoint. The API uses standard HTTP POST requests. You receive the final audio file in the response body, not as a continuous stream of data chunks.

How do I specify the language?

Set the optional 'language' field to an ISO code. If omitted, the system guesses the language from the script (Latin text defaults to English). Explicitly setting it ensures accurate pronunciation for non-English legal terms.

What is the speed range?

The speed range is 0.25 to 4.0. You can adjust this in the request to make the speech faster or slower. This helps tailor the audio to your team's listening preferences for lengthy contract reviews.

Do I need to install extra libraries?

No extra libraries are required beyond standard HTTP clients. You can use the OpenAI SDK or any HTTP library. We do not provide a proprietary SDK, so standard tools work directly with our API endpoints.

First request

curl

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

Secure your API access with a single active key per account. Generate yours instantly at /get-api-key/ to begin sending synthesis requests to the LexiSpeak endpoint.

API Key Format

Keys follow the structure tts-.... Store this secret value in your environment variables or configuration files to prevent unauthorized access to your billing and usage data.

Bearer Token

Include the key in every request header using the standard authorization format: Authorization: Bearer tts-.... This ensures the API identifies your account and applies your current rate limits correctly.

Key Rotation

You can issue a new key at any time via the dashboard. The previous key stops working immediately, ensuring no overlap in active sessions while maintaining uninterrupted access.

Speech Endpoint

Sound wave illustration for: Speech Endpoint

Send your text to the speech endpoint to receive synthesized audio. The API accepts standard JSON payloads and returns binary audio data or structured responses. This single endpoint handles all synthesis tasks, making it straightforward to integrate into document review workflows or accessibility pipelines.

POST Request

Submit text content via a POST request to the designated endpoint. The system processes the input and returns the audio file directly in the response body. For texts exceeding 4,096 characters, split the content into smaller chunks and join the resulting audio files on your end to ensure complete playback.

  • Method: POST
  • Endpoint: https://api.playokpk.com/v1/audio/speech
  • Content-Type: application/json

JSON Body

The request body must be a valid JSON object containing the synthesis parameters. Include the text input, the chosen voice model, and the desired audio format. You may optionally specify a language code or adjust the playback speed to suit your legal document review needs.

  • input: The text to convert (max 4,096 characters)
  • model: tts-1 or tts-1-hd
  • voice: One of the 8 available presets
  • response_format: mp3, wav, opus, flac, or pcm

Required Fields

The model and input fields are mandatory for every request. Without them, the API cannot determine the synthesis engine or the content to process. You must provide a valid voice preset to define the vocal characteristics, such as 'atlas' (neutral, news) for reading contracts.

  • model: String ('tts-1' or 'tts-1-hd')
  • input: String (the text content)
  • voice: String (e.g., 'aria', 'atlas')
Speech Endpoint

Voice Models

Sound wave illustration for: Voice Models

Both tts-1 and tts-1-hd models utilize the identical underlying engine and are priced uniformly at $0.01 per 1,000 characters. You may select either model based on preference without impacting cost or processing speed. The API treats them as interchangeable options for generating legal document audio.

tts-1 Standard

Use tts-1 for standard text-to-speech synthesis. It accepts the same input parameters as the HD variant, including voice selection and speed adjustments, ensuring consistent behavior across both model labels.

tts-1 HD

The tts-1-hd model offers the same core synthesis capabilities as the standard model. It is labeled distinctly but operates on the same engine, providing no technical difference in audio fidelity or processing time compared to the standard option, though 'tts-1-hd' is the designated model ID for the higher quality tier.

Model Differences

The primary distinction is the model identifier string used in your API requests. Since both models share the same engine and price, the choice between tts-1 and tts-1-hd is purely nominal. Select the label that best fits your naming convention without expecting different audio characteristics or performance metrics.

  • Same engine for both models
  • Identical pricing: $0.01 per 1,000 characters
  • Identical processing speed and queue behavior
  • No difference in audio texture or fidelity

Response Formats

Sound wave illustration for: Response Formats

The API returns audio in MP3, WAV, OPUS, FLAC, or PCM formats, allowing you to balance file size and fidelity based on your legal review workflow. Each format serves different archival and playback needs without requiring external conversion tools.

MP3 Compatibility

MP3 is a widely supported compressed format suitable for general playback and quick listening during case file reviews. It reduces storage requirements while maintaining acceptable audio clarity for most listening devices.

WAV Quality

WAV provides uncompressed audio, preserving the full fidelity of the synthesized speech. This format is useful when you need to edit the audio or maintain the highest possible quality for internal archives without lossy compression artifacts.

PCM Raw

PCM returns raw, uncompressed audio data without container headers. This is useful for direct integration into custom audio pipelines or systems that handle their own encoding and containerization logic.

Rate Limits

Sound wave illustration for: Rate Limits

Understanding rate limits is crucial for legal teams processing large volumes of case files. Our API handles requests sequentially, ensuring consistent audio quality while managing server load efficiently.

60 Requests Per Minute

Each API key allows up to 60 requests per minute. This limit applies to all accounts once they have topped up; accounts without a top-up are limited to 10 requests per minute. It ensures reliable performance during high-volume document processing.

Initial Limit

New accounts without a top-up are limited to 10 requests per minute. This lower threshold helps manage initial server load before your account is fully funded.

Queue Behavior

Requests are processed one after another. Under heavy load, a request may wait in a queue before synthesis begins. Long texts are split into parts, which are then joined. This sequential processing ensures accurate formatting and pronunciation for legal documents.

Rate Limits

Error Handling

Sound wave illustration for: Error Handling

When processing legal documents, understanding API responses ensures smooth integration for your team. Errors are handled clearly so you can adjust your workflow without losing credit.

429 Too Many Requests

You have exceeded the 60 requests per minute limit. Your key is temporarily throttled. Reduce your request rate or implement exponential backoff in your script.

401 Unauthorized

The API key is missing, invalid, or expired. Check your Authorization header. Generate a new key in your dashboard if necessary.

500 Internal Error

A server-side issue occurred during synthesis. The request failed, but the charge is returned in full. Check the status and retry with the same input.

SDK Integration

Sound wave illustration for: SDK Integration

The API mirrors the OpenAI speech endpoint, allowing you to reuse existing OpenAI SDKs with minimal configuration. You do not need a dedicated LexiSpeak SDK; simply point the client to our API base URL.

OpenAI SDK Setup

Install the official OpenAI Python library. Initialize the client with your API key and update the base URL to our endpoint.

  • Use openai Python package
  • Standard TTS request schema

Base URL Change

Set base_url to https://api.playokpk.com/v1. This ensures all requests route through our infrastructure while using standard OpenAI request structures.

  • Base URL: https://api.playokpk.com/v1
  • Auth: Bearer tts-...

Python Example

Configure the client with your key and the custom base URL. Send a POST request with the model, input text, and voice parameters.

  • Model: tts-1 or tts-1-hd
  • Voice: aria, nova, etc.
SDK Integration

Curl Example

Sound wave illustration for: Curl Example

The API accepts text via a standard POST request. This method is ideal for quick testing or simple scripts where you need to convert a short legal clause or contract section into speech without writing a full application.

You can verify connectivity and voice selection immediately using the command line. The response returns the audio file directly, ready for playback or storage.

Basic Request

Send a POST request to the speech endpoint with your JSON payload. Ensure the text does not exceed 4,096 characters.

```bash curl -X POST https://api.playokpk.com/v1/audio/speech \ -H "Authorization: Bearer tts-your-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Please review the attached contract.", "voice": "atlas", "response_format": "mp3"}' \ --output speech.mp3 ```

  • Use tts-1 or tts-1-hd (same engine and price).
  • Set voice to one of the eight presets like atlas for neutral news tone.
  • Specify response_format as mp3, wav, opus, flac, or pcm.

Headers

Include your API key in the Authorization header. Replace tts-your-key with your actual key from the dashboard.

Set Content-Type to application/json to ensure the server correctly parses the input fields.

  • Authorization: Bearer tts-...

Response Body

Upon success, the response contains the raw audio binary data. Save this output to a file with the appropriate extension.

If the request fails, the response body will contain an error object with details like insufficient balance or invalid parameters.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. These comprehensive legal documents streamline compliance for our large distributed teams across multiple jurisdictions.

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. Python documentation
  3. Tether (USDT)
  4. OpenAI API reference: create speech
  5. Creative Commons Attribution 4.0
  6. ISO 639 language codes
  7. IETF RFC 7845: Ogg Opus
  8. FFmpeg documentation
  9. LibriTTS-R corpus (OpenSLR 141)
  10. curl documentation
  11. TRON developer hub: TRC-20
  12. MDN: Web Speech API

More on this site