Vbee TTS API: Documentation, Voices & Integration

By Vbee AI Voice editorial team · Updated 2026-11-18

This documentation helps freelancers turn property scripts into natural-sounding audio for virtual tours. You will find clear examples for generating speech via cURL or the OpenAI SDK, including details on the eight voice presets and supported formats like MP3 and WAV.

Learn how to manage your API key, understand rate limits, and handle long texts by splitting them into 4096-character chunks. We cover request parameters, error handling, and pricing to ensure your workflow runs smoothly without unexpected delays or costs.

Vbee TTS API: Documentation, Voices & Integration

Frequently asked questions

How do I get an API key?

Sign up at /get-api-key/ using Google or email. You receive one active key per account. You can issue a new key anytime; the old one stops immediately. Keys start with 'tts-'. Use the Authorization header with your key to authenticate requests.

What is the base URL?

The API base URL is https://api.playjay9.com/v1. Send POST requests to /audio/speech. Use GET /v1/voices for details and GET /v1/models for model info. This endpoint structure matches the OpenAI speech endpoint format for easy integration.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.playjay9.com/v1. Use your Vbee API key for authentication. The request shape is identical to the OpenAI speech endpoint, allowing you to reuse existing code with minimal configuration changes.

What models are available?

Two models are available: 'tts-1' and 'tts-1-hd'. Both use the same engine and price. Select the model in your request body. The choice does not affect cost, which is $10 per 1 million characters regardless of the model selected.

How many characters per request?

Each request supports up to 4096 characters in the 'input' field. For longer texts, split your script into parts of this size. Generate audio for each part separately and join the resulting audio files to create the final output.

What voices can I use?

Eight voices are available: aria, nova, luna, sage, felix, milo, atlas, and orion. Any voice can speak any of the 23 supported languages. Specify the voice in your request. If language is unset, it is guessed from the script.

Which formats are supported?

Supported response formats are mp3, wav, opus, flac, and pcm. Specify your preferred format in the 'response_format' field. The audio is returned directly in the response. Generated files include an inaudible watermark marking them as synthetic speech.

What is the rate limit?

The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so under load, you may experience queueing delays. Failed requests do not count toward usage.

How do I handle errors?

If synthesis fails, the charge is returned in full. Check your response status codes. Ensure your text is under 4096 characters and your API key is valid. Use the /docs/ page for reference on request structure and common parameters.

How do I play long audio?

Split text into chunks of 4096 characters. Send each chunk as a separate request. Receive the audio files for each part. Join these audio files sequentially to play the complete long audio. This ensures reliable generation within character limits.

Is the API synchronous?

Yes, the API is synchronous. You send a request and wait for the audio file in the response. Typical speed is roughly 25 characters of text per second of generation. Requests are queued if under load, so longer texts may take more time.

Can I stream the audio?

No, streaming is not supported. The API returns the complete audio file in the response body. You cannot receive partial audio chunks or use WebSocket for real-time playback. You must wait for the full file to be generated and returned.

Do I need to install a library?

No library is required. You can use plain HTTP requests or the official OpenAI SDK. No custom SDK is provided. Use standard HTTP libraries available in your preferred programming language to send POST requests to the speech endpoint.

How do I test the API?

Use the ready curl example on /get-api-key/. You can also use the OpenAI SDK with the adjusted base_url. Ensure you have a valid API key. Test with short texts first to verify voice, format, and speed settings work correctly.

First request

curl

curl https://api.playjay9.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.playjay9.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.playjay9.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

Create your account on the Vbee AI Voice site to access the API. You can register using your Google account or by providing an email address and password. This account is specific to this storefront and allows you to manage your usage and billing.

Once registered, you will have access to your unique API credentials. These credentials are required to authenticate your requests when sending text to the speech endpoint.

Sign up on the site

Sign up on the site

Navigate to the /get-api-key/ page to begin the registration process. The system creates an account immediately upon completion of the sign-up form.

Choose Google or email

Choose Google or email

Select Google for quick setup, which includes a $0.50 free trial credit valid for 7 days. Alternatively, use an email and password combination, which does not include trial credit but provides full access to the API.

Your account is tied to the specific site domain. Ensure you are creating an account on playjay9.com to receive the correct API key.

  • Google sign-up includes $0.50 trial credit.
  • Email sign-up has no trial credit.
  • Accounts are per site.

Copy your Bearer token

