Get Started with Our Cloud Text-to-Speech API

By MuseumEcho editorial team · Updated 2026-11-19

This guide walks you through integrating MuseumEcho’s text-to-speech API into your startup’s workflow. We provide a reliable service for generating audioguides, museum tours, and accessible travel content, allowing you to focus on user experience while we handle voice synthesis. You will learn how to authenticate, structure requests, and manage audio output efficiently.

You will get your API key, make your first request using cURL or the OpenAI SDK, and understand rate limits and error handling. The documentation covers supported models, audio formats, and available voices. This step-by-step approach ensures you can start generating synthetic speech for your tourism applications.

Get Started with Our Cloud Text-to-Speech API

Frequently asked questions

What is the API endpoint?

Send a POST request to https://api.siap234.cc/v1/audio/speech. Include your JSON body with the text, voice, and model parameters. This endpoint handles the synthesis and returns the audio file.

How do I authenticate?

Include your API key in the request header as Authorization: Bearer tts-.... You receive one active key per account. Ensure the key is valid before sending requests to avoid authentication errors.

Can I use Python SDK?

Yes, the official OpenAI SDKs work perfectly. Change the base_url to https://api.siap234.cc/v1 and use your MuseumEcho key. This allows you to use familiar Python code without learning a new library.

What is the base URL?

The base URL is https://api.siap234.cc/v1. Configure your HTTP client or SDK to use this prefix. All other endpoints, like /audio/speech or /voices, append to this base URL.

Does it support streaming?

No, the API does not support streaming, WebSocket connections, or real-time partial audio. You receive the complete audio file after the request finishes processing.

What is SSML support?

SSML is not supported. The API accepts plain text input only. You cannot use SSML tags for pronunciation or pacing adjustments. Use the speed parameter to adjust the overall voice speed.

How do I handle errors?

Failed requests are free, and the charge is returned in full. Check the response status code for errors like rate limits or invalid input. Inspect the error message to correct your request parameters.

What happens if I hit the rate limit?

You are limited to 60 requests per minute per key (10 before top-up). If you exceed this, requests may wait in a queue or return an error. Monitor your usage to stay within limits.

Can I send large texts?

Yes, but each request is limited to 4096 characters. If your text exceeds this, split it into smaller parts. Send each part separately and join the resulting audio files later.

How do I split long texts?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the API. Then, concatenate the returned audio files to create the final audio track.

What is the character limit?

The maximum input length per request is 4096 characters. Spaces and punctuation count toward this limit. For longer content, you must split the text and process it in multiple requests.

Is there a webhook?

No, there is no webhook support. The API is synchronous; you wait for the response containing the audio file. You cannot register a URL to receive notifications when synthesis completes.

Can I use multiple keys?

Each account has one active key. You can issue a new key at any time, but the old one stops immediately. Use the new key for subsequent requests after rotation.

How do I revoke a key?

Revoke a key by issuing a new one. The old key stops working immediately when the new one is active. You can generate a new key from your account dashboard.

First request

curl

curl https://api.siap234.cc/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.siap234.cc/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.siap234.cc/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 start generating audio, you need an API key. Create an account on our /get-api-key/ page using your Google credentials or an email and password. This account is specific to this storefront and will hold your credits and key.

Once registered, navigate to your dashboard to view your unique key and current balance. You can issue a new key at any time; the previous one becomes invalid immediately, ensuring secure access for your startup's audioguide projects.

Sign up on site

Sign up on site

Visit the registration page to create your account. You can sign up using Google for quick access or use a standard email and password combination. Accounts are created per site, so this key works specifically for siap234.cc.

  • Google or email/password sign-up options available
  • Accounts are specific to this storefront

Copy key from dashboard

Copy key from dashboard

After logging in, access your dashboard to find your API key. It is displayed prominently alongside your current balance and usage statistics. Copy this key to use in your application headers or SDK configurations.

Single active key

You have one active key per account. If you need to rotate credentials for security, you can issue a new key at any time. The old key stops working immediately, so ensure your application updates before the old key expires if needed.

  • Issue a new key anytime
  • Old key stops immediately

