API Documentation for Narrator Text to Speech Integration

By Tourism TTS Review editorial team · Updated 2026-11-19

This documentation guides tourism startups and museum curators in integrating the Narrator Text-to-Speech API for scalable audio guide production. You will learn how to generate audio files from text using standard HTTP requests, enabling you to create multilingual content without hiring voice actors for every language.

The guide covers essential integration steps, from obtaining your API key and configuring the OpenAI SDK to handling rate limits and long-text chunking. It also covers pricing and payment. It provides concrete examples for common workflows, helping you build high-quality audioguides and video voiceovers with precise control over voices, formats, and speeds.

API Documentation for Narrator Text to Speech Integration

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or an email and password. Accounts are specific to this site. The dashboard displays your active API key, current balance, and usage statistics immediately after creation. You can issue a new key at any time, which invalidates the previous one instantly.

What is the base URL for the API?

The API base URL is https://api.a2229.info/v1. You can use this endpoint with standard HTTP clients or by configuring your SDK’s base_url parameter. All speech generation requests are sent to the /audio/speech sub-path using the POST method with a JSON body containing your parameters.

Can I use the OpenAI Python SDK?

Yes, the official OpenAI SDKs work perfectly. You only need to change the base_url to https://api.a2229.info/v1 and provide your site-specific API key. The request shape matches the OpenAI speech endpoint exactly, allowing you to integrate Narrator TTS into existing Python workflows with minimal code changes.

What happens if I send an invalid voice name?

The API will return an error response indicating the invalid voice. Since there are only eight preset voices (aria, nova, luna, sage, felix, milo, atlas, orion), sending an unrecognized name triggers a failure. Failed requests are free, so you will not be charged for the invalid attempt.

How do I specify the language explicitly?

Include the optional 'language' field in your request body with the ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly setting the language ensures accurate synthesis, as any voice can speak any supported language.

What is the maximum input length?

Each request supports up to 4096 characters of input text. For longer texts, you must split the content into chunks of this size and join the resulting audio files. Spaces and punctuation count toward the character limit, so plan your splits accordingly to maintain seamless audio playback for your audience.

Can I stream the audio directly?

No, streaming is not supported. The API returns the complete audio file in the response after synthesis is finished. You cannot receive partial audio chunks or use WebSocket for real-time streaming. This synchronous approach is suitable for audioguides and pre-rendered video voiceovers where latency is less critical.

Is SSML supported in the input text?

SSML is not supported in the input text. You cannot use phoneme dictionaries, custom pronunciation lexicons, or emotion tags. The input is treated as plain text. If you need specific pronunciation, you may need to adjust the spelling in your input text before sending it to the API endpoint.

How do I handle rate limits in production?

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 and implement retry logic with exponential backoff to handle temporary delays or quota exhaustion during high-volume generation tasks.

What format does the response return?

The response returns the audio file in the format you specified: mp3, wav, opus, flac, or pcm. The audio data is included directly in the response body. Each generated file carries an inaudible watermark marking it as synthetic speech, which helps identify the content as AI-generated without affecting playback quality.

Can I use the same key for multiple projects?

Yes, one active key per account can be used across multiple projects. The rate limit applies per key, so sharing it across projects increases the total request volume. You can issue a new key at any time, which immediately invalidates the old one, allowing you to rotate keys for different environments.

Do I need to include the model parameter?

Yes, you must specify the model as either 'tts-1' or 'tts-1-hd'. Both use the same engine and price. Including this parameter is required for the API to process your request correctly. The choice between them does not affect the cost, which is $10 per 1 million characters.

How do I detect which voice was used?

The API does not return metadata indicating which voice was used in the response headers or body. You must track this information in your own application logic based on the voice name you sent in the request. The audio file itself contains an inaudible watermark but does not encode the voice identity.

What are the error codes for failures?

The documentation does not list specific HTTP error codes or error message strings. Failed requests result in an error response and are free, with the charge returned in full. You should handle standard HTTP error responses (like 4xx or 5xx) and implement retry logic based on the status code received.

First request

curl

curl https://api.a2229.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.a2229.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.a2229.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

Getting Your API Key

Sound wave illustration for: Getting Your API Key

Create an account at https://a2229.info/get-api-key/ using Google or email. This grants immediate access to your unique API key. Google sign-in provides a $0.50 free trial credit valid for 7 days; email/password accounts start without trial credit.

Sign Up and Generate Key

Sign Up and Generate Key

