Quickstart Guide for TTS API Integration and Setup

By AudioGuides API editorial team · Updated 2026-11-19

This guide helps product teams integrate the AudioGuides API for museum exhibits and tourism content. You will learn to send text and receive audio files using standard HTTP requests or the OpenAI SDK. The documentation covers authentication, parameter configuration, and response handling for building reliable multilingual narration systems.

Use this reference to implement text-to-speech in your application efficiently. We detail the available voices, supported output formats, and rate limits specific to audioguide workloads. Follow the steps below to generate your first audio file and configure your API key for production use.

Quickstart Guide for TTS API Integration and Setup

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

Python (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
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

Authentication

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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 atlas for clear, neutral narration.
  • Set language explicitly 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

Sound wave illustration for: 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.

Output Formats

Error Handling

Sound wave illustration for: 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 input does not exceed 4096 characters.
  • Verify voice matches a valid preset from the API.
  • Check that speed is 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. Node.js documentation
  3. TRON developer hub: TRC-20
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. MDN: Web Speech API
  6. W3C WAI: making audio and video accessible
  7. curl documentation
  8. openai-python on GitHub
  9. ISO 639 language codes
  10. LibriTTS-R corpus (OpenSLR 141)
  11. Python documentation
  12. Creative Commons Attribution 4.0

More on this site