Frequently asked questions
What is the endpoint URL?
Send your POST request to https://api.play2288.com/v1/audio/speech. This endpoint accepts JSON bodies containing your text, voice selection, and desired audio format. It follows the same request shape as the OpenAI speech endpoint, allowing you to use official OpenAI SDKs by simply changing the base URL to https://api.play2288.com/v1.
How do I set the language explicitly?
Include the optional language field with an ISO code in your request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting this field ensures accurate pronunciation for non-English Latin-script texts, supporting 23 languages including Arabic, Chinese, and Japanese.
Can I stream the audio as it generates?
No, the API does not support streaming, WebSocket connections, or real-time partial audio delivery. You must wait for the full audio file to be generated and returned in the response. For long texts, split them into parts of up to 4096 characters and join the resulting audio files manually.
What is the maximum text length?
Each request supports a maximum of 4096 characters for the input field. For longer texts, you should split the content into smaller chunks of this size. After generating audio for each part, you can join the resulting audio files to create a continuous narration track for your tourism or museum guide content.
How do I handle rate limits?
Your API key is limited to 60 requests per minute. New accounts start with a limit of 10 requests per minute until the first top-up is processed. If you exceed this limit, requests may be delayed or rejected. Monitor your usage via the dashboard to ensure smooth operation for your audio guide projects.
Is the API synchronous or asynchronous?
The API is synchronous. You send a request and wait for the audio file to be returned in the response. Requests are processed one after another, so under load, your request may wait in a queue. Typical generation speed is roughly real-time, producing about 25 characters of text per second of audio.
Do I need to specify the model version?
You must specify the model using either "tts-1" or "tts-1-hd". Both models use the same engine and pricing structure, so the choice depends on your quality preference rather than cost differences. Include this field in the JSON body of your POST request to https://api.play2288.com/v1/audio/speech.
What happens if I exceed the rate limit?
If you exceed the 60 requests per minute limit, your requests may be processed with delays or rejected. Since requests are handled sequentially, high load can cause queuing. Ensure you stay within the 10 requests per minute limit for new accounts until you top up your balance to unlock the higher 60 requests per minute tier.
Can I use the same key for multiple projects?
Yes, each account has one active API key that can be used across multiple projects. You can issue a new key at any time, which immediately invalidates the old one. This allows you to rotate keys for security or to separate usage tracking between different tourism agencies or museum guide applications.
How do I rotate my API key?
You can issue a new API key at any time through your account dashboard. Once the new key is generated, the old key stops working immediately. This ensures that any compromised or unused keys from previous projects are instantly deactivated, maintaining security for your audio generation workflows without downtime.
What formats are best for mobile apps?
You can choose from mp3, wav, opus, flac, or pcm via the response_format field. For mobile apps, mp3 or opus are often preferred for their balance of quality and file size. These formats ensure efficient storage and playback on iOS and Android devices while maintaining the high quality needed for professional narration.
Does the API support SSML?
No, the API does not support SSML (Speech Synthesis Markup Language). You cannot use SSML tags to control pauses, emphasis, or pronunciation within the text input. If you need precise control, you must manage pauses and breaks by splitting your text into separate requests and joining the resulting audio files.
Can I adjust the pitch of the voice?
No, the API does not allow pitch adjustment. You can only adjust the speed parameter, which ranges from 0.25 to 4.0. This allows you to make the narration faster or slower, but the fundamental pitch of the voice remains constant. Choose from eight preset voices to find the tone for your content.
How do I know if a request failed?
Check the HTTP status code and response body for error details. Failed requests are free, and the charge is returned in full if synthesis fails. You can also monitor your usage and status via the dashboard, which tracks request metadata including time, characters, and status for billing and debugging purposes.
First request
curl
curl https://api.play2288.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.play2288.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.play2288.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 |
Getting Your API Key
Access the /get-api-key/ page to register using Google or an email address. This creates your account and generates the initial API key required for all audio synthesis requests.
Sign Up Process
Signing up with Google grants a $0.50 trial credit (approx. 50,000 characters) valid for seven days. Email-based accounts start without trial credit. Once registered, you can immediately view your key, balance, and usage statistics.
Key Management
Each account holds one active API key displayed on your dashboard. This key authenticates all requests to the https://api.play2288.com/v1 endpoint. Keep this key secure to ensure only your museum or agency uses your credit balance.
Key Rotation
You can issue a new API key at any time via the dashboard. When a new key is generated, the previous one stops working immediately. This allows you to rotate keys without downtime or losing your current billing data.
First Request with Curl
You can test the API immediately using curl. Send a POST request to the speech endpoint with your text and voice selection. The service returns the audio file directly in the response body, allowing you to save it locally or play it in your museum guide application.
This simple workflow lets you generate audio for audioguides without managing complex infrastructure. You control the output format and speed, ensuring the narration fits your specific tourism or museum project requirements perfectly.
Basic JSON Body
The request uses a standard JSON structure compatible with the OpenAI SDK. You provide the text input, select a voice preset, and define the output format.
This consistent shape allows you to switch between libraries easily while maintaining the same request logic for your tourism content generation pipeline.
Required Fields
You must specify the model (tts-1 or tts-1-hd), the input text (max 4096 characters), and the voice preset.
The Authorization header with your Bearer token is also required for authentication.
Response Format
A successful request returns the audio file directly in the response body with the appropriate content type (e.g., audio/mpeg).
If synthesis fails, you receive a JSON error object describing the issue, such as invalid input or rate limits.
Using the OpenAI SDK
Leverage the official OpenAI SDKs to integrate Voisite’s TTS API into your museum guide applications or tourism platforms with minimal code changes. The process is straightforward: you only need to adjust the base URL and provide your API key.
Base URL Configuration
Set the base_url parameter to https://api.play2288.com/v1 in your SDK client configuration. This directs all requests to our infrastructure while maintaining the standard request shape used by OpenAI-compatible clients.
Client Initialization
Initialize the client using your unique API key obtained from the dashboard. Ensure the key is passed in the Authorization header as Bearer <your-key>. This single key manages all your usage and billing.
Code Example
Below is a Python example using the OpenAI SDK to generate a museum tour audio clip. Replace YOUR_API_KEY with your actual key.
- from openai import OpenAI
- client = OpenAI(base_url="https://api.play2288.com/v1", api_key="YOUR_API_KEY")
- response = client.audio.speech.create(
- model="tts-1",
- voice="atlas",
- input="Welcome to the Royal Gallery. Please keep your voices down."
- )
Supported Parameters
Configure your audio generation with precision using our straightforward parameters. Select the engine that balances quality and cost, then choose a voice preset that matches your tour’s narrative tone.
Model Selection (tts-1, tts-1-hd)
Both tts-1 and tts-1-hd use the same engine and price. Choose tts-1-hd for slightly higher fidelity in museum exhibits, or tts-1 for rapid audioguide generation.
Voice Selection
Choose from 8 presets like aria for warm narration or atlas for neutral news-style updates. Every voice supports all 23 languages, ensuring consistent tone across international tours.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Speed Control
Adjust speed between 0.25 and 4.0 to fit your pacing needs. Slower speeds aid comprehension in complex exhibits, while faster rates help process longer audio guides efficiently.
Audio Formats
Choose your output format based on your delivery platform. MP3 offers a good balance of file size and compatibility, making it ideal for web-based audioguides and mobile apps where bandwidth matters.
For archival purposes or high-fidelity museum installations, WAV provides uncompressed audio. OPUS and FLAC are available if you need specific codec support for your existing infrastructure.
MP3 for Web Players
MP3 is the standard for most web players and mobile applications. It keeps file sizes small, ensuring faster loading times for your tourists on the go.
- Universal compatibility with HTML5 audio tags
- Smallest file size for efficient data usage
- Ideal for streaming on mobile networks
WAV for High Quality
Select WAV when you need uncompressed, studio-quality audio for high-end museum installations or local file storage. This format preserves every detail of the synthetic voice.
- Lossless audio quality
- No compression artifacts
- Perfect for professional archival
OPUS and FLAC Options
Use OPUS for efficient compression, or FLAC if you prefer lossless compression. Both formats support the full range of our voice presets.
- OPUS: Efficient streaming codec
- FLAC: Lossless compression
- Support for diverse technical workflows