Locate your API key on the dashboard. It appears as a string starting with 'tts-'. This token serves as your Bearer authentication for all API requests.

Keep this key secure. You can issue a new key at any time, which will immediately invalidate the previous one.

  • Key format: tts-...
  • Auth header: Authorization: Bearer <key>
  • One active key per account.

View usage details

The dashboard displays your current balance, characters remaining, and usage history. This helps you monitor consumption against the rate limits and billing requirements.

Use the provided curl example to test your key immediately after copying it.

  • Balance and character count displayed.
  • Ready-to-use curl example provided.

Make your first request

Sound wave illustration for: Make your first request

Send your property script to the speech endpoint. The API processes the text and returns the generated audio file directly in the response body.

Use cURL command

Use this command to test the endpoint. Replace YOUR_API_KEY with your token from the dashboard.

  • curl -X POST https://api.playjay9.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Welcome to this stunning 3-bedroom home...", "voice": "nova"}'

Send POST to /v1/audio/speech

Post a JSON body with model, input, and voice. You can also set response_format and speed. The text limit is 4096 characters.

Receive audio file in response

The response contains the audio binary. Save it as mp3 or wav. Use this file in your virtual tour player.

Use the OpenAI SDK

Sound wave illustration for: Use the OpenAI SDK

Leverage familiar tools by pointing the OpenAI SDK to our infrastructure. This allows you to use existing codebases with minimal modification, ensuring a smooth transition for developers already accustomed to standard TTS workflows.

The API mirrors the official request shape exactly. You only need to adjust the base URL to https://api.playjay9.com/v1 while keeping your authentication and payload structure identical to standard implementations.

Change base_url

Update your SDK configuration to point to our API endpoint. Replace the default base URL with https://api.playjay9.com/v1 to direct requests to our servers. Your existing Bearer token works seamlessly with this new endpoint.

  • Base URL: https://api.playjay9.com/v1
  • Auth: Bearer tts-... key

Keep same request shape

The JSON body remains identical to the OpenAI specification. Use model (tts-1 or tts-1-hd), input (text), and voice parameters exactly as documented. No custom fields are required for basic synthesis.

Use official SDKs

Any official OpenAI SDK (Python, Node.js, etc.) works out of the box. Simply configure the base URL as described above. This ensures compatibility with standard libraries without needing a dedicated Vbee client.

Request parameters

Sound wave illustration for: Request parameters

Define the synthesis parameters to control audio quality, input length, and voice selection. Each request specifies the model, the text to convert, and the target voice preset.

Model: tts-1 or tts-1-hd

Select "tts-1" for standard speed or "tts-1-hd" for higher fidelity. Both use the same engine and price: $10 per 1 million characters.

Input: text up to 4096 chars

Pass your property description or tour script in the input field. The limit is 4096 characters per request, including spaces and punctuation.

Voice: 8 presets available

Choose from 8 presets tailored for clear narration. Select voices like sage for calm instructions or felix for energetic promo updates.

  • Aria: warm, clear narrator
  • Nova: bright, upbeat
  • Luna: soft, storytelling
  • Sage: calm, instructional
  • Felix: energetic, promo
  • Milo: friendly, conversational

Response formats

Sound wave illustration for: Response formats

The API returns audio in four standard formats, letting you choose the right balance of quality, file size, and compatibility for your real estate workflows. Selecting the correct format ensures smooth playback in web viewers or high-fidelity editing in your preferred software.

All formats include the standard synthetic watermark and respect the character limits defined in the request body. Failed requests remain free regardless of the chosen format.

MP3 for web players

MP3 is the default choice for embedding audio directly into property listing pages or virtual tour interfaces. Its broad compatibility ensures that prospective buyers can listen to your voiceover on any device without needing special plugins or codecs.

Use this format when you need small file sizes for fast loading, especially on mobile connections. The compression maintains sufficient clarity for spoken property descriptions while minimizing bandwidth usage.

  • Ideal for HTML5 audio tags
  • Small file size for quick loading
  • Universal browser support

WAV for editing

WAV provides uncompressed, lossless audio, making it a good option for post-production. If you plan to add background music, adjust volume levels, or perform noise reduction in software like Audacity or Adobe Audition, WAV preserves the full fidelity of the synthesis.

This format is larger than MP3 but ensures no quality is lost during editing. It is suitable for final deliverables where audio quality is prioritized over file size.

  • Lossless quality
  • Best for post-production
  • Larger file size

OPUS for efficiency