First Request with cURL

Sound wave illustration for: First Request with cURL

Send your first synthesis request using a simple HTTP POST. The endpoint processes text and returns the audio file when synthesis is complete. This method works for any integration, from scripts to web apps, ensuring you get control over the raw data.

The API expects a JSON body with specific fields. You define the model, input text, voice, and output format. Keep text under 4,096 characters per call to stay within single-request limits.

POST endpoint

Send requests to https://api.siap234.cc/v1/audio/speech using the POST method. Include your API key in the Authorization header as Bearer tts-.... The endpoint accepts standard JSON payloads and returns audio files directly.

JSON body structure

The request body requires model, input, and voice. You may also specify response_format (mp3, wav, opus, flac, pcm) and speed (0.25–4.0). The input field holds your text, limited to 4,096 characters.

Example request

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

Using OpenAI SDK

Sound wave illustration for: Using OpenAI SDK

Since our API endpoint mirrors the OpenAI speech structure, you can reuse your existing OpenAI SDK clients by simply pointing them to our base URL. This allows you to reuse your existing OpenAI SDK clients by simply pointing them to our base URL.

Change base_url

Update your client configuration to use https://api.siap234.cc/v1 as the base URL. Ensure your Authorization header includes your Bearer token from the dashboard.

Use official SDKs

The official OpenAI SDKs work directly with this configuration. You can continue using your preferred language bindings (Python, Node.js, etc.) with minimal code changes.

Code snippet

```python import openai client = openai.OpenAI(base_url="https://api.siap234.cc/v1", api_key="tts-your-key") response = client.audio.speech.create( model="tts-1", voice="nova", input="Welcome to the museum.", response_format="mp3" ) response.stream_to_file("output.mp3") ```

Supported Models

Sound wave illustration for: Supported Models

The API offers two model variants, tts-1 and tts-1-hd, which utilize the same underlying engine for voice synthesis. You can switch between them by changing the model field in your request JSON without altering your integration logic or voice presets.

Both models support the full range of eight voice presets and all 23 languages. The choice affects audio fidelity rather than voice character or language capability, allowing you to test quality differences without reconfiguring your application.

tts-1 standard

The tts-1 model provides efficient, real-time generation suitable for most audioguide and travel content applications. It processes text at roughly 25 characters per second, making it suitable for standard speech synthesis.

  • Optimized for speed and standard clarity
  • Default choice for most tourism applications

tts-1-hd higher quality

Select tts-1-hd when you require enhanced audio fidelity, such as for premium museum tours or high-end accessible content. This model produces richer sound with better handling of intonation and pacing.

  • Enhanced audio fidelity
  • Better intonation handling

Same price

Both models are priced identically at $10 per 1 million characters. You can upgrade to tts-1-hd for specific high-quality segments without increasing your cost per character, allowing you to balance budget and audio quality freely across your content.

Audio Formats

Sound wave illustration for: Audio Formats

We support MP3, WAV, OPUS, FLAC, and PCM to fit various deployment needs. MP3 is the standard for web players, offering small file sizes with good quality. WAV provides uncompressed audio for maximum fidelity in local apps. OPUS offers efficient compression, while FLAC provides lossless compression, suitable for mobile data saving or archival. PCM provides raw audio data for real-time processing pipelines.

MP3

MP3 is the default format for most web-based audioguides. It balances file size and quality, ensuring fast loading times for users on mobile networks. Use this format for general listening experiences in tourism apps.

  • Default choice for web players
  • Small file size for quick loading
  • Compatible with all modern browsers

WAV

WAV provides uncompressed audio, preserving the full quality of the generated voice. This format is ideal for local applications where file size is less critical than fidelity. Use WAV when you need pristine audio for editing or high-end playback systems.

  • Uncompressed, lossless quality
  • Ideal for local applications
  • Maximum fidelity for editing

OPUS, FLAC, PCM

