Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playn777.com/v1. You use this endpoint for all requests, including POST /v1/audio/speech for synthesis and GET /v1/voices for metadata. This URL structure allows you to integrate the service directly into your car application’s backend or client-side logic without needing a separate gateway.
How do I authenticate with the API?
Authentication uses a Bearer token in the Authorization header. Include the header Authorization: Bearer tts-... with your unique API key. Each account has one active key at a time; issuing a new key immediately invalidates the old one, so ensure your car app updates its credentials promptly after a rotation.
Can I use the Python OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. Configure the SDK’s base_url to https://api.playn777.com/v1 and provide your WayAudio API key. This allows you to use standard Python libraries to call the speech endpoint without writing custom HTTP client code, simplifying integration for indie developers familiar with OpenAI’s ecosystem.
What is the maximum text length per request?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For navigation instructions longer than this, you must split the text into chunks, generate audio for each part, and join the resulting audio files in your application logic before playing them to the driver.
How do I set the voice language?
Pass the optional language field with an ISO code in your request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always specify the language to ensure accurate synthesis, as any voice can speak any of the 23 supported languages.
Does the API support SSML?
No, the API does not support SSML. You cannot use speech marks or prosody tags to control pacing or pronunciation. If you need specific timing, adjust the speed parameter between 0.25 and 4.0, or split your text manually to insert pauses by joining separate audio segments in your car app.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key. If you exceed this, the API returns a 429 Too Many Requests error. Short phrases may take a few seconds, and under load, delays increase. Failed requests remain free, but successful ones incur charges. Monitor your usage to avoid latency spikes during heavy navigation updates.
Is the API key case-sensitive?
Yes, the API key is case-sensitive. Ensure you copy it exactly from your dashboard at /get-api-key/. The key format is tts-.... Incorrect casing will result in authentication errors. Since only one key is active per account, verify you are using the current valid key issued to your WayAudio account.
Can I generate audio in multiple formats at once?
No, each request generates a single audio file in one format. Specify response_format as mp3, wav, opus, flac, or pcm. To get multiple formats, you must send separate requests for the same text. This allows your car app to choose the optimal format based on current network conditions or player capabilities.
How do I handle long navigation instructions?
Split text into parts of up to 4096 characters. Generate audio for each part using separate requests, then join the audio files in your application. This ensures reliable synthesis and avoids hitting character limits. The API processes requests sequentially, so plan your splitting logic to minimize latency during turn-by-turn directions.
Is the response format always MP3?
No, MP3 is just one option. You can choose mp3, wav, opus, flac, or pcm by setting the response_format field. WAV and FLAC offer lossless quality, while MP3 and OPUS are compressed. PCM provides raw audio data. Select the format that best fits your car app’s audio pipeline and storage constraints.
Do I need to handle audio streaming?
No, the API does not support streaming or WebSocket connections. You receive the complete audio file in the response after synthesis finishes. For short phrases, this takes a few seconds. Your car app must wait for the full file before playing it, as there are no partial audio chunks available.
How do I verify the audio is synthetic?
Every generated file contains an inaudible watermark marking it as synthetic speech. This watermark is embedded in the audio data itself. You do not need special tools to detect it; it is automatically included in all outputs from the tts-1 and tts-1-hd models, ensuring transparency for your users and compliance requirements.
What is the model name for HD audio?
Use tts-1-hd for high-definition audio. The standard model is tts-1. Both use the same engine and price ($0.01 per 1,000 characters). Choose tts-1-hd if your car app requires higher fidelity for dashboard interfaces, ensuring clear speech even in noisy cabin environments with premium audio systems.
First request
curl
curl https://api.playn777.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.playn777.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.playn777.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 |
Get your API key
Access the /get-api-key/ page on playn777.com to create your account. You can sign up instantly using your Google account or register with an email address and password. Each account is tied to this specific site and provides a single active API key for authenticating your requests.
Sign up with Google or email
Google sign-ups include a $0.50 trial credit valid for 7 days. Email-based accounts start without trial credit. Both methods generate a unique account per site, ensuring your navigation app’s integration is isolated and secure.
Locate key in dashboard
After signing up, the dashboard displays your API key immediately. It appears as a string starting with tts-. You can copy this key directly into your car app’s configuration or code. The dashboard also shows your current balance, trial status, and a ready-to-use cURL example for testing.
- Key format:
tts-... - Visible immediately after sign-up
- Included in dashboard view
Issue new key if needed
You can generate a new API key at any time from the dashboard. Once issued, the old key stops working immediately. This allows you to rotate credentials securely without downtime for your navigation service.
First request with cURL
Send your first synthesis request using cURL. Replace {API_KEY} with your unique key from the dashboard and {VOICE} with one of the eight available presets. The base URL points directly to the API endpoint for speech generation.
Base URL configuration
Configure your request to https://api.playn777.com/v1/audio/speech. Ensure the Authorization header includes Bearer {API_KEY}. This URL structure mirrors the standard OpenAI format, allowing direct integration with existing car app workflows.
JSON body structure
Construct the JSON body with model (tts-1 or tts-1-hd), input (text up to 4096 characters), voice, and response_format. You may optionally specify speed between 0.25–4.0 and language for precise control over synthetic speech output.
- model: "tts-1" or "tts-1-hd"
- input: Your navigation text string
- voice: e.g., "atlas" or "nova"
- response_format: "mp3", "wav", "opus", "flac", or "pcm"
Response handling
The API returns the audio file directly in the response body. Save this binary data to your car app’s local storage or play it to the dashboard speaker. Failed requests return a full refund of character credits.
Using the OpenAI SDK
Leverage the official OpenAI SDK to integrate speech synthesis into your car app with minimal code changes. The API maintains the standard request shape, allowing you to reuse familiar client structures while directing traffic to our cloud infrastructure.
Change base_url parameter
Point your SDK client to the WayAudio base URL: https://api.playn777.com/v1. This simple configuration swap enables the use of standard OpenAI libraries without requiring custom wrappers or new dependencies.
Keep standard client setup
Use your API key for authentication via the Authorization: Bearer header. Pass model, input, voice, and other parameters exactly as defined in the standard speech endpoint schema. No special headers or custom fields are needed.
Handle audio response
The SDK returns binary audio data directly. Write the response data to a local file or buffer. Ensure your car interface supports the requested response_format (e.g., mp3 or wav) for playback.
- Supported formats: mp3, wav, opus, flac, pcm
Voice selection parameters
Selecting the right voice ensures your navigation cues are clear and less fatiguing for drivers during long trips. You can choose from eight distinct presets, ranging from warm narrators to energetic promotional voices, all optimized for in-cabin listening.
The API lets you fine-tune delivery by adjusting speed and explicitly setting the language, preventing misinterpretation of non-English text in Latin script.
Choose from 8 presets
Each voice has a specific tone suited for different driving contexts. Use Atlas for neutral news updates or Orion for deep, documentary-style directions.
Available voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. All support 23 languages regardless of the voice selected.
- 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
Set speed between 0.25–4.0
Adjust the speed parameter to match driving conditions. Higher speeds (up to 4.0) help convey urgency in traffic alerts, while lower speeds (0.25–1.0) improve clarity for complex turn-by-turn instructions.
This range allows you to balance listening comfort with information density without distorting the voice quality.
Specify ISO language code
Always set the language parameter using an ISO code, especially for non-English Latin-script text. If omitted, the system guesses the language, defaulting to English for Latin script, which may cause errors in other languages.
Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
Supported audio formats
For car apps, MP3 is the standard choice. It offers reliable playback across many Android and iOS in-car systems while keeping file sizes small. This ensures quick decoding and smooth navigation voice delivery.
MP3 for mobile efficiency
MP3 is the recommended format for most dashboard interfaces. It balances quality and size, ensuring that navigation prompts load quickly.
- Default choice for general navigation prompts.
- Broad compatibility with car infotainment systems.
OPUS for low bandwidth
Use OPUS when your app streams audio over cellular data. It provides high quality at lower bitrates, reducing data usage for users with limited plans. This is suitable for route updates sent over the network.
- Optimal for cellular streaming.
- Reduces data consumption for users.
WAV and FLAC options
WAV and FLAC are available for local caching or high-fidelity playback. These uncompressed or lossless formats ensure no audio degradation, which is useful for storing frequently used navigation instructions locally on the device. They are larger but guarantee exact reproduction of the synthetic voice.
- WAV: Uncompressed, widely supported.
- FLAC: Lossless compression for archival quality.

