API Documentation for Text-to-Speech Integration

By ArionVoice editorial team · Updated 2026-11-19

This guide provides a practical, step-by-step reference for teachers and methodologists integrating the ArionVoice text-to-speech API. It covers authentication, request structures, and parameter details, enabling you to generate clear audio for language learning materials efficiently. You will find concrete examples for cURL and the OpenAI SDK, ensuring immediate usability without unnecessary complexity.

Designed for educators and methodologists who need consistent voice-overs, this documentation focuses on reliable integration. You will learn how to manage keys, handle rate limits, and select appropriate audio formats. All information is derived directly from the API’s current behavior, helping you build robust classroom resources or podcast content with predictable performance.

API Documentation for Text-to-Speech Integration

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.ariongame.info/v1. You use this endpoint for all requests, including the main speech generation at /v1/audio/speech. This URL is also used for retrieving available voices and model information via GET requests.

How do I authenticate my requests?

Include your API key in the Authorization header as a Bearer token. The format is Authorization: Bearer tts-... . Each account has one active key, and issuing a new key immediately invalidates the old one.

Can I use the OpenAI Python SDK?

Yes. The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.ariongame.info/v1 and providing your ArionVoice API key for authentication.

What is the maximum text length per request?

Each request supports up to 4096 characters of input text. If your text exceeds this limit, you must split it into smaller parts. Each part is processed separately, and the resulting audio files are joined later.

How do I handle texts longer than 4096 characters?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request. Then, join the returned audio files to create the final output. This ensures all text is processed within limits.

What formats does the API support?

The API supports mp3, wav, opus, flac, and pcm response formats. Specify your preferred format in the response_format field of your request. The default format is typically mp3, but you can change it as needed.

How fast is the generation?

Generation speed is roughly real-time for long texts, processing about 25 characters per second. Short phrases may take a few seconds. Requests are processed sequentially, so under load, you might experience a queue delay.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Exceeding this may result in delayed processing or errors. Requests are processed one after another, so high volume causes queuing.

Is the API compatible with JavaScript?

Yes. You can use the API with JavaScript via plain HTTP requests or by using the OpenAI SDK with a custom base_url. The standard JSON request body works seamlessly with any language that supports HTTP POST requests.

Can I generate audio in the background?

The API processes requests sequentially. You can send requests asynchronously from your application, but the server handles them one by one. You receive the audio file directly in the response.

How do I specify the language?

Include the optional language field with an ISO code in your request body. This ensures correct pronunciation. If not set, the language is guessed from the script, defaulting to English for Latin text.

What is the default language if not specified?

If the language field is omitted, the system guesses the language from the text script. For Latin-script text, it defaults to English. For other scripts, it attempts to detect the language, but setting it explicitly is safer.

Are there any limits on concurrent requests?

Requests are processed one after another. While you can send multiple requests concurrently from your client, the server queues them. High concurrency may increase wait times due to the sequential processing model and rate limits.

How do I get a list of available voices?

Send a GET request to /v1/voices. This endpoint returns details about available voices, including their IDs, languages, and formats. You can also check /v1/models for model information.

First request

curl

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

Get Your API Key

Sound wave illustration for: Get Your API Key

ArionVoice provides a reliable text-to-speech API designed for teachers and methodologists. To begin generating audio for your language learning materials, you first need an API key. This key authenticates your requests and tracks your usage against your account balance.

Sign Up on the Site

Sign Up on the Site

Navigate to https://ariongame.info/get-api-key/ and create an account using Google or email. Accounts are specific to this site. Google sign-ups include a $0.50 trial credit valid for seven days, while email accounts start without credit.

Locate Your Key

Locate Your Key

Once logged in, the dashboard displays your active API key, current balance, and character limits. You will see a ready-to-use cURL example showing how to send text and receive an audio file via the API endpoint.

Key Management

You have one active key per account. If needed, you can issue a new key at any time. The previous key stops working immediately upon generation, ensuring secure access to your TTS services.

  • Only one active key per account
  • Issue new keys anytime via dashboard
  • Old keys become invalid immediately

First Request with cURL

Sound wave illustration for: First Request with cURL

Use cURL to send a POST request to the speech endpoint. The API accepts JSON input and returns audio files directly, making it simple to integrate with language learning scripts or classroom resources.

Basic POST Request

Send your text to the API using the following command. Replace YOUR_API_KEY with your actual key from the dashboard.

  • curl -X POST https://api.ariongame.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova"}'

Required Fields

The request must include the model, input, and voice fields. The input text can be up to 4096 characters. The voice must be one of the eight presets, such as aria or felix.

Response Format

On success, the response contains the audio file in the requested format. Failed requests are free, so you do not lose credit if synthesis fails. The audio is returned directly in the response body.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

The official OpenAI SDKs work seamlessly with ArionVoice by simply updating the base URL configuration. This allows you to use familiar libraries without rewriting your entire integration logic, ensuring a smooth transition for developers already accustomed to standard TTS workflows.

Changing Base URL

Initialize your client with base_url set to https://api.ariongame.info/v1. This directs all requests to our endpoint while maintaining the standard request shape used by the OpenAI Speech API.

Authentication Header

Pass your API key in the Authorization header as Bearer tts-.... Ensure this key is active and matches the account you created on the /get-api-key/ page.

Code Example

