Frequently asked questions
How do I get an API key?
Sign up on our /get-api-key/ page using Google or an email and password. Accounts are created per site, and you will receive a unique Bearer token immediately. This key allows you to authenticate your requests to the speech generation endpoint.
What is the base URL for the API?
The API base URL is https://api.getplay971.com/v1. You send POST requests to /audio/speech for generation. Other endpoints like /voices and /models are also available under this base URL for retrieving voice options and model details.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. You simply change the base_url to https://api.getplay971.com/v1 and use your EstateSays API key. The request shape matches the OpenAI speech endpoint exactly, requiring no code changes for basic usage.
What audio formats are supported?
We support mp3, wav, opus, flac, and pcm formats. You specify the desired format using the response_format field in your request body. This allows you to choose the best balance between file size and quality for your real estate listings.
What are the rate limits?
You are limited to 60 requests per minute per API key. Before your first top-up, the limit is 10 requests per minute. This ensures fair usage across all agencies. Exceeding the limit will result in temporary throttling of your requests.
How do I handle long property descriptions?
Split texts into parts of up to 4096 characters. Generate audio for each part individually, then join the resulting audio files. This ensures optimal processing speed and avoids hitting the character limit per single request while maintaining audio continuity.
What happens if the API fails?
Failed requests are free. If synthesis fails, the charge is returned in full to your account balance. You can retry the request without worrying about incurring costs for unsuccessful audio generations, ensuring you only pay for delivered content.
How is authentication handled?
Authentication uses the Authorization header with a Bearer token. Include your unique API key, starting with tts-, in every request. This ensures secure access to your account balance and usage metrics while generating audio for your property listings.
Can I change my API key?
Yes, you can issue a new API key at any time. When you generate a new key, the old one stops working immediately. This allows you to rotate keys for security without downtime, ensuring your agency’s access remains secure.
Is there a mobile SDK?
No, there is no official mobile SDK. We recommend using the OpenAI SDK or plain HTTP requests. You can integrate the API directly into your mobile app by handling the HTTP requests and processing the returned audio files.
Do I need to install anything?
No, you do not need to install any specific software. The API is cloud-based and accessed via HTTP. You only need an internet connection and a library to make HTTP requests, such as the OpenAI SDK or curl.
How do I specify the language?
Set the optional language field to 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 setting the language ensures accurate voice generation.
What is the maximum text length?
The maximum input length is 4096 characters per request. Spaces and punctuation count toward this limit. For longer property descriptions, split the text into chunks and combine the resulting audio files to create a complete virtual tour audio track.
How do I detect errors?
Check the HTTP status code and response body for error details. Failed requests are free, so you can retry safely. The API provides clear error messages to help you debug issues like invalid parameters or rate limit exceeded scenarios.
First request
curl
curl https://api.getplay971.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.getplay971.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.getplay971.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
EstateSays provides a straightforward path to audio property tours. You can create an account using your Google credentials or a standard email and password directly on the site. This account is specific to getplay971.com and gives you immediate access to the API infrastructure needed to convert listings into voice.
Sign up on the site
Visit the /get-api-key/ page to register. If you sign in with Google, you receive a free trial credit of $0.50, valid for 7 days. Email-based accounts start without trial credit but are ready for immediate top-ups via USDT (TRC-20).
Access your dashboard
Once registered, your dashboard displays your active API key, current balance, and character usage. You can view the specific limits for your key, such as the 60 requests per minute cap, and see a ready-to-use cURL example to test your connection.
Copy your key
Locate your key starting with "tts-" in the dashboard header. Use this string in the Authorization: Bearer header of your API calls. You can generate a new key at any time, which immediately invalidates the previous one for security.
First Request with cURL
To generate your first audio tour, send a POST request to the speech endpoint. You must provide the API key in the Authorization header and specify the model, input text, and desired voice. This simple structure allows you to convert property descriptions directly into audio files without complex setup.
Basic POST request
Send your request to https://api.getplay971.com/v1/audio/speech with a JSON body. Include your tts-... key in the Authorization: Bearer header. The endpoint accepts standard parameters like model and input to define the synthesis task.
- Endpoint: POST https://api.getplay971.com/v1/audio/speech
- Header: Authorization: Bearer tts-your-key-here
- Body: JSON format with model and input fields
Include text and voice
Specify the input field with your property description, up to 4096 characters. Choose one of eight preset voices, such as atlas for a neutral news style or nova for a bright, upbeat tone. Set the response_format to mp3, wav, opus, or flac.
- Voice presets: aria, nova, luna, sage, felix, milo, atlas, orion
- Max input length: 4096 characters
- Formats: mp3, wav, opus, flac, pcm
Receive audio file
The API returns the synthesized audio file directly in the response body. You can save this file for use in your virtual tours or web listings. If the request fails, the response will contain an error code, but no charge is applied.
Use with OpenAI SDK
EstateSays uses the exact same request shape as OpenAI’s speech endpoint, so you can reuse your existing OpenAI SDK integrations with minimal changes. This means your real estate listing scripts work out of the box without rewriting complex audio generation logic.
Change base_url
Point your OpenAI SDK client to our API base URL: https://api.getplay971.com/v1. This simple configuration change directs all speech requests to our TTS engine while keeping your familiar client structure intact.
Use official SDKs
The official OpenAI SDKs work seamlessly because we mirror the standard request fields like model, input, voice, and response_format. You can continue using Python, JavaScript, or Go libraries you already trust for property description generation.
Simple integration
Replace your existing base_url and supply your EstateSays API key. The SDK handles the rest, sending text to our engine and returning audio files ready for your virtual tours.
- No new SDK to learn or install
- Uses standard OpenAI request parameters
- Works with Python, Node.js, and Go
Supported Audio Formats
EstateSays provides four standard audio formats to suit different playback environments. You can choose from MP3, WAV, Opus, or FLAC by setting the response_format parameter in your request body.
MP3
MP3 is the most compatible format for web players and mobile apps. It offers a good balance between file size and audio quality, making it ideal for embedding audio tours directly into property listing pages.
WAV
Choose WAV when you need lossless, high-quality audio for professional editing or archival purposes. This format preserves the full fidelity of the synthetic voice without compression artifacts.
FLAC and Opus options
FLAC provides lossless compression, reducing file size while maintaining exact audio quality. Opus offers efficient compression for modern web applications, though it is available as a standard option rather than specifically for streaming.
Rate Limits and Speed
Your API key allows up to 60 requests per minute. This limit applies to all endpoints and helps maintain stable performance for your agency’s workflow. If you haven’t topped up yet, the limit is 10 requests per minute.
60 requests per minute
Each request processes one text chunk. The limit resets every minute, allowing steady batch uploads for property listings.
Real-time generation
Generation speed is roughly real-time, producing about 25 characters of text per second. Short phrases may take a few seconds to complete.
Queue under load
Requests are processed sequentially. Under high load, a request may wait in a queue before starting synthesis.