Authentication relies on a single active Bearer token. Upon registration, you receive one key immediately. Unlike multi-seat models, this key represents your entire account’s access.

  • Google Sign-In provides instant trial credit ($0.50).
  • Email/password accounts start with zero balance.
  • Keys are generated instantly upon verification.

Locating Key in Dashboard

Locating Key in Dashboard

Visit the /get-api-key/ dashboard to view your current key, remaining balance, and usage statistics. The interface displays your active token alongside a ready-to-use cURL example for immediate testing.

  • Balance tracking in characters.
  • Instant copy-to-clipboard for the Bearer token.
  • Visible usage history for budgeting.

Revoking and Regenerating Keys

You can issue a new key at any time via the dashboard. The previous key stops working immediately upon regeneration, ensuring tight security control without waiting for expiration cycles.

  • Instant invalidation of old keys.
  • No downtime during regeneration.
  • One active key per account.

First Request with cURL

Sound wave illustration for: First Request with cURL

To generate an audio guide, send a POST request to the speech endpoint with your text and voice selection. The API returns the audio file directly, allowing immediate integration into your tourism or museum application without waiting for external processing.

Basic POST Request Example

Use the following cURL command to synthesize a short audio clip. Replace YOUR_API_KEY with your key from the dashboard and adjust the input and voice fields as needed for your specific content.

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

Setting Headers and Body

The request requires an Authorization header with your Bearer token and a JSON body containing the synthesis parameters. Ensure the input text does not exceed 4096 characters, as longer texts must be split client-side before submission to avoid errors.

Parsing the JSON Response

The API returns the audio data directly in the response body. Check the HTTP status code to confirm success; a 200 OK indicates the audio file is ready for playback or storage.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

Leverage the official OpenAI SDKs to integrate Narrator TTS with minimal configuration changes. By updating the base URL, you can reuse familiar client libraries for seamless audio generation in your tourism or museum applications.

This approach allows you to switch from the standard OpenAI endpoint to our infrastructure by simply pointing to the correct API domain, ensuring consistent request shapes and response handling across your codebase.

Configuring Base URL

Update the SDK client's base_url property to https://api.a2229.info/v1. This directs all speech requests to our Narrator TTS endpoint while maintaining the standard OpenAI request structure.

Installing the Official SDK

Install the official OpenAI SDK using your preferred package manager. For Python, use pip install openai. For Node.js, run npm install openai. These libraries handle authentication and JSON serialization automatically.

  • Python: pip install openai
  • Node.js: npm install openai

Code Snippet for Python/Node

Initialize the client with your API key and set the base URL. Pass your text and voice preset to the audio.speech.create method. The SDK returns the audio file directly for playback or storage.

  • Set Authorization: Bearer header automatically
  • Supports tts-1 and tts-1-hd models
  • Returns audio data in specified format

Request Parameters Explained

Sound wave illustration for: Request Parameters Explained

The API accepts two model identifiers, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing structure. You may select either without affecting the cost per character or the generation quality, allowing flexibility in your request headers based on your system's naming conventions.

Model Selection: tts-1 vs tts-1-hd

Both identifiers trigger the identical synthesis engine. There is no performance or audio quality difference between them, so you can standardize on one or switch freely without changing your billing expectations.

Voice Preset Options

Choose from eight distinct voices. Female options include Aria for clear narration, Nova for upbeat content, Luna for storytelling, and Sage for instructional guides. Male voices include Felix for energetic promos, Milo for conversational tones, Atlas for neutral news-style updates, and Orion for deep documentary styles.

  • Aria (warm narrator)
  • Nova (bright, upbeat)
  • Luna (soft storytelling)
  • Sage (calm instructions)
  • Felix (energetic promo)
  • Milo (conversational)
  • Atlas (neutral news)
  • Orion (deep documentary)

Speed and Language Parameters

Adjust playback speed between 0.25x and 4.0x to match your audio guide pacing. While the system guesses language from Latin script, explicitly set the language field for non-English texts to ensure accurate pronunciation. All voices support 23 languages, including Arabic, Chinese, French, German, Japanese, and Spanish.

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

The Narrator TTS API supports five standard audio formats, allowing you to choose the optimal balance between file size and fidelity for your tourism applications. Selecting the right format ensures your audioguides and video voiceovers load efficiently across various devices.

MP3 for Web and Mobile

MP3 is the default format for most use cases, offering compressed audio that loads quickly on mobile apps and web players. It is ideal for delivering clear, narrated content to tourists without consuming excessive bandwidth or storage space.

WAV for High-Quality Archives

