API Documentation for Museum Narration Systems

By Voisite editorial team · Updated 2026-11-18

This documentation helps tourism agencies and museum guides integrate Voisite’s text-to-speech API into their narration systems. You will find concrete examples for generating audio from text, configuring voices, and managing your account key. The guide covers everything from your first request to handling errors, ensuring you can scale your audioguide content efficiently without hiring additional voice talent.

We assume you are building audio tours, video tours, or digital museum exhibits. You will learn how to use standard HTTP requests or the OpenAI SDK to produce high-quality speech in 23 languages. Each section provides specific parameters and code snippets tailored to the needs of consistent, professional-grade narration for institutional audiences.

API Documentation for Museum Narration Systems

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

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

Getting Your API Key

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

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

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

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

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

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

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

Error Handling

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

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

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

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. LibriTTS-R paper (arXiv 2305.18802)
  3. openai-python on GitHub
  4. Tether (USDT)
  5. openai-node on GitHub
  6. IETF RFC 7845: Ogg Opus
  7. FFmpeg documentation
  8. MDN: Web Speech API
  9. curl documentation
  10. W3C WAI: making audio and video accessible
  11. LibriVox public-domain audiobooks
  12. ISO 639 language codes

More on this site