Frequently asked questions
How do I get an API key?
Sign up at /get-api-key/ using Google or email. Accounts created with email start without trial credit, while Google sign-ins receive $0.50 valid for 7 days. Your key appears on the dashboard alongside your balance and usage statistics.
What is the base URL for the API?
The API base URL is https://api.playbosspay.com/v1. You send POST requests to /audio/speech and GET requests to /voices or /models. This endpoint structure matches the OpenAI speech endpoint, allowing easy integration with existing tools.
Can I use the OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playbosspay.com/v1 and providing your PlayBossPay API key for authentication in the Authorization header.
How do I specify a voice?
Include the voice parameter in your request body. Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrators to energetic promo styles, suitable for real estate tours.
What formats are supported?
You can request audio in mp3, wav, opus, flac, or pcm formats. Select the format that best fits your virtual tour platform’s requirements. The API returns the generated audio file directly in the response using your chosen encoding.
What are the rate limits?
You are limited to 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Exceeding this limit may cause requests to queue or fail, so monitor your usage via the dashboard.
How do I handle errors?
If synthesis fails, the charge is returned in full. Failed requests do not consume your balance. You should check the response status and retry if necessary, keeping in mind that requests are processed sequentially and may queue under load.
Can I change my API key?
Yes, you can issue a new key at any time. When you generate a new key, the old one stops working immediately. This ensures secure access control for your real estate startup’s integration with our text-to-speech service.
Is there a documentation page for voices?
Yes, send a GET request to /v1/voices to retrieve details on all available voices, languages, formats, and pricing. This endpoint provides the complete list of eight presets and their characteristics, helping you choose a voice for your tours.
How do I set the language?
Include the optional language parameter with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly set the language to ensure accurate synthesis.
Can I adjust the speed?
Yes, you can set the speed parameter between 0.25 and 4.0. This allows you to customize the pacing of your property tours, making them slower for detailed descriptions or faster for quick overviews, enhancing the buyer experience.
What happens if I exceed the limit?
Requests are processed sequentially. If you exceed the rate limit, your request may wait in a queue before being processed. Under heavy load, this can increase generation time. Monitor your usage to ensure smooth operation for your tours.
Is the API synchronous?
Yes, the API is synchronous. You send a POST request and receive the audio file in the response. Requests are processed one after another, so under load, you may experience delays as your request waits in the queue.
How do I split long texts?
Split your text into parts of up to 4096 characters. Send each part as a separate request and join the resulting audio files on your end. This ensures optimal processing and avoids character limit errors for longer property descriptions.
First request
curl
curl https://api.playbosspay.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.playbosspay.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.playbosspay.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
Create your PlayBossPay account on the /get-api-key/ page using Google or email. Real estate startups receive $0.50 in trial credit valid for 7 days, sufficient for approximately 50,000 characters. Email-based accounts start without trial credit.
Your API key appears immediately on the dashboard alongside your balance, usage statistics, and a ready-to-use cURL example. This key authenticates all requests to the TTS engine.
Sign Up on Site
Visit the registration page to create your account. You can sign up quickly with Google or use a standard email and password. The process is straightforward, designed to get your virtual tour integration running without delay.
- Google or email/password authentication
- Instant trial credit ($0.50) for Google sign-ups
- Accounts are per site
Retrieve Key
Once registered, your unique API key is displayed on the dashboard. It begins with 'tts-' and is used in the Authorization header. You can copy this key directly for immediate integration with your property listing platform.
Manage Keys
Each account holds one active key. If you suspect a leak or need a fresh credential, you can issue a new key at any time. The old key stops working immediately, ensuring your audio tours remain secure.
First Request with cURL
Send your property listing text to our API to receive synthesized audio instantly. The endpoint accepts JSON bodies containing the text, selected voice, and output format, returning a ready-to-play audio file.
Basic Syntax
Use a standard HTTP POST request to the speech endpoint. Include your API key in the Authorization header and specify the model, input text, voice preset, and desired response format in the JSON body.
- Endpoint: https://api.playbosspay.com/v1/audio/speech
- Method: POST
- Content-Type: application/json
Example Command
Here is a working cURL example to generate a 5-second audio tour snippet for a virtual property listing.
- curl -X POST https://api.playbosspay.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Welcome to this modern downtown apartment with city views.", "voice": "aria", "response_format": "mp3"}'
Response Format
On success, the API returns the audio file directly in the requested format (MP3, WAV, OPUS, FLAC, or PCM) within the response body. You can save this output directly to your virtual tour platform.
OpenAI SDK Integration
To use our API with the official OpenAI SDK, simply point the client to our base URL. This allows you to keep your existing integration logic while switching the voice engine. The request shape matches the standard speech endpoint exactly.
Both Python and Node.js SDKs work seamlessly. You only need to update the base_url configuration. No custom wrappers or additional libraries are required for basic text-to-speech synthesis.
Base URL Change
Update your SDK client configuration to use https://api.playbosspay.com/v1 as the base URL. This directs all requests to our infrastructure while maintaining compatibility with the standard API structure.
- Base URL: https://api.playbosspay.com/v1
- Compatible with standard OpenAI SDK versions
- Requires no custom transport layers
SDK Compatibility
The API accepts standard JSON bodies identical to the OpenAI speech endpoint. Any SDK supporting the standard format will work without modification to the request payload.
- Python SDK
- Node.js SDK
- Standard HTTP clients
Code Snippet
Initialize the client with your key and the new base URL. Pass your property listing text and desired voice preset to generate audio instantly.
Request Parameters
Configure your synthesis requests using three primary parameters: model, voice, and speed. These settings determine the audio quality, timbre, and pacing of the generated speech, allowing you to tailor the output to specific property listing contexts.
Model Selection
Choose between "tts-1" for standard quality or "tts-1-hd" for high-definition audio. Both models use the same engine and pricing, so select "tts-1-hd" if your virtual tours require clearer, more detailed voice reproduction for complex property descriptions.
Voice Presets
Select from eight distinct voice presets to match your brand tone. Female options include Aria (warm, clear narrator) and Luna (soft, storytelling), while male voices like Felix (energetic, promo) or Atlas (neutral, news) offer different personalities. Each voice supports all 23 languages.
- Aria: Warm, clear narrator
- Felix: Energetic, promo style
- Luna: Soft, storytelling
- Atlas: Neutral, news style
Speed Control
Adjust the speech rate between 0.25 and 4.0. Slower speeds (e.g., 0.8) are ideal for detailed property features, while faster speeds (e.g., 1.5) work well for quick highlights. The default speed is 1.0, which matches natural conversational pacing.
Response Formats
The API returns synthesized audio in the format you specify via the response_format parameter. This choice determines the file type and encoding of the response body, allowing you to select the optimal balance between file size and quality for your specific virtual tour infrastructure.
MP3 Output
MP3 is a widely supported format for web players and mobile apps. It provides a good balance between compression and audio quality, ensuring fast loading times for property audio tours without consuming excessive bandwidth.
WAV Support
WAV offers uncompressed, high-quality audio suitable for professional editing or high-fidelity playback systems. Use this format if you need raw audio data for post-processing or if your virtual tour platform requires lossless input for maximum clarity.
OPUS & FLAC
OPUS and FLAC are supported formats. Note that we do not offer streaming or WebSocket support; audio is returned as a complete file in the response. These formats are ideal if you need to minimize storage costs without sacrificing quality, or if you require lossless audio for premium tour experiences.