Here is a minimal Python example using the OpenAI SDK to generate speech for a language learning exercise.

  • from openai import OpenAI
  • client = OpenAI(base_url="https://api.ariongame.info/v1", api_key="tts-...")
  • response = client.audio.speech.create(
  • model="tts-1",
  • voice="aria",
  • input="The cat sat on the mat."
  • )

Supported Parameters

Sound wave illustration for: Supported Parameters

Configure the synthesis engine and audio output by selecting a model, voice, and playback speed. These parameters define the voice characteristics and processing speed for your language learning materials.

Model Selection

Choose between tts-1 and tts-1-hd. Both use the same underlying engine and pricing, so you can switch models without affecting cost or voice quality.

Voice Selection

Select one of eight presets to match your educational content. Female voices include aria, nova, luna, and sage; male voices include felix, milo, atlas, and orion. Each voice supports all 23 languages, allowing consistent narration across different language courses.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Speed Control

Adjust the speed parameter between 0.25 and 4.0. Slower speeds (0.5–1.0) are ideal for language learners needing clear articulation, while faster speeds suit review sessions. The default is 1.0.

Audio Formats

Sound wave illustration for: Audio Formats

ArionVoice supports five standard audio formats to suit different playback environments. You specify the desired format in the response_format field of your request. The API returns the raw audio data directly in the response body, allowing immediate playback or storage.

MP3

MP3 is the default format and offers a balance between file size and quality. It is widely compatible with all web browsers, mobile devices, and learning management systems. Use MP3 for general language learning podcasts or web-based audio exercises.

WAV

WAV provides uncompressed, high-fidelity audio. It is ideal for professional editing workflows or when you need to process the audio further in digital audio workstations. The file sizes are significantly larger than MP3, so consider storage costs for large projects.

OPUS, FLAC, PCM

OPUS offers compression for bandwidth-constrained environments. FLAC provides lossless compression, preserving audio quality while reducing file size compared to WAV. PCM returns raw, uncompressed audio data, suitable for specific hardware integrations that require linear PCM input.

Audio Formats

Rate Limits and Performance

Sound wave illustration for: Rate Limits and Performance

The API enforces a rate limit of 60 requests per minute per key, with a lower limit of 10 requests per minute for new accounts before the first top-up. This limit applies to each active API key independently, allowing you to scale usage by managing keys or adjusting request frequency.

60 Requests Per Minute

Each API key allows up to 60 requests per minute. New accounts start with a limit of 10 requests per minute until the first top-up is processed.

  • Limit: 60 requests/minute per key (10/minute for new accounts)
  • Applies to all /v1/audio/speech calls
  • Keys can be rotated to manage limits

Queue Handling

Requests are processed sequentially within the rate limit. If you exceed the limit, subsequent requests will be queued and processed as slots become available. Requests wait in line until processed.

  • Sequential processing within limits
  • Automatic queuing on limit exceedance
  • No priority queue available

Generation Speed

Synthesis speed is approximately real-time, generating about 25 characters of text per second of audio. Short phrases may take a few seconds to process due to overhead. Longer texts are split into 4096-character chunks and joined, which may introduce slight delays between segments.

  • Speed: ~25 chars/sec of audio
  • Short phrases: few seconds latency
  • Long texts: split and joined

Handling Errors

Sound wave illustration for: Handling Errors

Robust error handling ensures your language learning workflows remain uninterrupted. When a request fails, the API returns a standard HTTP error code along with a detailed message explaining the cause, allowing you to log and debug issues efficiently.

Common Error Codes

The API returns standard HTTP status codes. A 400 Bad Request indicates invalid parameters, such as exceeding the 4096-character input limit. A 401 Unauthorized error means your API key is invalid or missing. A 429 Too Many Requests signal indicates you have exceeded the 60 requests per minute rate limit.

  • 400: Invalid parameter or input length exceeded
  • 401: Invalid or missing API key
  • 429: Rate limit exceeded (60 req/min)

Retry Logic

Implement exponential backoff for transient errors like 429 or 500-level server errors. Wait briefly before retrying, as requests are processed sequentially and may queue under load. Avoid immediate rapid retries to prevent overwhelming the endpoint.

  • Use exponential backoff for 429 and 5xx errors
  • Check the 'Retry-After' header if provided
  • Limit maximum retry attempts to avoid infinite loops

Failed Request Refunds

If synthesis fails due to a server-side error, the charge is returned in full. You do not need to manually request a refund. Failed requests are free, so your balance remains unaffected by API errors.

Endpoint Reference

Sound wave illustration for: Endpoint Reference

The ArionVoice API provides three primary endpoints for integration. The speech endpoint handles audio generation, while the voices and models endpoints allow you to inspect available options programmatically.

All endpoints require a Bearer token in the Authorization header. Use the OpenAI SDK or plain HTTP clients to interact with these endpoints at https://api.ariongame.info/v1.

POST /v1/audio/speech

Send text and receive audio. Accepts model, input, voice, response_format, and speed. Text is limited to 4096 characters.

  • Model: tts-1 or tts-1-hd
  • Input: string up to 4096 chars
  • Voice: one of 8 presets
  • Response format: mp3, wav, opus, flac, pcm
  • Speed: 0.25–4.0
  • Language: optional ISO code

GET /v1/voices

Returns a list of available voices, their associated languages, supported formats, and pricing details. Use this to dynamically select voices for your language learning materials.

GET /v1/models

Returns the available models (tts-1 and tts-1-hd) with their respective details. Both models use the same engine and pricing structure.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This voice adds a layer of professionalism to advanced course materials.

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

More on this site