Handling Long Texts
Property descriptions often exceed the 4,000-character limit per API call. When a listing’s details, amenities, and neighborhood highlights stretch beyond this boundary, you must split the text into smaller chunks to ensure successful synthesis.
Split into 4096 chars
Divide your script into segments of up to 4,096 characters each. Spaces and punctuation count toward this limit. Send each segment as a separate POST request to the /v1/audio/speech endpoint.
Join audio files
The API returns an audio file for each request. To create a continuous tour, concatenate these files in the order you sent them. This creates a seamless audio experience for potential buyers listening to the full listing.
Manage large scripts
Typical generation speed is roughly real-time, producing about 25 characters of text per second. For very long scripts, requests are processed sequentially, so under load, a request may wait in a queue. Plan your character count accordingly.
Common Errors
Encountering errors is part of integration. Understanding these common issues helps you debug your real estate audio tours quickly and keep your listings generating smoothly.
Invalid API key
Ensure your request includes the header Authorization: Bearer tts-.... Keys are specific to this site; using a key from another network site will fail.
- Check for trailing spaces when copying from the dashboard.
- Verify the key starts with
tts-.
Rate limit exceeded
You are limited to 60 requests per minute per key. If you exceed this, requests are rejected until the window resets. New accounts start with 10 requests per minute.
- Implement exponential backoff in your script.
- Monitor your usage dashboard for real-time limits.
Text too long
Each request supports up to 4096 characters. Sending longer property descriptions will result in an error. Split your text into smaller chunks before sending.
Authentication Details
Authentication relies on a single active Bearer token per account. Include it in the Authorization header as Bearer tts-your_key_here. This token grants access to all endpoints, including speech synthesis and voice listings.
Bearer token format
The token must start with tts- followed by your unique identifier. Ensure no extra spaces are included in the header value to avoid 401 errors.
Key management
Each account maintains one active key visible in your dashboard. You can generate a new key at any time via the UI or API.
Revoke old keys
Issuing a new key immediately invalidates the previous one. The old key stops working at once, ensuring secure rotation without downtime for new requests.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This flexibility ensures your audio tours feel consistent yet tailored.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- ISO 639 language codes
- IETF RFC 7845: Ogg Opus
- LibriTTS-R corpus (OpenSLR 141)
- Node.js documentation
- openai-python on GitHub
- MDN: Web Speech API
- Python documentation
- OpenAI API reference: create speech
- LibriVox public-domain audiobooks
- TRON developer hub: TRC-20
- W3C WAI: making audio and video accessible
