API Documentation for Legal Audio Generation

By ClarityVoice editorial team · Updated 2026-11-18

This documentation provides the technical specifications for ClarityVoice’s text-to-speech API, designed specifically for product teams managing legal content. You will find precise details on authentication, request structures, and parameter options to integrate audio generation directly into your compliance workflows. Every field is mapped to our API’s capabilities, ensuring your team can reliably convert dense legal text into clear, listenable audio files.

Here you will learn how to authenticate with a Bearer token, structure JSON payloads, and handle responses using standard HTTP methods. The guide covers supported formats like MP3 and FLAC, explains rate limits of 60 requests per minute, and details error handling for failed syntheses. Use this reference to build robust integrations that meet the specific demands of legal documentation, from character-accurate billing to voice selection.

API Documentation for Legal Audio Generation

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email with a password. Your account is specific to this site. Once registered, you will see your active API key, balance, and usage details directly on the dashboard.

Can I use the OpenAI SDK?

Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base URL to https://api.playvt443.com/v1 and providing your site-specific key via the Authorization header.

What is the base URL?

The API base URL is https://api.playvt443.com/v1. You send POST requests to /audio/speech and GET requests to /voices or /models using this base path for all interactions with the text-to-speech service.

How do I set the language?

Include the optional language field in your request body with an ISO code. If omitted, the system guesses the language from the script, defaulting Latin text to English. Set it explicitly for non-English Latin-script text to ensure accuracy.

What models are available?

Two models are available: "tts-1" and "tts-1-hd". Both use the same engine and pricing. You can list all available models by sending a GET request to the /v1/models endpoint to see current configurations.

Can I adjust the speed?

Yes, you can set the speed parameter between 0.25 and 4.0. This allows you to control the playback rate of the generated audio. The default speed is typically set to 1.0 for natural pacing.

How do I split long texts?

The API accepts up to 4096 characters per request. For longer texts, you must split the input into parts of this size, send separate requests, and join the resulting audio files on your end to create the final document.

Is there an SSML endpoint?

No, there is no SSML endpoint. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You control pacing and emphasis primarily through text structure and the speed parameter rather than markup.

What happens if I hit the rate limit?

The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so under load, your request may wait in a queue. Exceeding the limit will result in standard HTTP rate limit errors.

Do I need to install a specific SDK?

No, you do not need a specific SDK. You can use the official OpenAI SDKs by adjusting the base URL, or use plain HTTP requests. There is no proprietary mobile SDK or WordPress plugin required for integration.

How do I handle errors?

Failed requests are free, and the charge is returned in full. You should handle standard HTTP error codes returned by the API. Ensure your text is under 4096 characters and your key is valid to avoid common issues.

Is the API RESTful?

Yes, it is a standard REST API. You use POST for generating speech at /audio/speech and GET for retrieving resources like voices at /voices. It follows standard HTTP methods and JSON request/response structures.

Can I stream the audio?

No, there is no streaming or WebSocket support. The API returns the complete audio file in the response body. You receive the full file once generation is complete, rather than receiving partial audio chunks in real-time.

How do I rotate my key?

You can issue a new API key at any time from your account dashboard. When you generate a new key, the old one stops working immediately. This allows for instant rotation without any downtime or manual deactivation steps.

First request

curl

curl https://api.playvt443.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.playvt443.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.playvt443.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 Bearer token. Include Authorization: Bearer tts-... in every request header to authenticate your account.

Bearer token key

Bearer token key

Use your unique API key in the Authorization header. This token identifies your account and tracks character usage for billing.

One active key per account

One active key per account

Each account holds exactly one active key. If you generate a new key, the old one stops working immediately.

Rotate keys instantly

Rotate keys instantly

Generate a new key anytime from your dashboard. The transition is immediate, ensuring zero downtime for your legal audio workflows.

Quickstart with Curl

Sound wave illustration for: Quickstart with Curl

Send a POST request to the speech endpoint with your Bearer token in the Authorization header. The API processes your legal text and returns an audio file directly in the response body, enabling immediate playback or storage without additional network calls.

First API request

Use the following curl command to generate audio from a short legal clause. Replace YOUR_API_KEY with your key from the dashboard.

  • ```bash curl -X POST "https://api.playvt443.com/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "This agreement is binding.", "voice": "sage"}' \ -o output.mp3 ```

JSON body structure

The request body requires the model, input, and voice fields. You may optionally specify response_format, speed, and language. Text is limited to 4096 characters per request.

Response format

