API Documentation for Legal Text-to-Speech

By VerdictRead editorial team · Updated 2026-11-18

This documentation provides the technical reference for VerdictRead’s text-to-speech API, designed for legal departments requiring precise, auditable audio conversion of case files and briefs. It details the standard JSON request structure, authentication methods, and integration patterns necessary for high-volume processing workflows.

Readers will find concrete specifications for endpoints, parameter limits, and error handling, along with ready-to-use code examples in Python and Node.js. This guide supports engineers and developers integrating the API into existing document management systems.

API Documentation for Legal Text-to-Speech

Frequently asked questions

How do I authenticate my API requests?

Include the header Authorization: Bearer tts-... with your unique API key in every request. Keys are issued per account and must be sent with each POST to the speech endpoint. Ensure the key is active and correctly formatted to avoid authentication errors during your legal document processing workflow.

What is the maximum length for input text?

Each request supports a maximum of 4096 characters for the input field. For longer case files, split the text into chunks of this size and join the resulting audio files. This limit applies per API call, not per document, so manage chunking logic in your application.

Can I use the OpenAI SDK for this API?

Yes. The request shape matches the OpenAI speech endpoint. Configure your OpenAI SDK by changing the base_url to https://api.playtko7.com/v1 and providing your VerdictRead API key. This allows you to use official OpenAI SDKs seamlessly without writing custom HTTP client code for your legal integration.

How do I handle rate limits in my application?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Process requests sequentially or implement a queue. Under load, requests may wait in a queue. Monitor your usage via the dashboard and adjust your batch processing speed to stay within these limits.

What happens if the API returns an error?

If synthesis fails, the charge is returned in full. Failed requests do not deduct from your balance. Ensure your application handles HTTP errors appropriately and retries if necessary, knowing that valid failures will not impact your character count or financial balance for that specific attempt.

Is the API key unique per account?

Yes, each account has one active key. When you issue a new key, the old one stops immediately. This ensures strict security for legal departments, allowing you to revoke access instantly by generating a new key without needing complex permission management or multiple key rotations simultaneously.

Can I change the API key after issuing it?

Yes, you can issue a new key at any time. The previous key becomes invalid immediately upon issuing the new one. This allows for secure rotation of credentials in your legal tech stack without downtime, ensuring that only the current active key is used for API calls.

What are the supported audio formats?

You can specify mp3, wav, opus, flac, or pcm via the response_format field. These formats cover standard legal archiving needs. Select the format that best suits your document management system's requirements, keeping in mind file size differences between lossy and lossless options.

How do I specify the language for non-English text?

Set the optional language parameter to the ISO code. If omitted, the system guesses from the script, defaulting Latin text to English. For non-English Latin-script text, always set the language explicitly to ensure accurate pronunciation and compliance with your specific jurisdictional audio requirements.

Is there a WebSocket endpoint for real-time streaming?

No. The API is a standard REST endpoint for generating audio files. There is no WebSocket support or real-time partial audio streaming. You must wait for the full audio file to be generated and returned in the response before processing or storing the legal document audio.

Do I need an account to test the API?

Yes, you need an account to obtain an API key. Sign up via Google or email on the /get-api-key/ page. Google sign-ups receive a $0.50 trial credit valid for 7 days, allowing you to test the API immediately without immediate payment, though email accounts start without credit.

How do I retrieve the list of available voices?

Send a GET request to /v1/voices. This endpoint returns details on available voices, languages, formats, and price. Use this to configure your application dynamically, selecting from the eight presets like Aria, Nova, or Felix based on the desired tone for your legal audio outputs.

What is the difference between tts-1 and tts-1-hd?

Both models use the same engine and price. You can use either tts-1 or tts-1-hd in your requests without any difference in billing or audio quality, allowing flexibility in your API configuration without affecting your legal budget.

First request

curl

curl https://api.playtko7.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.playtko7.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.playtko7.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 API Keys

Sound wave illustration for: Authentication and API Keys

Access the /get-api-key/ page to generate your API key via Google sign-in or email registration. Each account receives one active key, which appears on the dashboard alongside your balance and usage statistics. The key enables authenticated requests to the speech endpoint.

Keys are unique to your account and site. You can rotate keys immediately if needed, with the old key invalidating instantly. This ensures strict control over which team members or systems can access your legal audio generation resources.

Generate your API key

Generate your API key

Navigate to the /get-api-key/ page and sign in using Google or your email credentials. Upon authentication, your active API key is displayed. Use this key to authorize all subsequent API calls. If you lose access, generate a new key, which immediately deactivates the previous one.

  • Sign up via Google or email/password on /get-api-key/
  • One active key per account; new keys invalidate old ones instantly
  • Key format: Bearer tts-...

Bearer token format

Bearer token format