OPUS offers high-quality compression, reducing bandwidth usage without sacrificing clarity. FLAC provides lossless compression, perfect for archiving audioguide content. PCM delivers raw audio data, suitable for real-time processing pipelines that need immediate access to audio samples.

  • OPUS: Efficient compression for mobile
  • FLAC: Lossless archival quality
  • PCM: Raw data for pipelines
Audio Formats

Rate Limits

Sound wave illustration for: Rate Limits

Rate limits ensure stable generation for your museum tour app. Each API key is capped at 60 requests per minute, preventing sudden spikes from overwhelming the synthesis engine. This limit applies uniformly regardless of text length or voice model selected.

60 requests per minute

Once your account is active and funded, you can send up to 60 synthesis requests every minute. This throughput is suitable for batch-processing workflows, such as generating audioguide segments.

10 before first top-up

New accounts start with a lower limit of 10 requests per minute. This applies to free trial credits and initial usage before your first top-up. Once you add USDT to your balance, the limit increases to 60 requests per minute immediately.

  • Trial accounts: 10 requests/minute
  • Top-up required for 60 requests/minute
  • Limit resets every 60 seconds

Queue handling

Requests are processed sequentially within the minute window. If you exceed the limit, additional requests may wait in a queue. Longer texts take more time to synthesize, so high-volume applications should space out requests to avoid delays in audio delivery.

Error Handling

Sound wave illustration for: Error Handling

When your TTS requests fail, you are not charged. If synthesis fails, the charge is returned in full. This applies to all rate limits and server errors, ensuring you only pay for successfully generated audio files.

Common status codes

The API returns standard HTTP status codes. Use 400 for invalid parameters, 401 for authentication issues, 429 for rate limits, and 500 for server errors.

  • 400: Bad Request (invalid JSON or model)

Retry logic

Implement exponential backoff for 429 and 500 errors. Requests are processed sequentially; under load, a request may wait in a queue. Retry after the specified delay.

Refund policy

Failed requests are free. If synthesis fails, the charge is returned in full. This applies to all rate limits and server errors. No manual refund requests are needed.

Voices Endpoint

Sound wave illustration for: Voices Endpoint

The GET /v1/voices endpoint returns metadata for all available voices, including their IDs, gender, and supported languages. This data allows your application to dynamically populate voice selection menus without hardcoding presets.

Use this endpoint to verify language compatibility before sending synthesis requests, ensuring the selected voice can natively produce the target language.

The API supports 23 languages, including English, Spanish, German, French, Chinese, Japanese, and Arabic. Any voice can speak any supported language, but setting the language field explicitly prevents misidentification for non-English Latin text.

GET /v1/voices

Send a GET request to /v1/voices with your Bearer token to receive a JSON array of voice objects. Each object contains the voice ID, name, gender, and a list of supported language codes.

This list remains stable. The response includes metadata useful for building accessible dropdowns for museum audioguide apps.

  • Returns a JSON array of voice objects.
  • Includes voice ID, name, gender, and supported languages.
  • No pagination; returns all voices in one call.

List available voices

The endpoint lists eight presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. These cover various tones from warm narration to energetic promo styles.

Select the voice ID (e.g., aria) in your synthesis request. The voice determines the timbre and pacing, while the language parameter controls the phonetic output.

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

Language support

The API supports 23 languages. If the language field is omitted, the system guesses the language from the script, defaulting to English for Latin text.

For non-English texts using Latin script, always set the language parameter explicitly to avoid incorrect pronunciation.

Unsupported languages include Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, and Bengali. If a voice is selected, it can speak any of the supported languages without needing separate voice models.

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
  • Any voice can speak any supported language.
  • Explicit language field recommended for Latin-script non-English text.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. For archival tours or high-fidelity experiences, WAV and FLAC provide lossless audio.

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. Tether (USDT)
  4. Creative Commons Attribution 4.0
  5. LibriTTS-R corpus (OpenSLR 141)
  6. openai-node on GitHub
  7. LibriVox public-domain audiobooks
  8. IETF RFC 7845: Ogg Opus
  9. W3C WAI: making audio and video accessible
  10. ISO 639 language codes
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. OpenAI API reference: create speech

More on this site