Text to Speech API: Integration Guide and Reference

By Audioguide Voice editorial team · Updated 2026-11-18

This documentation provides the reference guide for Audioguide Voice, the text-to-speech API designed for museum exhibits and travel content. It covers integration steps for non-technical users and developers, explaining how to convert text into engaging audio files using realistic, licensed voices.

You will learn how to generate keys, structure requests, and select from eight preset voices across 23 languages. The guide details rate limits, supported formats like MP3 and WAV, and practical examples to help you create high-quality audio for tourism and educational projects quickly.

Text to Speech API: Integration Guide and Reference

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email. Google sign-ins receive a $0.50 trial credit valid for 7 days. Email accounts start without trial credit. Your key appears on the dashboard alongside your balance and usage statistics.

What is the base URL for the API?

The API base URL is https://api.playabc77.com/v1. Use the endpoint POST https://api.playabc77.com/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models for retrieving available options.

Can I use the OpenAI Python SDK?

Yes. The request shape matches the OpenAI speech endpoint. Change the SDK’s base_url to https://api.playabc77.com/v1 and use your site’s key. The official OpenAI SDKs work directly with this configuration.

How do I specify the audio format?

Include the response_format field in your JSON body. Supported formats are mp3, wav, opus, flac, and pcm. Choose the format that best suits your deployment needs.

What are the rate limits?

You are limited to 60 requests per minute per key. New accounts start with a limit of 10 requests per minute until the first top-up is processed.

How do I handle long texts?

Split text into parts of up to 4096 characters. Send each part as a separate request and join the resulting audio files. This ensures all content is synthesized correctly.

What happens if the API fails?

Failed requests are free. If synthesis fails, the charge is returned in full. You can retry the request without incurring additional costs for the failed attempt.

How do I set the language explicitly?

Include the language field with an ISO code. If omitted, the system guesses from the script, defaulting Latin text to English. Explicitly set it for non-English Latin-script text.

Is the API compatible with cURL?

Yes. The API accepts standard JSON bodies via POST. You can use cURL with the Authorization header set to Bearer your-key. A ready cURL example is available on the dashboard.

Do I need to install a specific library?

No. You can use plain HTTP or the OpenAI SDK. There is no official proprietary library. Just send JSON requests to the endpoint with your authentication header.

How do I check my balance?

Visit the /get-api-key/ page after signing in. The dashboard displays your current balance, trial status, characters remaining, and usage history for your account.

Can I regenerate my API key?

Yes. You can issue a new key at any time from your dashboard. The old key stops working immediately when the new one is generated.

What is the character limit per request?

Each request supports up to 4096 characters in the input field. For longer texts, split your content into chunks of this size and combine the audio outputs.

How do I interpret the response?

The response contains the generated audio file. Failed requests return a status indicating the error but no charge is applied. Check the status code to confirm success.

First request

curl

curl https://api.playabc77.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.playabc77.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.playabc77.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 engaging audio for museum tours and travel videos without writing code. Start by signing up on the site to access your personal dashboard. You can register using Google for an instant free trial credit or use an email and password. Accounts are specific to this storefront.

Once registered, navigate to your dashboard to generate your unique API key. This key is the only credential needed to authenticate your requests. You can issue a new key at any time, which immediately invalidates the previous one, ensuring your access remains secure and controlled.

Sign Up on the Site

Visit the /get-api-key/ page to create your account. Google sign-up grants a $0.50 trial credit valid for seven days. Email-based accounts start without trial credit but allow immediate top-ups.

Your account is tied to this specific site. You can manage your balance and usage details directly from the dashboard interface provided.

  • Google or Email/Password registration
  • $0.50 trial credit with Google sign-up
  • Immediate access to dashboard

Generate Key from Dashboard

After logging in, locate the API key section in your dashboard. Click to generate a new key, which will appear as a string starting with 'tts-'. Copy this key securely.

Each account holds one active key at a time. Issuing a new key instantly stops the old one, so ensure your applications are updated promptly to avoid interruption.

  • Generate key from dashboard interface
  • Key format: 'tts-...' prefix
  • Instant invalidation of previous key

Use Bearer Token Auth