Error Handling
When integrating Voisite into your museum guide workflows, understanding error responses ensures your audio players remain robust. Our API returns standard HTTP status codes, allowing you to implement precise retry logic for seamless audioguide experiences.
Rate Limit Errors
If you exceed 60 requests per minute, the API returns a 429 status. New keys start with a stricter limit of 10 requests per minute until the first top-up. Implement exponential backoff to handle queueing delays gracefully.
- Status Code: 429 Too Many Requests
- Retry after the specified header delay
Invalid Input Errors
Common errors include missing the input field or exceeding the 4096-character limit. Ensure your tourism content fits within these constraints. Failed synthesis requests are free, so you can retry without cost concerns.
- Status Code: 400 Bad Request
- Check
inputlength and required fields
Server Errors
Occasional 500 errors may occur during high load. Since requests are processed sequentially, queuing may cause slight delays. If a server error occurs, the charge is returned in full if synthesis fails.
- Status Code: 500 Internal Server Error
- Automatic refund if synthesis fails
Rate Limits
Voisite enforces a rate limit of 60 requests per minute per API key. This ensures consistent audio generation quality for tourism agencies and museum guides handling steady workloads. Each request counts toward this limit, regardless of text length or audio format.
60 Requests Per Minute
Your key allows up to 60 synthesis requests within any one-minute window. If you generate multiple audio files for a single tour, monitor your usage to avoid hitting this ceiling. This limit applies to all requests, including failed ones.
Initial Limit for New Keys
New keys start with a lower limit of 10 requests per minute. This applies until your first top-up is processed. Once you add funds via USDT (TRC-20), your limit increases to the full 60 requests per minute. This allows you to test the service with your trial credit before scaling up.
Queuing Behavior
Requests are processed sequentially. If you exceed the rate limit, subsequent requests may wait in a queue. Short phrases typically take a few seconds to generate, while longer texts take roughly one second per 25 characters. Under heavy load, generation times may increase slightly due to queuing.
Language Detection
For museum audio guides, accurate language detection simplifies batch processing. The API guesses the language from the script, defaulting to English for Latin text, which works well for standard English tours.
Automatic Detection
The system analyzes input characters to determine the likely language. This feature reduces configuration overhead when generating audio for diverse visitor groups in multiple languages.
Manual Language Code
For precision, send the ISO language code in the language field. This is essential for non-English Latin-script texts to prevent incorrect English narration.
Latin Script Default
If no language is specified, Latin script inputs are assumed to be English. Use explicit codes for Arabic, Chinese, or other scripts to ensure correct voice synthesis.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
