Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email plus password. Accounts are per site. Once registered, your dashboard displays your active API key, current balance, and usage statistics immediately.
What is the base URL for the API?
The API base URL is https://api.ace44.info/v1. You send POST requests to https://api.ace44.info/v1/audio/speech. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.ace44.info/v1 and providing your site-specific key.
What formats are available for output?
You can choose between mp3, wav, opus, flac, and pcm formats. Select the format that best fits your playback environment or processing pipeline when making your synthesis request.
How do I handle texts longer than 4096 characters?
Split your text into parts of up to 4096 characters each. Generate audio for each part individually, then join the resulting audio files together to create the final continuous audio file.
What is the rate limit per minute?
You are limited to 60 requests per minute per key. If you have not topped up your account, the limit is 10 requests per minute. Requests are processed sequentially, so load may cause queuing.
Does the price differ between models?
No. Both tts-1 and tts-1-hd use the same engine and price. You pay $10 per 1 million characters regardless of which model you select for your audio generation requests.
How do I authenticate my requests?
Include an Authorization header with your Bearer token: Authorization: Bearer tts-... . Each account has one active key, which you can find on your dashboard after signing up.
What happens if a request 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.
Can I change my API key?
Yes. You can issue a new API key at any time from your account settings. When you issue a new key, the old one stops working immediately.
Is there an SDK for mobile devices?
No. There is no official mobile SDK. However, our API follows the standard OpenAI request shape, so you can use the official OpenAI SDK or plain HTTP requests on any platform. Simply update the base URL to https://api.ace44.info/v1 and use your API key for seamless integration on iOS or Android.
Do I need to install any software?
No. The API is cloud-based. You simply send HTTP POST requests with your text and receive an audio file. No local software installation is required to use the service.
How do I specify the language?
Include the optional language field with an ISO code in your request. If omitted, the language is guessed from the script, defaulting to English for Latin text. Set it explicitly for non-English Latin scripts.
What is the character limit per request?
Each request accepts up to 4096 characters of input text. For longer texts, you must split the content into chunks of this size and generate audio for each chunk separately.
First request
curl
curl https://api.ace44.info/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.ace44.info/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.ace44.info/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 |
Get your API key
Create your EchoGuide account on the /get-api-key/ dashboard using Google or email. Once signed in, you will see your unique API key and starting balance on the main page.
Copy this secret key immediately. It authenticates your requests to the TTS API and grants access to your credit.
Sign up on the dashboard
Visit the sign-up page to create an account. You can use Google for quick access, which includes a $0.50 free trial valid for 7 days. Email-based accounts start with zero balance.
- Google or email registration
- Instant access to dashboard
- $0.50 trial for Google sign-ins
Copy your secret key
Locate the API key displayed on your dashboard after logging in. This key identifies your account and tracks your usage for billing purposes.
Keep it secure and private
Treat your API key like a password. Anyone with the key can use your credit. You can issue a new key at any time, which immediately invalidates the old one.
- One active key per account
- Issue new key to invalidate old
- No shared keys recommended
First request with curl
Once you have your API key from the dashboard, you can immediately test the service with a simple command. This approach lets you verify that your German guide script sounds natural before building it into your museum application.
We use standard HTTP requests so you do not need any special libraries. You can run this test directly from your terminal or command prompt to hear the synthetic voice output.
Use POST to /v1/audio/speech
Send a POST request to the speech endpoint. Replace YOUR_API_KEY with your actual secret key from the dashboard.
- Endpoint:
POST https://api.ace44.info/v1/audio/speech - Header:
Authorization: Bearer YOUR_API_KEY - Header:
Content-Type: application/json
Send JSON with text and voice
Include your guide text in the JSON body. Use the aria voice for a clear, warm narration style. Set the language to de for German.
- Model:
tts-1 - Voice:
aria - Language:
de - Input: Your German script (max 4096 chars)
Receive audio file in response
The API returns the audio file directly in the response body. Save this output as an MP3 file to play it on your audio guide devices or embed it in your website.
- Format: MP3 (default)
- Response: Binary audio data
- No storage: Generated audio is returned in the response and not stored.
Using the OpenAI SDK
We provide a straightforward way to integrate our text-to-speech engine into your existing workflows using the official OpenAI Python SDK. This approach requires minimal code changes, allowing tourism and museum staff to generate natural-sounding German audio guides without building custom HTTP clients from scratch.
Install the official OpenAI package
Install the OpenAI package via pip. This ensures you have the necessary tools to communicate with our API using standard methods.
Set base_url to our API
Configure the client by setting the base_url parameter to https://api.ace44.info/v1. This directs requests to our endpoint while maintaining compatibility with the standard request shape.
Use standard speech method
Call the standard speech method with your API key and text input. The SDK handles the JSON body and returns the audio file directly, simplifying integration for no-code or low-code users.
Request parameters
Configure your TTS requests using three core parameters: model, voice, and response format. These fields determine audio quality, character, and file type. The API accepts standard JSON bodies, making integration straightforward for tourism and museum audio guides.
Each parameter has specific constraints. You can choose between two engine models, select from eight distinct voice presets, and output audio in various formats. All requests must include a valid model name and voice identifier.
Set model to tts-1 or tts-1-hd
Both tts-1 and tts-1-hd use the same engine and pricing. Choose tts-1 for standard efficiency or tts-1-hd for higher fidelity. The API processes requests sequentially, so longer guide scripts may queue during high load.
Choose from 8 voice presets
Select a voice that matches your guide’s tone. Options include warm narrators like Aria or calm instructors like Sage. All voices support German and 22 other languages (23 total). If language is omitted, Latin script defaults to English.
Voices are based on licensed recordings from LibriVox. Each file includes an inaudible synthetic watermark. You can specify an optional ISO language code to ensure accurate pronunciation for non-English scripts.
- 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
Specify response format
Choose mp3, wav, opus, flac, or pcm for the response_format. MP3 is ideal for general web playback, while WAV offers high quality. Other formats suit specific archival or processing needs.
The API returns the audio file directly in the response. Failed requests do not consume credit, ensuring you only pay for successfully generated audio files.
Supported audio formats
Select the format that best fits your audioguide distribution workflow. Each option balances file size, quality, and compatibility differently, ensuring your audio plays smoothly on any device.
MP3 for general use
MP3 is the standard choice for most tourism applications. It offers a good balance between audio quality and small file size, making it ideal for web playback and mobile apps.
WAV for high quality
Choose WAV when you need uncompressed, studio-quality audio. This format preserves every detail of the synthesis, making it perfect for offline kiosks or high-end museum installations where file size is less critical than fidelity.
OPUS, FLAC, PCM options
OPUS provides efficient compression. FLAC offers lossless compression for archival purposes, keeping file sizes smaller than WAV without quality loss. PCM delivers raw, uncompressed data for immediate processing in custom audio pipelines.
- OPUS: Efficient streaming
- FLAC: Lossless compression
- PCM: Raw data