OPUS offers high compression efficiency, resulting in smaller file sizes while maintaining good audio quality. This format is ideal if you need to store large volumes of voiceovers or have strict bandwidth constraints.

It is well-supported in modern web technologies and mobile applications. Choose OPUS when minimizing storage and transfer costs is a priority for your virtual tour platform.

  • High compression ratio
  • Modern web support
  • Low bandwidth usage
Response formats

Rate limits and queues

Sound wave illustration for: Rate limits and queues

The API allows 60 requests per minute for each active key. This limit applies to successful and failed synthesis attempts, helping you manage burst traffic during property listing uploads.

60 requests per minute

Each active key supports a maximum of 60 requests per minute. This steady limit suits most freelance workflows where voiceovers are generated sequentially for virtual tours or listing descriptions.

  • Limit applies per API key, not per account.
  • Failed requests do not count toward the limit.
  • No monthly plans or tiered limits.

10 requests before top-up

New accounts start with a limit of 10 requests per minute. This lower threshold remains until you make your first top-up via USDT (TRC-20). Once funded, the limit increases to 60 requests per minute immediately.

  • Minimum top-up is $5.
  • Credit is added automatically within minutes.
  • No subscription required to increase limits.

Processing in queue order

Requests are processed one after another. If you send multiple requests simultaneously, they wait in a queue based on arrival time. Longer texts may take more time to generate, so plan your script splits accordingly to avoid delays.

  • Processing is sequential, not parallel.
  • Queue order determines generation sequence.
  • Short phrases take a few seconds.

Handling errors

Sound wave illustration for: Handling errors

The API returns standard HTTP status codes to indicate success or failure. A 200 OK response means your audio file is ready. Other codes, such as 400 or 429, signal specific issues that require attention before proceeding.

Understanding these responses ensures your integration handles failures gracefully. This is crucial when generating voiceovers for real estate listings, where you need reliable audio files to pair with property visuals.

Check HTTP status code

Always inspect the HTTP status code returned by the API. A 200 status confirms successful synthesis. Codes like 400 indicate invalid parameters, while 429 means you have hit the rate limit of 60 requests per minute.

If you see a 401 error, your authentication token is invalid or expired. Ensure you are sending the correct Bearer token in the Authorization header.

  • 200: Success, audio file included in response
  • 400: Bad request, check input parameters
  • 401: Unauthorized, verify your API key
  • 429: Too many requests, wait before retrying

Review error message

The response body contains a detailed error message explaining the issue. Read this message carefully to understand what went wrong. Common errors include invalid voice names or text exceeding the 4096 character limit.

For example, if you send text in a language not supported, the API will return a clear error. This helps you quickly correct your script before generating the final audio file.

  • Invalid voice ID provided
  • Text exceeds 4096 character limit
  • Unsupported language code
  • Insufficient balance for request

Retry if necessary

If an error is transient, such as a temporary network issue, you can retry the request. Wait a few seconds before retrying to avoid hitting rate limits again. Use exponential backoff for better reliability.

For persistent errors, such as an invalid API key, do not retry immediately. Instead, check your account settings on the dashboard to ensure your key is active and correct before trying again.

  • Wait 1-2 seconds before retrying
  • Use exponential backoff for repeated failures
  • Check API key validity for 401 errors
  • Verify input parameters for 400 errors

Long text handling

Sound wave illustration for: Long text handling

For property listings or virtual tour scripts exceeding 4,096 characters, you must split the text into smaller parts. Each segment is processed as a separate request to the API.

Generate audio files for each segment individually. Once all parts are received, join them sequentially to create the final continuous audio file for your project.

Split into 4096 char parts

Divide your script so each part contains no more than 4,096 characters. This limit applies to the input text, including spaces and punctuation.

Generate separate audio

Send each text segment to the POST /v1/audio/speech endpoint. The API returns an audio file for each request, processed in queue order.

Join files for final output

Concatenate the returned audio files in the correct order to form the complete voiceover. This ensures seamless playback for your virtual tour or listing.

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.

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. IETF RFC 7845: Ogg Opus
  3. ISO 639 language codes
  4. Creative Commons Attribution 4.0
  5. Tether (USDT)
  6. FFmpeg documentation
  7. curl documentation
  8. TRON developer hub: TRC-20
  9. LibriTTS-R corpus (OpenSLR 141)
  10. MDN: Web Speech API
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. Node.js documentation

More on this site