Include your API key in the HTTP header of every request. Use the format: 'Authorization: Bearer tts-your-key-here'. This authenticates your usage against your account balance.

The base URL for all requests is https://api.playabc77.com/v1. Ensure your key is sent with each POST request to /audio/speech or GET requests to /voices.

  • Header: Authorization: Bearer tts-...
  • Base URL: https://api.playabc77.com/v1
  • One active key per account

Make Your First Request

Sound wave illustration for: Make Your First Request

To generate audio, send a POST request to https://api.playabc77.com/v1/audio/speech with your Bearer token. The API accepts standard JSON bodies, making it easy to integrate with existing workflows without custom libraries.

JSON Body Structure

The request body contains configuration for the synthesis engine. You must specify the model, input text, voice, and output format. The API processes these fields to return the audio file directly in the response.

  • Method: POST
  • Endpoint: /v1/audio/speech
  • Content-Type: application/json

Required Fields

Every request needs four core parameters. The model must be either tts-1 or tts-1-hd. The input field holds your text, limited to 4,096 characters per call. Choose a voice from the eight available presets. Finally, set response_format to mp3, wav, opus, flac, or pcm.

  • model: "tts-1" or "tts-1-hd"
  • input: string (max 4096 chars)
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, pcm

Optional Parameters

Fine-tune the output with optional fields. Use speed (0.25–4.0) to adjust playback rate. Provide an ISO language code via language to ensure correct pronunciation, especially for non-English Latin script text. If omitted, the system guesses the language, defaulting to English for Latin scripts.

  • speed: 0.25 to 4.0
  • language: optional ISO code
Make Your First Request

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Since the API endpoint matches the OpenAI speech structure, you can reuse existing clients by simply pointing them to our base URL. This allows museum guides and travel content creators to integrate TTS into their workflows without rewriting core logic.

Change Base URL

Update your client configuration to use https://api.playabc77.com/v1 as the base URL. This ensures all requests route to our servers while maintaining standard compatibility.

Use Official SDKs

The official OpenAI SDKs work seamlessly with our endpoint. No proprietary library is required; just adjust the base URL and use your API key for authentication.

Python Example

Initialize the client with your base URL and key. Pass the text, voice, and model parameters directly. The SDK handles the JSON serialization and returns the audio binary.

  • Set base_url to https://api.playabc77.com/v1
  • Use tts-1 or tts-1-hd models
  • Authenticate with Authorization: Bearer header

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

The API returns audio in five distinct formats, allowing you to choose the right balance between file size and quality for your museum or travel content. Each format is generated directly from the same synthesis engine, ensuring consistent voice performance regardless of your selection.

You can specify the output type via the response_format parameter in your JSON request. This flexibility ensures optimal playback across different devices, from web browsers to standalone audio guides.

MP3 Compression

MP3 is a widely supported format for web and mobile applications. It offers significant file size reduction while maintaining clear speech intelligibility, making it ideal for streaming audio guides or embedding in travel videos where bandwidth matters.

  • Small file size reduces data usage for end-users

WAV Lossless

WAV provides uncompressed, high-fidelity audio perfect for professional editing or archival purposes. Use this format when you need to layer voiceovers with background music or perform further audio processing without generative quality loss.

  • Uncompressed quality for professional post-production

FLAC and OPUS Options

FLAC offers lossless compression, reducing file size compared to WAV without sacrificing audio quality. OPUS provides efficient compression suitable for low-bandwidth environments, ensuring smooth playback even on older mobile devices in remote tourist locations.

  • FLAC: Lossless, ~60% smaller than WAV
  • OPUS: Efficient compression for low-bandwidth areas

Voice Selection

Sound wave illustration for: Voice Selection

Choose the voice that fits your museum guide or travel video. You can select from eight distinct presets, each designed for specific narrative styles. Whether you need a calm instructional tone or an energetic promo, there is a voice for every context.

All voices are generated from licensed recordings and carry an inaudible watermark. You can mix and match voices across different languages without restriction.

8 Preset Voices

The API offers eight unique voice presets, ranging from warm narrators to deep documentary styles. Each voice is based on licensed LibriTTS-R recordings.

