Frequently asked questions
What is a good script length?
Keep each request under 4096 characters. For longer virtual tour scripts, split the text into parts of this limit and join the resulting audio files. This ensures reliable processing and avoids truncation during synthesis.
Which voice is best for tours?
Q: Which voice is suitable for tours? A: Use Aria for a warm, clear narrator or Felix for energetic promo-style tours. Atlas works well for neutral, news-style descriptions. Select the voice that matches your property’s tone, ensuring the language setting aligns with the script. There is no single "best" voice; choose based on whether your listing requires a friendly, conversational style or a more formal, documentary approach.
Can I change the speed?
Yes, adjust the speed parameter between 0.25 and 4.0. This allows you to speed up short listings or slow down detailed property descriptions to match the visual pacing of your virtual tour video.
How do I split long text?
Divide your script into segments of up to 4096 characters. Send each segment as a separate request and concatenate the returned audio files. This method handles longer property descriptions without hitting the character limit.
Does the API support SSML?
No, the API does not support SSML. You cannot use phoneme dictionaries or custom pronunciation lexicons. Input plain text only; the system guesses the language based on the script or your specified language code.
Can I clone a voice?
No, custom voice cloning is not offered. You cannot upload your own voice or design a new one. Use the eight available presets, which are based on licensed recordings from LibriTTS-R and LibriVox.
How long does generation take?
Generation is roughly real-time, processing about 25 characters per second. Short phrases take a few seconds, while longer texts may queue under load. Requests are processed sequentially, so wait times vary during high usage.
What format is best for video?
Q: What format is suitable for video? A: MP3 is widely compatible with most video editing software. You can also choose WAV, OPUS, FLAC, or PCM depending on your editing workflow. MP3 offers a good balance of quality and file size for property tours.
Do I need to set the language?
Set the language if your text uses Latin script but is not English. Otherwise, the system guesses the language from the script. This ensures accurate pronunciation for the 23 supported languages, including Spanish, French, or German.
Is the watermark audible?
No, the watermark is inaudible. Every generated file carries an inaudible mark identifying it as synthetic speech. This does not affect the audio quality or the viewer’s experience during your virtual tour presentation.
Can I use this commercially?
Yes, you can use the generated audio commercially. Input text is not used for training, and generated audio is returned in the response without being stored. You retain the rights to the audio files you create.
How do I handle errors?
Failed requests are free, with the charge returned in full. If synthesis fails, check your input text and API key. Retry the request or split the text if it exceeds the 4096-character limit per request.
What if I run out of credits?
Top up using USDT on the TRON network (TRC-20). Minimum $5 transfers are credited automatically within minutes. Balance does not expire, and there are no monthly plans or minimum spending requirements for continued use.
Is there a mobile app?
No, there is no mobile app or official SDK of our own. Use the OpenAI SDK or plain HTTP requests. Access the API via any device with a web browser and internet connection, integrating it into your workflow.
Prepare your script
Start by drafting a concise property description that highlights key features without fluff. For virtual tours, clarity is essential to guide viewers through the space efficiently. Keep your script focused on visual cues and property details.
Write property description
Focus on specific attributes like square footage, room layout, and unique selling points. Avoid marketing jargon that doesn't translate well to audio. A clear, factual script ensures the TTS engine delivers a natural-sounding narration that matches the visual tour.
- List key features: beds, baths, yard size
- Avoid complex numbers or dates
- Keep sentences short for better pacing
Add tour instructions
Incorporate directional cues such as 'walk into the kitchen' or 'note the hardwood floors.' These instructions help sync the voiceover with video movements. Ensure the language is imperative and direct to maintain viewer engagement.
- Use directional verbs: walk, look, enter
- Sync with camera pans
- Keep instructions under 15 words
Keep under 4096 chars
The API accepts a maximum of 4096 characters per request. Count spaces and punctuation toward this limit. If your script exceeds this, split it into segments before sending the POST request to avoid truncation.
- Limit: 4096 characters including spaces
- Count punctuation and spaces
- Split long scripts into parts
Choose the right voice
Selecting the correct voice preset ensures your virtual tour audio matches the property’s tone. Our API offers eight distinct voices, each designed for specific narration styles.
For real estate, choose voices that enhance clarity and engagement without distracting from the visuals. The right choice depends on whether you want a warm, energetic, or neutral delivery.
Aria for warm narration
Aria provides a warm, clear narrator voice ideal for luxury or heritage properties. Her tone adds a personal touch to detailed property descriptions.
Use Aria when highlighting architectural details or lifestyle benefits. Her clear articulation ensures every word is understood without sounding robotic.
- Warm, clear narrator tone
- Ideal for luxury or heritage listings
- Enhances personal connection with viewers
Nova for upbeat tours
Nova offers a bright, upbeat voice perfect for modern, high-energy virtual tours. Her style keeps viewers engaged during quick walkthroughs.
Nova’s energetic delivery complements fast-paced video edits.
- Bright, upbeat delivery
- Ideal for modern properties
- Keeps viewers engaged during quick tours
Atlas for neutral news style
Atlas delivers a neutral, news-style voice suitable for straightforward property data. His tone is professional and unobtrusive.
Use Atlas for factual listings where clarity matters most. His voice ensures information is delivered without emotional bias.
- Neutral, professional tone
- Ideal for factual, data-driven listings
- Unobtrusive delivery for clear information
Set the request parameters
Configure the JSON body for your POST request to ensure the API generates audio that matches your virtual tour’s pacing. The model field accepts either "tts-1" or "tts-1-hd"; both use the same engine and pricing, so you can choose based on preference without affecting cost.
Adjust the speed parameter between 0.25 and 4.0 to control the delivery rate. A standard speed of 1.0 provides natural narration, while slower speeds may help emphasize key property features. Ensure your text input stays within the 4096-character limit per request.
Select tts-1 model
Both "tts-1" and "tts-1-hd" map to the same underlying engine and price point ($10 per 1 million characters). You can switch between them without cost implications, allowing flexibility if one model better suits a specific script’s tone.
Set speed between 0.25–4.0
The speed field accepts values from 0.25 to 4.0. For property listings, a speed near 1.0 ensures clarity. Faster speeds may be useful for quick highlights, while slower speeds help viewers absorb detailed descriptions.
- Minimum speed: 0.25
- Maximum speed: 4.0
- Default speed: 1.0
Choose MP3 format
Set response_format to "mp3" for broad compatibility with video editors. Other supported formats include wav, opus, flac, and pcm. MP3 is recommended for most virtual tour workflows due to its small file size and universal playback support.
- mp3
- wav
- opus
- flac
- pcm
Send the API request
Sending your script to the TTS engine is the core step where text becomes audio. You structure a JSON payload with your chosen voice, model, and input text, then POST it to the speech endpoint.
Use cURL or SDK
Use the OpenAI SDK or a simple HTTP client. Set the base_url to https://api.playjay9.com/v1 so requests route correctly. Pass the text in the input field, limited to 4096 characters.
- SDK: Initialize client with your API key and custom base URL.
- cURL: Use
POSTwithContent-Type: application/json.
Include Bearer token
Authentication is handled via the Authorization header. Include your unique API key as a Bearer token: Authorization: Bearer tts-.... This key is issued on your dashboard and identifies your account for billing.
Wait for response
The API returns the audio file directly in the response body. For short phrases, this takes a few seconds. If the request fails, you receive a JSON error without being charged. Save the returned binary data as your MP3 or WAV file.
Process the audio file
Once the API returns the audio file, you can download it directly from the response. The format you selected (e.g., MP3) is ready for immediate use in your editing software. There is no need for additional conversion or processing steps before integration.
Download the MP3
The API response contains the audio data directly. Save the file to your local directory or cloud storage. The file is ready for playback without further encoding.
- Save the response body as an .mp3 file
- Verify file integrity before importing
- No extra conversion needed
Sync with video timeline
Import the audio into your video editor. Align the narration with the virtual tour visuals. Adjust timing to match property features shown on screen. The synthetic speech watermark is inaudible and does not affect sync.
- Align narration with property highlights
- Match voice pacing to video cuts
- Ensure audio starts/ends with visual cues
Add background music
Layer background music beneath the voiceover. Keep volume lower than the speech for clarity. This enhances the professional feel of the virtual tour without distracting from the property details.
- Use royalty-free background tracks
- Set music volume below voice level
- Fade in/out at start/end
Handle long scripts
The API enforces a strict 4,096-character limit per request. If your property description or virtual tour script exceeds this threshold, you must manually split the text into smaller chunks before sending them to the endpoint.
Split text into parts
Break your script at logical sentence boundaries to ensure natural pauses between segments. Each part must be under 4,096 characters, including spaces and punctuation, to avoid rejection.
Generate each segment
Send each chunk as a separate POST request to https://api.playjay9.com/v1/audio/speech. Use the same voice and speed settings for every part to maintain consistent audio quality and tone across the entire tour.
Join audio files
Once all segments are generated, download the individual audio files. Use an audio editor to concatenate them in order, creating a single continuous voiceover file ready for your video timeline.
Check language settings
Language detection works automatically for Latin script text, defaulting to English. However, for non-English Latin text, you must explicitly set the language parameter to ensure accurate pronunciation.
Verify that your chosen voice supports the target language. All eight voices support all 23 listed languages, including Arabic, Chinese, and Swahili.
Set ISO code if needed
Always specify the ISO language code (e.g., es for Spanish) when using Latin-script text that is not English. This prevents the API from guessing incorrectly and producing awkward phrasing.
- Use explicit codes like
fr,de, orptfor clarity. - Omitting the code may cause incorrect language selection for Latin script.
Default to English for Latin
If you do not set the language field, the system assumes English for any Latin-script input. This is convenient for English properties but risky for other languages using Latin characters.
Verify voice supports language
All eight presets (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) support all 23 languages. You can confidently use any voice for any supported language without checking individual voice capabilities.
- Aria: Warm narration in any supported language.
- Atlas: Neutral news style for professional tours.