Choose WAV for uncompressed, high-fidelity audio suitable for museum archives or high-end installations where audio quality is paramount. This format preserves the full nuance of the voice presets, such as the warm tones of Aria or the deep documentary style of Orion.

Opus, FLAC, and PCM Options

Opus provides efficient compression, while FLAC offers lossless compression for archival purposes. PCM is available for raw, uncompressed data processing. All formats support the same 8 voice presets and language settings.

Supported Audio Formats

Handling Errors and Limits

Sound wave illustration for: Handling Errors and Limits

Rate limits protect the API from overload. You get 60 requests per minute after your first top-up, or 10 per minute initially. Exceeding this triggers a 429 error, so implement exponential backoff in your tourism audio guide generation pipeline to avoid delays.

Rate Limit Exceeded (429)

Requests are processed sequentially under load. If you exceed 60 requests per minute, the API returns HTTP 429. Your museum audio guide batch jobs should queue requests and retry with a delay to ensure smooth playback generation without data loss.

  • Limit: 60 requests/minute (10/min initially)
  • Status code: 429 Too Many Requests
  • Recommendation: Implement exponential backoff

Invalid API Key (401)

A 401 error indicates your bearer token is missing, expired, or incorrect. Ensure your Authorization header uses the format Bearer tts-.... Keys are single-active; revoking one immediately invalidates the old key, so update your integration promptly.

  • Status code: 401 Unauthorized
  • Check header format: Bearer tts-...
  • Revoking a key invalidates the old one instantly

Input Too Long (400)

The API rejects text exceeding 4096 characters with a 400 error. For longer audioguide scripts, split your text into chunks. Process each chunk separately and join the resulting audio files client-side to maintain continuity in your final tour audio product.

  • Max input length: 4096 characters
  • Status code: 400 Bad Request
  • Strategy: Split text, generate, then join

Long Text Handling Strategy

Sound wave illustration for: Long Text Handling Strategy

Long texts exceeding 4096 characters must be split into smaller chunks before sending to the API. Each chunk generates a separate audio file, which you then join client-side to create a seamless audio guide or video voiceover.

This approach ensures reliable processing and allows you to manage buffer limits effectively during playback.

Splitting Text into 4096 Character Chunks

Divide your input text into segments of up to 4096 characters. Each segment is sent as a separate POST request to the /v1/audio/speech endpoint. This ensures that no single request exceeds the character limit, maintaining consistent generation quality.

Split the text into segments of up to 4096 characters. Keep spaces and punctuation in the count, as they contribute to the character total.

  • Maximum 4096 characters per request
  • Include spaces and punctuation in count
  • Split at natural boundaries when possible

Joining Audio Files Client-Side

After receiving individual audio files for each chunk, join them in your application. Most programming languages have libraries for concatenating audio files, such as ffmpeg or native SDK methods.

Ensure that the audio formats match across all chunks to avoid compatibility issues during concatenation. The API returns the audio data in the specified response_format, so maintain consistency in your requests.

  • Use libraries like ffmpeg for joining
  • Ensure consistent audio formats
  • Concatenate in the correct order

Managing Audio Buffer Limits

Be mindful of buffer limits when handling multiple audio files. Large texts can result in numerous small files, which may overwhelm your application’s memory if not managed properly.

Buffer audio files as needed to ensure smooth playback without excessive memory usage. This is particularly important for real-time audio guides or interactive applications.

  • Monitor memory usage
  • Stream audio files as needed
  • Optimize for real-time playback

Authentication and Security

Sound wave illustration for: Authentication and Security

Authentication relies on a single Bearer token sent in the Authorization header. This key grants access to your account’s balance and usage limits for all API requests.

Bearer Token Usage

Include the header Authorization: Bearer tts-... in every request. The token authenticates your identity and deducts credits from your balance upon successful synthesis.

Single Active Key Policy

Only one key is active per account. Generating a new key immediately invalidates the previous one, ensuring secure key rotation without downtime.

Secure Key Storage Best Practices

Store keys in environment variables or secure secret managers. Avoid hardcoding them in client-side code or public repositories to prevent unauthorized usage of your tourism audio credits.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This clarity helps developers quickly prototype audio guides for museums or tourist apps without guessing parameter formats or encoding requirements.

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. Python documentation
  3. Tether (USDT)
  4. W3C WAI: making audio and video accessible
  5. ISO 639 language codes
  6. FFmpeg documentation
  7. openai-node on GitHub
  8. Creative Commons Attribution 4.0
  9. curl documentation
  10. IETF RFC 7845: Ogg Opus
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. openai-python on GitHub

More on this site