API Documentation for Tourism Text-to-Speech

By VoxVoyage editorial team · Updated 2026-11-18

This documentation helps tourism and museum creators generate natural-sounding audio guides using a simple API. You do not need coding experience; just paste your script and download the audio files. We provide clear steps for testing with curl, integrating with the OpenAI SDK, and selecting the right voice for your specific content.

You will find details on supported formats like MP3 and WAV, voice options such as Aria and Atlas, and how to handle long texts by splitting them into chunks. The guide also covers rate limits, error handling, and account setup. Use this page to quickly integrate high-quality synthetic speech into your museum tours or travel apps.

API Documentation for Tourism Text-to-Speech

Frequently asked questions

How do I get my API key?

Sign up on https://playmcww.com/get-api-key/ using Google or email. Your key starts with tts-. You can issue a new key at any time, which immediately invalidates the old one. The dashboard displays your key, balance, and usage statistics.

What is the base URL for the API?

Use https://api.playmcww.com/v1 as your base URL. This allows official OpenAI SDKs to work by changing the base_url. Send POST requests to /v1/audio/speech. You can also check available voices and models via GET /v1/voices and GET /v1/models.

Can I use the Python OpenAI SDK?

Yes. The API uses the same request shape as the OpenAI speech endpoint. Simply configure your OpenAI SDK client to use https://api.playmcww.com/v1 as the base_url and provide your VoxVoyage API key. No custom library is required.

What is the maximum character limit per request?

Each request supports up to 4096 characters. For longer scripts, split the text into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit. Failed requests do not consume your character allowance.

How do I specify the voice?

Include the voice parameter in your JSON body. Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice can speak all 23 supported languages, but you should set the language parameter for non-English text to ensure accuracy. If unspecified, the system guesses the language from the script.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key (10 before first top-up). Requests are processed sequentially, so excess requests wait in a queue. Requests are processed sequentially, so excess requests wait in a queue. You may experience delays if the queue is long.

Can I use SSML tags?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. It accepts plain text input. For precise control, you must split your text manually and adjust parameters like speed or voice selection in separate requests.

Is streaming supported for audio?

No. The API returns the complete audio file in the response body. There is no WebSocket or real-time partial audio streaming. You must wait for the full synthesis to complete before receiving the audio data for your museum guide.

How do I handle errors in my code?

Check the HTTP status code and response body for error details. Failed synthesis requests are free, so the charge is returned in full. Implement retry logic for transient errors, keeping in mind the 60 requests per minute rate limit.

Do I need to install a specific library?

No. You can use the official OpenAI SDK, plain HTTP requests, or any HTTP client library. The API is designed to be compatible with standard HTTP methods and JSON formats, requiring no proprietary software or specific vendor libraries.

What is the default response format?

The default format is mp3 (if not specified). You can specify other formats like wav, opus, flac, or pcm via the response_format parameter. Each generated file contains an inaudible watermark marking it as synthetic speech. All formats are returned directly in the response.

Can I change the speed of the audio?

Yes. Use the speed parameter with values between 0.25 and 4.0. This allows you to adjust the narration pace for your museum audio guides. The default speed produces audio at roughly real-time length (about 25 characters per second) for long texts.

Is the API synchronous or asynchronous?

The API is synchronous. You send a POST request and wait for the response containing the audio file. Requests are processed one after another, so under load, your request may wait in a queue before synthesis begins.

How do I authenticate my requests?

Include the header Authorization: Bearer tts-<your-key> in every request. Each account has one active key. You can generate a new key at any time via the dashboard, which immediately invalidates the previous key for security purposes.

First request

curl

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

To begin generating audio guides for your museum or tour, start by creating an account at https://playmcww.com/get-api-key/. You can sign up instantly using your Google account or by providing an email address and password. This step is required to access the API key needed for all subsequent requests.

Sign up via Google or email

Sign up via Google or email

Creating an account takes less than a minute. Google sign-up includes a $0.50 free trial valid for 7 days, giving you about 50,000 characters to test the service. Email-based accounts start without trial credit but are otherwise identical.

Find your key on the dashboard

Find your key on the dashboard

After signing in, navigate to the dashboard to view your unique API key. The interface displays your current balance, characters remaining, and a ready-to-use curl example. You can copy this key directly into your applications or scripts.

One active key per account

Each account maintains only one active API key at a time. If you need a new key, you can issue a replacement at any time; the previous key stops working immediately. This ensures simple security management for your tour projects.

Make Your First Request

Sound wave illustration for: Make Your First Request

To generate your first audio guide, send a POST request to the speech endpoint with your API key. This method allows immediate testing without installing additional libraries.

Curl example for quick testing

Use this command to verify your setup. Replace YOUR_API_KEY with your actual key from the dashboard.

  • curl -X POST https://api.playmcww.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Welcome to our museum.", "voice": "nova", "response_format": "mp3"}'

JSON body structure

The request body is a standard JSON object containing the parameters for synthesis.

Required fields: model, input, voice

You must specify the model (tts-1 or tts-1-hd), the input text (max 4096 characters), and the voice preset. The input field contains the script text for your audio guide.

Use the OpenAI SDK

Sound wave illustration for: Use the OpenAI SDK

VoxVoyage’s TTS API mirrors the OpenAI speech endpoint structure, allowing you to leverage existing OpenAI SDKs with minimal configuration. This compatibility simplifies integration for tourism and museum teams who want to generate audio guides without learning a new library.

Change base_url to our endpoint

To use the official OpenAI SDKs, simply update the base_url configuration to point to our API infrastructure. Set the base URL to https://api.playmcww.com/v1 instead of the default OpenAI endpoint. This redirects all requests to our servers while maintaining standard SDK behavior.

  • Base URL: https://api.playmcww.com/v1
  • Authentication header: Authorization: Bearer tts-...