Rate limits and queuing
Rate limits protect the API's stability during high-volume navigation updates. Each API key supports a maximum of 60 requests per minute. This limit applies to all synthesis endpoints collectively.
60 requests per minute limit
The system processes requests sequentially, meaning complex audio generation may take longer than simple phrases. If you exceed 60 requests in a minute, the API returns a 429 Too Many Requests error. Plan your batch splits accordingly to avoid interruptions in navigation prompts.
10 requests before top-up
New accounts without a top-up are limited to 10 requests per minute. This ensures fair usage for trial users. Once you add funds via USDT (TRC-20), this limit increases to the standard 60 requests per minute.
Handling queue delays
Under load, requests may wait in a queue before processing begins. Typical speed is roughly real-time, but short phrases may take a few seconds. Implement exponential backoff in your client to handle temporary delays gracefully without dropping navigation cues.
Error handling and retries
Robust error handling ensures your navigation app remains responsive when the TTS service encounters issues. By correctly interpreting HTTP status codes and implementing exponential backoff, you prevent app freezes during temporary outages or billing pauses.
Common HTTP error codes
A 403 Forbidden indicates insufficient balance or an expired trial, requiring immediate top-up. A 429 Too Many Requests signals that you have exceeded the 60 requests per minute limit per key. Use the /v1/voices endpoint to verify voice availability if you receive a 400 Bad Request.
- 401: Invalid or missing API key
- 403: Insufficient balance
- 429: Rate limit exceeded (60 req/min)
Retry logic for failures
Implement exponential backoff for 429 and 5xx errors. Wait 1 second, then 2, then 4 seconds before retrying. This prevents overwhelming the API during high load when requests are queued. Do not retry 400 or 403 errors as they require manual intervention.
Character limit errors
The API rejects inputs exceeding 4096 characters with a 400 error. Ensure your text preprocessing splits long navigation instructions before sending. Handle this gracefully by splitting the string in your client code rather than relying on server-side splitting.
Long text splitting strategy
For navigation instructions exceeding 4096 characters, split the input text into chunks of that length. Send each chunk as a separate POST request to the speech endpoint. This ensures every segment stays within the single-request limit.
Split at 4096 characters
Count every character, including spaces and punctuation. If a single instruction is longer, divide it precisely at 4096 characters. Do not exceed this limit, or the request will fail.
Join audio files sequentially
The API returns audio files for each chunk. Concatenate these files in the exact order they were requested. Play them sequentially in your car’s audio player to create a continuous voice output.
Manage memory usage
Download each audio file before requesting the next one if memory is limited. Process them in a loop rather than storing all files in RAM simultaneously. This keeps your app stable during long directions.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. A neutral vocal quality reduces cognitive load by removing subjective emotional cues.
23 languages
Any voice speaks any of these languages.
