Frequently asked questions
How do I generate an API key?
Navigate to /get-api-key/ and sign in using Google or an email/password combination. The dashboard displays your active API key, current balance, and usage statistics. You can issue a new key at any time; the previous key becomes invalid immediately upon creation.
What is the endpoint URL?
Send POST requests to https://api.3178.info/v1/audio/speech. Include a JSON body with fields like model, input, voice, and response_format. Authentication requires an Authorization header with your Bearer token. Other endpoints include GET /v1/voices and GET /v1/models.
Can I use the OpenAI Python SDK?
Yes. The API accepts the same request shape as OpenAI. Configure your SDK’s base_url to https://api.3178.info/v1 and provide your API key. This allows you to use the official OpenAI Python SDK without modifying the core request structure.
How do I set the language parameter?
Pass the optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting Latin text to English. For non-English Latin text, explicitly set the language parameter to ensure correct pronunciation and synthesis.
What is the maximum input length?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer audioguide scripts, split the text into parts under this limit, generate audio for each, and join the resulting audio files.
How do I handle rate limits?
The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load, they may queue. Monitor your usage via the dashboard to avoid exceeding these limits during high-volume audioguide generation.
What happens if the server is down?
If synthesis fails, the charge is returned in full. Failed requests incur no cost. The system does not provide an SLA or uptime guarantee.
Is the API synchronous or asynchronous?
The API is synchronous. You send a POST request and receive the audio file in the response. It does not support streaming, WebSockets, or real-time partial audio. You must wait for the complete audio file before proceeding.
Can I change the speed of narration?
Yes. Use the speed parameter in the request body, accepting values between 0.25 and 4.0. This allows you to adjust narration pace for different audioguide contexts, from slow museum explanations to faster transit announcements, without altering the voice model.
How do I list available voices?
Send a GET request to /v1/voices. This endpoint returns details on all 8 voice presets, supported languages, formats, and pricing. You can then select the appropriate voice (e.g., aria, nova, atlas) for your specific audioguide content requirements.
What is the tts-1-hd model?
tts-1-hd is one of the two available models, alongside tts-1. Both use the same engine and have identical pricing. The choice between them does not affect cost or voice selection, but both support the full range of response formats.
Do I need to split long texts?
Yes, if your text exceeds 4096 characters. Split the text into segments, generate audio for each segment via separate requests, and join the resulting audio files. This ensures compliance with the input length limit while maintaining continuous narration.
How do I detect errors in response?
Check the HTTP status code and response body for error details. If synthesis fails, you receive a full refund. Use standard HTTP client error handling to catch failures and retry or notify users.
Is there a demo endpoint?
There is no separate demo endpoint. Use the standard /v1/audio/speech endpoint with your API key. Sign up at /get-api-key/ to receive $0.50 in trial credit (valid for 7 days) to test the API with real requests.
First request
curl
curl https://api.3178.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.3178.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.3178.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 |
Authentication
Access the AudioGuides API using a single active API key issued to your account. Each key is prefixed with tts- and provides full access to all endpoints, including speech synthesis and voice listing.
API Key Format
Keys are generated on the /get-api-key/ dashboard. They follow the standard tts-<unique_id> pattern. Store this value securely in your environment variables.
Bearer Token
Include the key in the HTTP Authorization header as a Bearer token. The format is Authorization: Bearer tts-.... This header is required for all POST and GET requests to the API base URL.
Key Rotation
You can issue a new key at any time via the dashboard. When a new key is generated, the previous one stops working immediately. This allows instant revocation if a key is compromised without affecting other services.
First Request
Generate audio for your audioguide or museum exhibit with a single POST request. The API accepts text input and returns an audio file directly in the response body, enabling immediate playback or storage in your content management system.
This quickstart demonstrates the minimal required fields to synthesize speech. You will send your text payload, receive the audio data, and verify the response code to ensure successful generation before integrating the file into your tourist application.
cURL Example
Execute a synthesis request using the following cURL command. Replace YOUR_API_KEY with your key from /get-api-key/ and provide the text you want converted to speech.
```bash curl -X POST "https://api.3178.info/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Welcome to the exhibition.", "voice": "aria"}' \ --output audio.mp3 ```
JSON Body
The request body uses standard JSON format. Include the model ("tts-1" or "tts-1-hd"), the input text (up to 4096 characters), and a voice preset. You may also specify response_format and speed as needed.
Example payload:
- {"model": "tts-1", "input": "Enter your audioguide text here.", "voice": "nova", "response_format": "mp3", "speed": 1.0}
Response Handling
A successful request returns an HTTP 200 status code with the audio file in the response body. The format matches the response_format parameter, typically MP3 or WAV. Save this binary data directly to your server.
If the request fails, the response contains an error object with details. Check the HTTP status code to determine if the issue is related to authentication, input validation, or server load.
OpenAI SDK
To integrate our TTS engine using the official OpenAI SDK, modify the base_url to https://api.3178.info/v1. This allows you to use the standard SDK methods while routing requests to our infrastructure. Ensure your Authorization header includes your tts-... API key.
Base URL Change
Update your SDK configuration to point to our base URL. This single change enables the use of our speech endpoint with your existing OpenAI SDK client setup.
Voice Parameter
Pass one of the eight voice presets (e.g., aria, nova, felix) in the voice field. Each voice is optimized for clear narration, ensuring consistent quality across museum exhibits and tourism content.
Model Selection
Select either tts-1 or tts-1-hd. Both models use the same engine and pricing, offering identical audio quality with no functional difference in output format or speed.
Parameters
Configure the input, voice, and speed fields to generate audioguide narration. Input text must not exceed 4096 characters per request. For longer scripts, split the text and join the resulting audio files.
Input Text
Pass the narration text in the input field. The API counts spaces and punctuation toward the 4096-character limit. Text is processed sequentially, so long documents may queue under load.
Voice Selection
Select a voice preset such as atlas for neutral news or sage for instructional content. Each voice supports all 23 languages. If the language field is omitted, the system guesses the language, defaulting to English for Latin script.
- Use
atlasfor clear, neutral narration. - Set
languageexplicitly for non-English Latin text. - Voices are consistent across all supported languages.
Speed Control
Adjust the speed parameter between 0.25 and 4.0 to fit the audio guide's pacing. Standard speed is 1.0. Faster speeds reduce generation time but may affect clarity for complex terms.
Output Formats
The API returns audio files in formats that balance compatibility and quality. MP3 is the default, offering broad support for standard audioguide players. WAV provides uncompressed lossless audio for high-fidelity museum installations where file size is less critical than immediate playback quality.
MP3 Support
MP3 is the standard output format, suitable for most web and mobile audioguide applications. It provides a good balance between file size and audio quality, ensuring efficient delivery over typical tourist network connections.
WAV Support
WAV delivers uncompressed PCM audio, ideal for local kiosks or offline devices requiring consistent playback. Use this format when maximum fidelity is required and storage or bandwidth constraints are minimal.
Opus and FLAC
Opus offers high-quality compression at lower bitrates, reducing data usage for large-scale deployments. FLAC provides lossless compression, preserving audio quality while reducing file size compared to WAV, making it suitable for archival storage.