Use official OpenAI libraries

You can use any official OpenAI SDK (Python, Node.js, etc.) to interact with the endpoint. The libraries handle request formatting and response parsing automatically, reducing the need for custom HTTP code in your museum guide applications.

Same request shape as OpenAI

The JSON body structure is identical to the OpenAI speech endpoint. Pass your model, input text, voice, and response_format exactly as you would for OpenAI. This consistency means your existing code logic for handling responses remains valid.

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

Choose the format that matches your delivery channel. MP3 provides the best balance of file size and quality for web players and mobile apps. WAV offers uncompressed audio for professional editing or high-fidelity kiosks. FLAC ensures lossless storage for archival purposes, but file sizes are larger than MP3.

MP3 for web and mobile

MP3 is the recommended format for most tourism applications. It loads quickly on standard connections and plays reliably on iOS and Android devices. Use this format for audio guides delivered via web browsers or standard mobile applications where bandwidth efficiency matters.

  • Smallest file size among supported formats (MP3)
  • Universal playback support on all devices
  • Ideal for streaming over standard mobile networks

WAV for high quality

WAV files provide uncompressed, high-quality audio. Choose this format when you need to edit the generated voiceovers in professional software or distribute them to high-end audio kiosks. WAV files are larger than MP3 but retain the full fidelity of the synthesis engine.

  • No compression artifacts
  • Direct import into audio editing software
  • Best for local playback on dedicated devices

FLAC for lossless storage

FLAC offers lossless compression, preserving every detail of the generated speech while keeping file sizes smaller than WAV. Use this format for archiving your museum’s audio library. It ensures long-term quality without the storage overhead of uncompressed WAV files.

  • Lossless compression preserves audio integrity
  • Smaller than WAV, larger than MP3
  • Perfect for permanent museum archives

Voice Selection Guide

Sound wave illustration for: Voice Selection Guide

Selecting the correct voice ensures your audio guide matches the museum’s atmosphere. Our eight preset voices are engineered for clarity and natural flow, making them ideal for static scripts that visitors listen to at their own pace.

Female voices: Aria, Nova, Luna, Sage

Aria offers a warm, clear narrator style suitable for general exhibits. Nova provides a bright, upbeat tone for interactive displays. Luna’s soft, storytelling voice works well for historical narratives. Sage delivers a calm, instructional tone for technical or procedural guides.

Male voices: Felix, Milo, Atlas, Orion

Felix brings an energetic, promo-like energy to short highlights. Milo sounds friendly and conversational, perfect for modern art or casual tours. Atlas provides a neutral, news-style delivery for factual exhibits. Orion’s deep, documentary voice suits serious historical or scientific contexts.

Choosing the right tone for tours

Match the voice to the content’s emotional weight. Use Luna or Orion for deep historical stories, and Nova or Milo for light, engaging museum entrances. Ensure the voice remains consistent across all chapters of your guide to maintain a professional, cohesive experience for your visitors.

  • Use consistent voices for related exhibits
  • Test voices with sample script segments
  • Avoid mixing tones within a single tour
Voice Selection Guide

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Your API key processes requests at a steady pace, designed for batch audio generation rather than instant streaming. Understanding these limits helps you plan museum guide production efficiently without unexpected interruptions during peak usage periods.

60 requests per minute

Once fully active, your account allows up to 60 requests per minute. This capacity is sufficient for generating standard audio guides in reasonable timeframes, even for longer scripts split into multiple chunks.

10 requests per minute initially

New accounts start with a lower limit of 10 requests per minute. This initial restriction helps manage server load while you test the API with short phrases or sample texts before scaling up.

Limit increases after top-up (to 60 requests/minute)

The rate limit increases to 60 requests per minute automatically after you add funds. Top-ups via USDT on the TRON network are processed within minutes, allowing you to resume high-volume generation quickly.

  • Minimum top-up is $5
  • Credits do not expire
  • No monthly subscription required

Handling Long Texts

Sound wave illustration for: Handling Long Texts

Audio guides often exceed the 4,000-character limit per request. You must split your script into smaller parts and generate each chunk separately. This ensures every segment is synthesized correctly without truncation.

Split text into 4096 char chunks

Treat spaces and punctuation as characters when counting. Divide your tour script into segments no longer than 4,096 characters. This limit applies to each individual API call.

Join audio files programmatically

Receive each audio file via the API response. Concatenate the files in order using simple scripting or a media library. The resulting file plays as a single continuous guide.

Maintain consistent voice

Use the same voice preset for all chunks of one script. This ensures the audio guide sounds like one narrator speaking. Avoid switching voices mid-tour.

Error Codes and Handling

Sound wave illustration for: Error Codes and Handling

Errors return standard HTTP codes so you can handle failures programmatically. Failed synthesis requests are free, meaning you are not charged for audio that does not generate successfully.

Common HTTP status codes

Use 400 for bad requests, 401 for authentication issues, and 429 for rate limits. Check the response body for a clear message explaining the failure.

Invalid input errors

Ensure the input text does not exceed 4096 characters. Provide a valid voice name from the supported list and verify your API key is correct in the header.

  • Input must be under 4096 characters
  • Voice must be one of the 8 presets
  • Model must be 'tts-1' or 'tts-1-hd'

Rate limit exceeded messages

You have a limit of 60 requests per minute. New accounts start with 10 requests per minute. The limit increases automatically after you add funds.

  • Standard limit: 60 requests/minute
  • Initial limit: 10 requests/minute
  • Top-up via USTRC20 increases limits

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This feedback loop ensures your final audio guide meets visitor expectations without unnecessary rework.

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

More on this site