Optimize for speed
Generating voiceovers for virtual tours requires balancing speed with quality. While the API processes requests sequentially, understanding the mechanics helps you avoid unnecessary delays during peak usage times. Proper preparation ensures your audio files are ready for editing without waiting in line.
The system processes requests one after another, so under load, a request may wait in a queue. Long texts take time because they are processed in real-time, roughly 25 characters per second. Short phrases may still take a few seconds due to this sequential processing.
Use faster models
Both tts-1 and tts-1-hd use the same engine and price, so there is no speed difference between them. Choose based on your quality preference rather than latency. The generation speed is consistent regardless of the model selected, averaging real-time playback speed for longer scripts.
- tts-1 and tts-1-hd have identical processing speeds.
- No performance benefit from upgrading models for speed.
Reduce request load
Keep your input text under 4096 characters to avoid unnecessary splitting overhead. Each request is processed sequentially, so submitting smaller, focused scripts ensures quicker turnaround. Avoid sending multiple large requests simultaneously if you can combine them into a single optimized script.
Failed requests are free and do not consume your balance, but they still count towards your rate limit. Ensure your text is valid to avoid wasting your 60 requests per minute quota on errors.
- Limit text to 4096 characters per request.
- Ensure text validity to prevent wasted rate limit.
Queue management
Requests are processed one after another, so high traffic can cause delays. If you need multiple voiceovers, space them out slightly to avoid queuing behind other users. Use the rate limit of 60 requests per minute to plan your batch generation efficiently.
For urgent projects, consider generating shorter segments first to secure your place in the queue. The system handles long texts by splitting them internally, but manual splitting can give you more control over the queue position.
- Requests are processed sequentially.
- High traffic causes queuing delays.
- Plan batch generation within 60 requests/minute limit.
Review the output
Before adding background music, play the generated audio to ensure the narration matches the visual pacing of your virtual tour. The synthetic speech should sound natural and clear, allowing viewers to easily follow the property details without distraction.
Listen for clarity
Verify that the voice modulation remains consistent throughout the clip. Listen for any abrupt cuts or unnatural pauses that might disrupt the viewer's immersion in the property tour.
Check watermark
Every generated file includes an inaudible watermark identifying it as synthetic speech. This mark is permanent and cannot be removed, so ensure this aligns with your client's disclosure requirements.
Verify pronunciation
Check that specific property names, street addresses, and technical terms are pronounced correctly. While the AI handles standard text well, proper nouns may require manual spelling adjustments in the input text to ensure accurate delivery.
Integrate into workflow
Integrate Vbee AI into your real estate workflow by automating voiceover generation. This allows you to produce consistent audio for multiple property listings without manual intervention, saving time for visual editing.
Use standard tools to handle requests efficiently. The API’s compatibility with existing SDKs and simple HTTP methods ensures smooth integration into your current pipeline.
Securely store generated audio files. Since input text is used only for generation and not training, you maintain full control over your property data and final audio assets.
Automate with scripts
Write a simple script to loop through your property descriptions. Send each text string to the API endpoint and save the resulting audio files directly to your project folder.
This approach works well for batch processing multiple listings. You can schedule these scripts to run overnight, ensuring all voiceovers are ready before your marketing team starts working.
- Use Python or Bash scripts for batch processing
- Loop through property JSON data
- Automate file naming based on property ID
Use OpenAI SDK
Leverage the OpenAI SDK by pointing it to https://api.playjay9.com/v1. This allows you to use familiar methods like client.audio.speech.create without learning a new library.
Pass your unique API key in the Authorization header. The SDK handles the JSON body structure, making it easy to switch models or adjust speeds programmatically.
This method reduces boilerplate code. You can manage retries and errors using standard SDK features, ensuring reliable delivery of audio files to your editing software.
Store audio securely
Store generated MP3 files in your preferred cloud storage or local server. The API does not retain the audio, so you must save copies for your projects.
Keep your API key and property data secure. Since accounts are per site, ensure your credentials are stored securely within your automation environment.
Organize audio files by property ID and date. This structure makes it easy to sync audio with video timelines during post-production without losing track of specific listings.
Manage your billing
Vbee AI Voice uses a transparent, pay-as-you-go model where costs are calculated at $0.01 per 1,000 characters. You can fund your account via USDT (TRC-20) with a $5 minimum, and balances never expire. There are no monthly plans or subscriptions to manage.
Top up with USDT
Deposit funds using USDT on the TRON network. Transfers are credited automatically within minutes, allowing you to continue generating voiceovers without interruption. Ensure you use the TRC-20 standard to avoid delays.
- Minimum deposit: $5
- Network: TRON (TRC-20) only
- Crediting time: Within minutes
- Balance expiry: None
Monitor character count
Each request processes up to 4,096 characters, including spaces and punctuation. Your dashboard displays your current balance and characters remaining. Plan your scripts accordingly to avoid unexpected charges or truncation.
- Cost: $10 per 1 million characters
- Limit: 4,096 characters per request
- Includes: Spaces and punctuation
Track failed requests
If synthesis fails, the charge is returned in full. Monitor your usage logs to identify any errors and retry as needed. This ensures you only pay for successfully generated audio files.
Troubleshoot common issues
When integrating Vbee AI Voice into your virtual tour workflow, you may encounter specific technical hurdles. Understanding these common issues helps maintain your production schedule without unexpected delays.
Rate limit reached
You have 60 requests per minute. If you exceed this, requests queue or fail. Failed requests do not charge your balance.
- Check your key usage via /v1/voices
- Split bulk jobs into smaller batches
- Retry failed requests immediately
Invalid voice name
Ensure you use one of the eight valid presets. Names are case-sensitive. Refer to the /v1/voices endpoint for the current list.
- Valid: aria, nova, luna, sage, felix, milo, atlas, orion
- Check spelling carefully
Text too long
Each request supports up to 4096 characters. Exceeding this limit causes a 400 error. Split longer property descriptions into segments.
- Count characters including spaces
- Split logical sentences
- Join audio files later
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Freelancers can now showcase properties seamlessly with immersive virtual tours that captivate potential buyers instantly.
23 languages
Any voice speaks any of these languages.