Include your API key in the HTTP header as a Bearer token. The header must read: Authorization: Bearer tts-<your-key>. This standard format ensures compatibility with the OpenAI SDKs and any standard HTTP client used by your legal tech stack.

  • Header: Authorization: Bearer tts-...
  • No additional prefixes or suffixes required
  • Case-sensitive token value

Key rotation policy

Generate a new key from your dashboard at any time. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation for security audits or personnel changes without downtime in your audio processing pipeline.

Endpoint Structure

Sound wave illustration for: Endpoint Structure

The API provides three primary endpoints for legal document processing. The speech generation endpoint handles text-to-audio conversion, while the voices and models endpoints expose available configuration options. All requests use standard JSON bodies and require Bearer token authentication in the header.

Each endpoint serves a specific function in the workflow: generating audio from case files, listing available voice presets, and confirming model capabilities. The structure mirrors standard industry patterns, allowing legal engineering teams to integrate quickly using existing HTTP clients or the OpenAI SDK.

POST /v1/audio/speech

This endpoint converts input text into audio files. Send a JSON body containing the text, desired voice, and format. The API returns the audio file directly in the response body.

Ensure text does not exceed 4096 characters. For longer briefs, split the text into chunks and concatenate the resulting audio files. The endpoint supports multiple output formats including MP3, WAV, OPUS, and FLAC.

  • Input: JSON object with 'model', 'input', 'voice', and 'response_format' fields.
  • Output: Audio file bytes or error JSON.
  • Max input length: 4096 characters.

GET /v1/voices

Retrieve a list of all available voice presets and their attributes. This endpoint returns details for eight voices, including gender, tone description, and supported languages.

Use this endpoint to dynamically select the appropriate voice for different types of legal documents, such as 'atlas' for neutral news-style readings or 'sage' for instructional content.

  • Returns voice ID, name, gender, and language support.
  • Lists all 8 presets: aria, nova, luna, sage, felix, milo, atlas, orion.
  • Indicates supported languages (23 total).

GET /v1/models

Fetch available model identifiers. Currently, 'tts-1' and 'tts-1-hd' are supported. Both use the same engine and pricing but offer different audio quality options.

Use this endpoint to verify model availability before generating audio. The models endpoint ensures compatibility with your integration setup.

  • Returns list of available model IDs.
  • Supports 'tts-1' and 'tts-1-hd'.
  • No additional configuration required.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts two model identifiers, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing structure. You select the model via the JSON body to initiate synthesis. Each request processes text up to a strict 4096-character limit, counting all spaces and punctuation.

For voice and language configuration, you must specify one of eight presets. The system supports 23 languages, including English, German, and Japanese. If the language parameter is omitted, the API guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language code is recommended for non-English inputs to ensure accuracy.

Model selection (tts-1, tts-1-hd)

Both model identifiers trigger the same synthesis engine with identical pricing. There is no performance difference between them for legal document processing; select based on preference without affecting cost or output quality.

  • - tts-1: Standard model identifier
  • - tts-1-hd: High-definition model identifier
  • - Same engine and price for both

Input text length limit

Each API call accepts a maximum of 4096 characters. This limit applies to the input string, including spaces and punctuation marks. For case files exceeding this length, split the text into parts, synthesize each separately, and join the resulting audio files.

  • - Maximum 4096 characters per request
  • - Spaces and punctuation count toward the limit
  • - Split longer briefs into manageable chunks

Voice and language codes

Select from eight specific voice presets (e.g., aria, atlas, felix). The language parameter accepts optional ISO codes. Without it, the system defaults to English for Latin scripts. Set the language explicitly for non-English Latin text to avoid misidentification.

All voices support all 23 listed languages. Ensure the selected voice matches the required tone for your legal department's standards, such as neutral for news-style updates or calm for instructional content.

  • - 8 voice presets available
  • - Supports 23 languages
  • - Default language is English for Latin text
  • - Explicit language code recommended for non-English inputs

Response Formats

Sound wave illustration for: Response Formats

The API returns synthesized audio files in the requested format, ensuring compatibility with your legal review systems. Each response includes the binary audio data and metadata confirming the character count and voice used. Failed requests return no charge and clear error codes.

Audio files are generated on-demand and not stored by the server, aligning with strict data retention policies. The output format determines the file size and quality, allowing legal teams to balance storage efficiency with playback requirements.

MP3 output

MP3 is a widely supported format for legal audio archives. It provides efficient compression suitable for long case files and briefs, reducing bandwidth usage during bulk processing.

This format is ideal for integration with standard document management systems that require lightweight audio attachments for accessibility compliance.

  • Default response format

WAV output

WAV delivers uncompressed, lossless audio. This is suitable for archival purposes where bit-perfect fidelity is required for evidentiary audio.

Use this format when downstream legal tools require standard PCM audio without decoding artifacts.

OPUS and FLAC options