Error Handling
API errors indicate specific issues during synthesis. The 400 status returns for invalid inputs, such as exceeding the 4096-character limit or using an unsupported voice ID. Always validate the request body before sending to avoid wasted credits.
400 Bad Request
This error occurs when the JSON payload is malformed or contains invalid values. Common causes include missing the input field, providing an empty string, or selecting a voice not present in the /v1/voices list. The response body includes a message describing the validation failure.
- Ensure
inputdoes not exceed 4096 characters. - Verify
voicematches a valid preset from the API. - Check that
speedis between 0.25 and 4.0.
429 Rate Limit
A 429 response indicates you have exceeded the allowed request rate. New accounts start with a limit of 10 requests per minute. After the first top-up, this increases to 60 requests per minute. Exceeding this limit pauses synthesis until the window resets.
- Implement exponential backoff in your integration logic.
- Monitor usage via the dashboard to stay within limits.
- Top up to increase your base rate limit.
500 Server Error
A 500 status indicates a transient issue on our side, such as a temporary spike in processing load. If synthesis fails completely, the charge is returned in full to your account balance.
- Retry the request after a short delay.
- No charge is applied if synthesis fails.
Rate Limits
Rate limits protect API stability during high-volume audioguide generation. You can make 60 requests per minute with a valid key. This allows processing of multiple tour segments.
Requests are processed sequentially under load, so complex audio synthesis may queue briefly. Monitoring response headers helps manage throughput for large museum collections.
60 Requests Per Minute
Each API key supports up to 60 requests per minute. This limit applies per key, allowing multiple keys to scale throughput if needed.
- Limit is 60 req/min per active key
- Requests queue if backend is busy
- No burst allowance beyond the limit
Initial Limit
New accounts start with 10 requests per minute. This lower limit prevents abuse during initial testing before the first top-up.
Once you add funds, the limit increases to 60 req/min immediately.
Limit Increase
The limit increases to 60 req/min after the first successful top-up. No manual verification is required.
Top-ups via USDT (TRC-20) are processed automatically, updating your limit within minutes.
Voice List
The API provides eight distinct voice presets designed for clear audioguide narration. Voices are categorized by gender and tonal quality to suit different museum or tourism contexts.
Female Voices
Four female options offer varied narrative styles:
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
Male Voices
Four male options provide complementary tones:
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Voice Descriptions
All voices support 23 languages and handle any language input. If the language field is omitted, the system guesses from the script, defaulting to English for Latin text. Each voice is based on licensed recordings from LibriTTS-R (CC BY 4.0).
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Selecting the right voice is critical for museum audioguides, where clarity and tone must match the exhibit's context.
23 languages
Any voice speaks any of these languages.