The API returns the audio file directly with the appropriate content type (e.g., audio/mpeg). Failed requests return a JSON error object but incur no charge.

OpenAI SDK Compatibility

Sound wave illustration for: OpenAI SDK Compatibility

The API mirrors the OpenAI speech endpoint structure, allowing product teams to swap providers without rewriting core logic. By pointing the OpenAI SDK to our base URL, you leverage familiar client libraries for legal audio generation.

Standard method calls remain unchanged. You simply pass the audio input, voice preset, and desired format. The SDK handles the serialization and transmission, ensuring your legal documentation workflows integrate seamlessly with existing infrastructure.

Base URL configuration

Update your SDK client’s base_url to https://api.playvt443.com/v1. This single change directs all requests to our TTS engine while maintaining compatibility with standard OpenAI parameters.

  • Set base_url to https://api.playvt443.com/v1
  • Use your Bearer token for authentication
  • No code changes required for standard fields

Standard method calls

Invoke the audio.speech method as you would with OpenAI. Pass model, input, voice, and response_format in the JSON body. The API returns the audio file directly, ready for playback or storage in your legal content system.

SDK compatibility

The official OpenAI SDKs work out-of-the-box. You only need to adjust the base URL and inject your API key. This reduces integration time for teams already using OpenAI-compatible tools for document processing.

Note: This is not the official OpenAI service. We use a compatible endpoint shape, but rate limits and billing are specific to ClarityVoice.

  • Official OpenAI SDKs supported
  • No custom client library needed
  • Compatible with standard JSON bodies

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts two model identifiers, tts-1 and tts-1-hd, which share the same engine and pricing. This simplifies integration for legal teams who need consistent audio quality across different compliance documentation tiers without managing complex model selection logic.

Input text is limited to 4096 characters per request. For lengthy legal contracts, split the text into chunks and join the resulting audio files. Each request is processed sequentially, so under load, synthesis may queue behind previous submissions.

Model selection (tts-1)

Specify tts-1 or tts-1-hd in the model field. Both use the identical synthesis engine and incur the same rate of $0.01 per 1,000 characters. This uniformity ensures that billing remains predictable regardless of which identifier you choose for your legal audio generation.

There is no performance or quality difference between the two identifiers. Use either one interchangeably. The API ignores minor variations in casing, but standardizing on tts-1 reduces cognitive load for your development team.

  • - Both models use the same underlying synthesis engine
  • - Identical pricing: $0.01 per 1,000 characters
  • - No functional difference in audio output quality

Voice presets

Select from eight licensed voices based on real recordings. For legal content, sage offers a calm, instructional tone ideal for instructional compliance videos, while atlas provides a neutral, news-like delivery for standard corporate announcements. aria serves as a warm narrator for customer-facing explanations.

Each voice supports all 23 languages. If the language field is omitted, the system guesses from the script, defaulting to English for Latin text. For non-English Latin scripts, explicitly set the language code to ensure accurate pronunciation of legal terminology.

  • - aria: warm, clear narrator
  • - nova: bright, upbeat
  • - luna: soft, storytelling
  • - sage: calm, instructional
  • - felix: energetic, promo
  • - milo: friendly, conversational
  • - atlas: neutral, news
  • - orion: deep, documentary

Speed adjustment

Adjust playback speed between 0.25 and 4.0 using the speed parameter. Faster speeds compress the audio, reducing file size and playback time for large document libraries. Slower speeds enhance clarity for complex legal jargon or non-native speakers reviewing contracts.

The default speed is 1.0. Adjusting speed does not affect the character count billing. Whether you listen at 2x speed or 0.5x, the input text length determines the cost. This allows teams to optimize listening experience without impacting API charges.

Supported Formats

Sound wave illustration for: Supported Formats

The API supports five audio formats: MP3, WAV, Opus, FLAC, and PCM. MP3 provides compressed audio suitable for most playback scenarios, though it is not explicitly the default format. WAV delivers uncompressed quality for professional editing workflows. Opus offers efficient compression for web delivery. FLAC ensures lossless fidelity for archival purposes.

All formats are generated on-demand during synthesis. Choose the format that best matches your storage and playback requirements. The response body contains the raw audio bytes in the selected format.

MP3 output

MP3 is a common format for most use cases. It provides a good balance between file size and audio quality. Ideal for web players and mobile applications.

Use MP3 when storage efficiency matters. The compressed format reduces bandwidth usage without significant quality loss for speech content.

  • Compressed format
  • Small file size
  • Wide compatibility

WAV quality