Handling long texts
When your guide script exceeds 4,096 characters, you must divide it into smaller chunks before sending them to the API. Each request can only process a single segment of this size, ensuring consistent synthesis quality without truncation.
Split text into 4096 char parts
Break your narrative into logical segments, such as individual exhibit descriptions or tour stops. Ensure each chunk stays within the 4,096-character limit, including spaces and punctuation. This prevents errors and keeps audio generation efficient.
- Count characters carefully, including spaces.
- Split at natural pauses or sentence ends.
- Avoid cutting mid-word if possible.
Generate each part separately
Send each text segment as a distinct POST request to the speech endpoint. The API processes these sequentially, so allow time for each to complete before starting the next, especially if you are under load.
- Use the same voice and model for all parts.
- Set the same speed parameter to maintain consistency.
Join audio files together
Once you receive all audio responses, concatenate them in the original order. Since the API returns discrete files, you will need a simple script or tool to merge them into a single continuous audio file for playback.
- Maintain the original sequence of segments.
- Use a library like ffmpeg or pydub for merging.
- Verify silence gaps between joined parts.
Rate limits explained
Your API key allows 60 requests per minute under normal conditions. This limit resets every minute and applies to the key, not the account. If you exceed this, requests will be rejected until the window clears.
60 requests per minute
Each successful or failed synthesis counts toward this limit. Plan your batch jobs accordingly to avoid interruptions during peak usage times.
10 requests before top-up
New accounts without a top-up are limited to 10 requests per minute. Once you add funds via USDT (TRC-20), this limit increases to the standard 60 requests per minute. Top-ups are credited automatically within minutes.
Queue during high load
Requests are processed sequentially. Under heavy load, a request may wait in a queue before generation begins. This can increase latency, but ensures fair access for all users.
Common errors and fixes
When integrating the EchoGuide API, you may encounter common HTTP errors. Understanding these responses helps you resolve issues quickly without interrupting your workflow.
This guide covers authentication failures, rate limiting, and validation errors, ensuring your audio generation pipeline runs smoothly.
401 for invalid key
A 401 Unauthorized error occurs when the API key is missing, incorrect, or expired. Ensure you are passing the correct key in the Authorization header.
If you regenerated your key, remember that the old one stops immediately. Update your configuration to use the new secret key.
- Check for typos in your key string.
- Verify the key is active in your dashboard.
- Ensure the Authorization header format is correct.
429 for rate limit exceeded
You receive a 429 error when exceeding 60 requests per minute per key. New accounts start with a 10 requests per minute limit until the first top-up.
Requests are processed sequentially, so high load may also cause delays. Wait a moment and retry the request.
- Monitor your usage in the dashboard.
- Implement exponential backoff in your code.
- Top up your balance to increase limits.
400 for missing fields
A 400 Bad Request indicates that required fields like model, input, or voice are missing or invalid. Check your JSON payload structure.
Ensure the input text does not exceed 4096 characters and the voice name is one of the eight available presets.
- Validate JSON syntax before sending.
- Confirm input text length limits.
- Use a valid voice preset name.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Support your international visitors with clear, natural audio in their native tongue.
23 languages
Any voice speaks any of these languages.
