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.mp3Python (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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authentication
Secure your API access with a Bearer token. Include Authorization: Bearer tts-... in every request header to authenticate your account.
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
Each account holds exactly one active key. If you generate a new key, the old one stops working immediately.
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
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
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_urltohttps://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
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
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
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
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, missinginput, 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
400errors 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
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.
23 languages
Any voice speaks any of these languages.