WAV provides uncompressed audio data. It preserves the full fidelity of the generated speech. Suitable for professional editing and post-production workflows.

Choose WAV when you need raw audio data.

  • Uncompressed audio
  • High fidelity
  • Editing friendly

FLAC lossless

FLAC offers lossless compression. It retains all audio data. Ideal for archival storage.

Use FLAC when you need perfect quality.

  • Lossless compression
  • Archival quality
  • Open format

Rate Limits

Sound wave illustration for: Rate Limits

Rate limits ensure stable generation for your legal document workflows. Your API key allows 60 requests per minute under normal operation, providing sufficient throughput for batch processing of compliance materials.

60 requests per minute

Once your account is active, you can process up to 60 requests per minute. This limit applies per key and is designed to handle typical volume spikes without compromising service stability.

10 req/min initial

New accounts start with a conservative limit of 10 requests per minute. This prevents resource exhaustion during the initial trial phase. The limit automatically increases to 60 req/min after your first top-up.

  • No manual upgrade required
  • Instant change upon top-up

Queue handling

Requests are processed sequentially. Under heavy load, additional requests may wait in a queue. Short phrases take a few seconds; longer texts generate at roughly real-time speed (25 characters per second).

Error Handling

Sound wave illustration for: Error Handling

Errors are returned as standard HTTP status codes with a JSON body explaining the cause. Common issues include 400 Bad Request for invalid parameters and 429 Too Many Requests when you exceed the 60 requests per minute limit.

Implement exponential backoff to handle transient network issues or temporary queue delays. Since requests are processed sequentially under load, short waits between retries prevent overwhelming the API during high traffic.

Common error codes

The API returns clear error codes to help you debug integration issues quickly.

  • 400 Bad Request: Invalid JSON, missing input, or unsupported voice/model combination.
  • 401 Unauthorized: Invalid or expired API key.
  • 429 Too Many Requests: You have exceeded the rate limit of 60 requests per minute.
  • 500 Internal Server Error: Temporary processing failure; retry after a short delay.

Retry logic

For 429 errors, wait and retry using exponential backoff. For 500 errors, a single retry is often sufficient.

  • Do not retry 400 errors immediately; they indicate a configuration mistake.
  • Implement a maximum retry count (e.g., 3 attempts) to avoid infinite loops.

Failed request billing

If synthesis fails due to a server error, the charge is returned in full. You are only billed for successfully completed audio generations.

Voices Endpoint

Sound wave illustration for: Voices Endpoint

The GET /v1/voices endpoint returns the full list of available audio presets, their supported languages, and associated formats. This allows legal product teams to programmatically select the most appropriate voice tone for different types of compliance documentation or client communications without manual lookup.

You can verify language support and available output formats directly through this endpoint, ensuring your integration handles the 23 supported languages correctly. This data is essential for automating voice selection based on the text's language or regional requirements.

List available voices

Retrieve the eight distinct voice presets, categorized by gender and tone. Each voice has a specific name, such as 'aria' for warm narration or 'atlas' for neutral news delivery, allowing precise control over the audio output.

Each voice supports all 23 languages. You can filter the list by voice ID or name to quickly identify the best preset for a specific document type, ensuring consistent audio branding across your legal products.

  • - aria: warm, clear narrator
  • - nova: bright, upbeat
  • - luna: soft, storytelling
  • - sage: calm, instructional
  • - felix: energetic, promo
  • - milo: friendly, conversational
  • - atlas: neutral, news
  • - orion: deep, documentary

Language codes

The endpoint provides ISO 631-1 language codes for all supported languages. While the API guesses language from script, setting the language parameter explicitly ensures accurate synthesis for non-English Latin-script texts.

Use this data to map your application’s language settings to the correct voice parameters, avoiding mispronunciations in critical legal terms or names.

  • - Arabic, Chinese, Danish, Dutch
  • - English, Finnish, French, German
  • - Greek, Hebrew, Hindi, Italian
  • - Japanese, Korean, Malay, Norwegian
  • - Polish, Portuguese, Russian, Spanish
  • - Swahili, Swedish, Turkish

Format options

The endpoint lists all supported audio formats: MP3, WAV, Opus, FLAC, and PCM. This allows you to choose the right balance between file size and quality for your specific use case, whether it’s archival or playback.

Ensure your integration handles the selected format correctly, as the API returns the raw audio data in the specified encoding.

  • - mp3
  • - wav
  • - opus
  • - flac
  • - pcm

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This ensures each segment is processed correctly without truncation or errors.

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

More on this site