Rate Limits & Quotas
Understanding rate limits ensures your virtual tour generation remains smooth and predictable. Our API enforces strict quotas to maintain stability for all real estate startups using the service.
60 Requests Per Minute
Each API key is limited to 60 requests per minute. This limit applies uniformly across all endpoints, including speech synthesis and voice listing.
Initial Limit
New accounts start with a lower quota of 10 requests per minute. This initial limit helps prevent accidental bursts while you integrate the API into your virtual tour platform.
Limit Increase
Once you top up your balance with USDT (TRC-20), your rate limit increases to the standard 60 requests per minute. This change happens automatically within minutes of transfer confirmation.
Error Handling
When synthesis fails, your balance is refunded in full, so you are never charged for broken audio. Common issues include exceeding the 4,096-character limit per request or passing an unsupported voice ID or model. The API returns clear error messages to help you adjust your input text or parameters quickly.
Common Errors
Errors typically stem from invalid JSON, missing authentication, or rate limits. If you exceed the 60 requests per minute limit, the API rejects subsequent calls until the window resets. Always validate your text length before sending.
- Invalid character encoding in input text
- Expired or incorrect Bearer token
- Input text exceeds 4,096 characters
Retry Logic
Implement exponential backoff for transient network errors. Since requests are processed sequentially, brief queues may cause temporary delays. Wait and retry rather than failing immediately, especially during peak usage times.
Status Codes
The API uses standard HTTP status codes. A 200 OK indicates successful synthesis. Use 400 for bad requests, 401 for authentication issues, and 429 for rate limit exceeded. Check the response body for specific error details.
Voice & Language Options
Choose from eight distinct voice presets to match your property’s personality, from warm narrators to neutral news anchors. Each voice is built from licensed recordings and carries an inaudible synthetic watermark.
Our API supports 23 languages, allowing you to create immersive tours for international buyers. Any voice can speak any supported language, ensuring consistent quality across your global listings.
8 Voice Presets
Select from four female voices (Aria, Nova, Luna, Sage) and four male voices (Felix, Milo, Atlas, Orion). These presets range from upbeat and energetic to calm and instructional, letting you tailor the audio experience to different property types.
All voices are derived from licensed LibriTTS-R recordings, ensuring high-quality, natural-sounding speech without the need for custom voice design or cloning.
- Female: Aria, Nova, Luna, Sage
- Male: Felix, Milo, Atlas, Orion
- All voices support all 23 languages
23 Languages
Our API supports 23 languages, including English, Spanish, French, German, Chinese, Japanese, and Arabic. This allows you to create multilingual tours for buyers from diverse backgrounds.
If a language is not in the list, such as Vietnamese or Thai, it is not supported. Ensure your target audience’s language is included for the best results.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Auto-Detection
The API automatically guesses the language from the text’s script. For Latin-script text, it defaults to English. For non-English Latin text, set the language parameter explicitly to avoid misinterpretation.
This feature simplifies integration, but for mixed-language tours, explicitly defining the language for each segment ensures accurate pronunciation and tone.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Our platform empowers startups to create immersive virtual tours for real estate properties, transforming how clients experience homes from anywhere.
23 languages
Any voice speaks any of these languages.