OPUS offers high-quality compression with lower file sizes than MP3, suitable for rapid review workflows where storage is a constraint. FLAC provides lossless compression, reducing file size compared to WAV while maintaining audio integrity.

Choose FLAC when long-term archival storage costs matter but lossless quality is mandated by internal compliance standards.

  • Lossless compression option

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

The API enforces a standard limit of 60 requests per minute per active key. This cap ensures stable processing for legal teams generating bulk case files or briefs without overwhelming the synthesis engine. High-volume document conversion remains predictable under normal operational conditions.

60 requests per minute

Each API key is allocated a maximum of 60 requests per minute. This throughput is sufficient for most legal departments processing standard-length briefs. The limit resets every minute, allowing consistent batch uploads for audio conversion of case documents.

10 requests per minute initially

New accounts start with a reduced limit of 10 requests per minute. This restriction applies until the first top-up is processed. Once USDT payment is confirmed on the TRON network, the limit automatically increases to the standard 60 requests per minute.

Queue handling under load

Requests are processed sequentially. Under heavy load, synthesis may wait in a queue before execution begins. Longer texts typically generate at roughly real-time speed, while short phrases take a few seconds. Plan batch uploads to avoid latency during peak usage.

  • Requests are processed one after another
  • Short phrases take a few seconds
  • Long texts generate at roughly real-time speed
Rate Limits and Throttling

Error Handling

Sound wave illustration for: Error Handling

Error responses follow standard HTTP conventions, allowing your legal compliance systems to parse failures automatically. Each error object includes a code and a descriptive message, ensuring clear audit trails for failed synthesis jobs without requiring manual intervention.

Invalid input text

The API rejects inputs exceeding 4096 characters or containing unsupported binary data. Ensure your document parser strips non-UTF8 characters before submission to prevent silent truncation of case files.

  • Maximum length: 4096 characters per request
  • Unsupported format: HTTP 400 Bad Request
  • Retry strategy: Split long briefs into segments

Insufficient balance

Requests fail immediately if the account balance cannot cover the character cost. Since failed requests are refunded, ensure your billing logic checks balance before high-volume batch processing of deposition transcripts.

  • Charge: $0.01 per 1,000 characters
  • Result: HTTP 402 Payment Required
  • Action: Top up via USTRC-20

Rate limit exceeded

New accounts start with a 10 requests/minute limit, scaling to 60 requests/minute after the first top-up. Exceeding this triggers a 429 status; implement exponential backoff to handle queue delays during peak processing.

  • Standard limit: 60 requests per minute
  • Initial limit: 10 requests per minute
  • Response: HTTP 429 Too Many Requests

SDK Integration

Sound wave illustration for: SDK Integration

The API mirrors the OpenAI speech endpoint structure, allowing legal engineering teams to leverage existing infrastructure without custom wrappers. By adjusting the base URL, your current OpenAI SDK implementations for text-to-speech can immediately route requests to VerdictRead's high-volume processing cluster.

OpenAI SDK compatibility

Use any official OpenAI SDK (Python, Node.js, etc.) by simply redirecting the endpoint. The request shape is identical, ensuring that your existing parsing logic for audio responses remains intact during migration.

Base URL configuration

Set your SDK's base_url to https://api.playtko7.com/v1. This directs all POST and GET calls to the correct endpoint while maintaining standard authentication headers.

Standard JSON body

Pass parameters in a standard JSON object. Include model, input, voice, and response_format. The API expects these fields exactly as defined in the OpenAI specification, supporting up to 4096 characters per payload.

Code Examples

Sound wave illustration for: Code Examples

Below are concrete integration examples for generating legal audio from text inputs. Each snippet demonstrates the required JSON structure and authentication headers for immediate deployment in your compliance pipeline.

cURL request example

Use this command to generate speech directly. Replace YOUR_API_KEY with your Bearer token from the dashboard.

  • curl -X POST https://api.playtko7.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Case file summary...", "voice": "sage", "response_format": "mp3"}'

Python SDK example

Install the OpenAI SDK and configure the base URL to point to our API endpoint. This allows you to use standard Python libraries for legal document processing.

  • import openai client = openai.OpenAI(base_url="https://api.playtko7.com/v1", api_key="YOUR_API_KEY") response = client.audio.speech.create(model="tts-1", voice="sage", input="Legal brief text", response_format="mp3") with open("brief.mp3", "wb") as f: f.write(response.content)

Node.js integration

Configure the Node.js OpenAI client with the same base URL. This ensures compatibility with existing Node.js legal tech stacks for automated brief generation.

  • const openai = require('openai'); const client = new openai.OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://api.playtko7.com/v1' }); const audio = await client.audio.speech.create({ model: 'tts-1-hd', voice: 'atlas', input: 'Summary text', response_format: 'wav' });

Listen to the 8 voices

Each sample below was generated by this API from the same sentence.

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

More on this site