Quickstart Guide to the Text-to-Speech API for Real Estate

By EstateSays editorial team · Updated 2026-11-18

This guide helps real estate agencies integrate EstateSays to convert property listings into engaging audio tours. You will learn how to generate high-quality speech from text descriptions using our simple REST API. The documentation covers essential workflows, from obtaining your API key to handling long property scripts, ensuring your virtual tours feel alive and accessible.

We use the standard OpenAI-compatible endpoint, allowing you to leverage existing SDKs with minimal code changes. You can choose from eight distinct voices and multiple audio formats to match your brand’s tone. This page provides concrete examples and technical details for developers building audio features for real estate clients.

Quickstart Guide to the Text-to-Speech API for Real Estate

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.mp3

Python (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
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

Get Your API Key

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

Rate Limits and Speed

Handling Long Texts

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. ISO 639 language codes
  3. IETF RFC 7845: Ogg Opus
  4. LibriTTS-R corpus (OpenSLR 141)
  5. Node.js documentation
  6. openai-python on GitHub
  7. MDN: Web Speech API
  8. Python documentation
  9. OpenAI API reference: create speech
  10. LibriVox public-domain audiobooks
  11. TRON developer hub: TRC-20
  12. W3C WAI: making audio and video accessible

More on this site