These presets cover a range of tones, allowing you to create audio guides or travel videos.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational
  • Atlas: Neutral, news
  • Orion: Deep, documentary

Gender and Tone Options

Voices are categorized by gender and tone to help you quickly find the right fit. Female voices like Aria and Nova offer clarity and brightness, while male voices like Orion provide depth and neutrality.

You can adjust the speed between 0.25 and 4.0 to match the pacing of your video or guide. This flexibility allows you to create audio for a museum exhibit or travel reel.

Voice Names

Each voice has a distinct name for easy reference in your API requests. Use the voice ID directly in the voice field of your JSON body to specify your choice.

The voice names are used to identify voices in your API requests. You can switch voices between requests without any additional setup, making it easy to test different tones.

All voices support all 23 languages, allowing you to use the same voice across different audio guides.

Voice Selection

Language Support

Sound wave illustration for: Language Support

Audioguide Voice supports 23 languages, covering major tourism markets including English, Spanish, French, German, Italian, Chinese, Japanese, Korean, Arabic, Hindi, Russian, Portuguese, Dutch, Swedish, Polish, Turkish, Greek, Hebrew, Finnish, Norwegian, Danish, Swahili, and Malay. Every voice can speak any of these languages natively.

This wide coverage ensures your museum audio guides and travel videos sound authentic for international visitors without needing multiple voice providers.

23 Languages

The API supports 23 specific languages. If you need a language not listed, such as Vietnamese, Ukrainian, or Thai, it is not currently supported.

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Auto-Detection

If you do not specify a language, the API guesses it from the text script. Latin script text defaults to English. For non-English Latin-script text, we recommend setting the language explicitly to avoid mispronunciation.

Explicit Language Code

Set the language parameter with an ISO code to ensure correct pronunciation. This is especially useful for mixed-language texts or when using Latin script for non-English languages.

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

The API enforces a strict rate limit of 60 requests per minute per key. This ceiling ensures stable performance for your audio generation workflows, whether you are producing short museum audio guides or longer travel narration segments. Monitoring your usage via the dashboard helps you stay within these bounds to avoid temporary throttling.

60 Requests Per Minute

Once you have topped up your account, you can send up to 60 synthesis requests in any 60-second window. This throughput is sufficient for batch-processing multiple voiceovers or handling moderate concurrent traffic without significant delays.

10 Requests Before Top-Up

New accounts or those without recent top-ups are limited to 10 requests per minute. This lower tier allows you to test the integration with your free trial credit or initial balance before scaling up your production volume.

Queue Behavior

Requests are processed sequentially. Under load, a request may wait in a queue before synthesis begins. Long texts take time to generate, so ensure your client handles asynchronous responses or implements exponential backoff if you receive 429 Too Many Requests errors.

  • Requests are processed one after another.
  • Short phrases take a few seconds.
  • Implement backoff for 429 errors.
Rate Limits and Quotas

Error Handling

Sound wave illustration for: Error Handling

Handling errors ensures your museum guide or travel video production runs smoothly. The API returns standard HTTP status codes to indicate whether synthesis succeeded or failed, allowing your application to react appropriately.

Common Error Codes

The API uses standard HTTP status codes. A 200 OK response means audio was generated successfully. Use 401 Unauthorized if your Bearer token is missing or invalid, and 429 Too Many Requests if you exceed the 60 requests per minute limit.

Character Limit Exceeded

Each request supports up to 4096 characters. If your script exceeds this, the API returns a 400 error. Split longer texts into smaller parts, generate the audio files, and join them to create complete guide narrations.

Invalid Voice ID

Ensure you use one of the eight supported voice presets (e.g., aria, nova, felix). If you reference an unknown voice ID, the API returns a 400 Bad Request error with a clear message identifying the issue.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Your audioguide turns every museum visit into a memorable, easy-to-create experience for all visitors.

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. curl documentation
  3. W3C WAI: making audio and video accessible
  4. ISO 639 language codes
  5. LibriTTS-R corpus (OpenSLR 141)
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Python documentation
  8. TRON developer hub: TRC-20
  9. Creative Commons Attribution 4.0
  10. openai-node on GitHub
  11. OpenAI API reference: create speech
  12. LibriVox public-domain audiobooks

More on this site