Text-to-Speech API: Developer Integration Guide

By 1930 Cup editorial team · Updated 2026-11-19

This guide explains how to integrate the VoxTrain text-to-speech API into your multilingual e-learning workflow. You will learn to generate professional audio files for HR agencies and training departments using standard HTTP requests. The documentation covers authentication, endpoint structures, voice selection, and format options with concrete examples.

Readers will find step-by-step instructions for both cURL and OpenAI SDK integration. We detail rate limits, language handling, and character counting to help you estimate costs accurately. All information is specific to the 1930cup.info infrastructure, ensuring your development team can deploy reliable synthetic speech for corporate training materials without guesswork.

Text-to-Speech API: Developer Integration Guide

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email. Accounts are per site. The dashboard displays your active key, balance, and usage. You can issue a new key at any time; the old one stops immediately. This provides immediate access to the API for your integration needs.

What is the base URL?

The API base URL is https://api.1930cup.info/v1. Use this endpoint for all requests. The standard endpoint is POST https://api.1930cup.info/v1/audio/speech. This URL structure ensures compatibility with standard HTTP clients and SDKs configured for this specific domain.

Can I use the OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. Configure your SDK’s base_url to https://api.1930cup.info/v1 and use your site’s key. This allows you to use official OpenAI SDKs directly without writing custom HTTP logic for your integration.

What models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and price. Select the model in your request body. The choice affects audio quality but not the cost or character limits per request.

What is the character limit?

Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer texts, split the input into parts of 4096 characters and join the resulting audio files. This ensures consistent processing and avoids payload size issues.

How do I set the language?

Pass the optional ISO language code in the request. If omitted, the system guesses the language from the script; Latin text defaults to English. For non-English Latin text, explicitly set the language to ensure correct synthesis. Supported languages include English, German, and French.

What formats are supported?

Supported response formats are mp3, wav, opus, flac, and pcm. Specify the desired format in the response_format field. This allows you to choose the best balance between file size and quality for your e-learning content delivery pipeline.

What are the rate limits?

The limit is 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. Requests are processed sequentially, so under load, a request may wait in a queue. Monitor your usage to avoid delays.

What happens on rate limit?

Requests are processed one after another. If you exceed the limit, your request waits in a queue. There is no explicit error for queuing; just wait for processing. Failed requests are free, but queued requests still count toward your usage when processed.

Is SSML supported?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You must use plain text input. For precise control, adjust the speed parameter or choose a voice preset that matches your desired tone and pace.

Can I stream the audio?

No. There is no streaming, WebSocket, or real-time partial audio support. The API returns the complete audio file in the response. For long texts, split them into chunks and join the resulting files after generation.

How do I handle errors?

Failed requests are free, and the charge is returned in full. Check the response status code for errors. Ensure your input text is under 4096 characters and your key is valid. Use the /v1/models endpoint to verify available models.

First request

curl

curl https://api.1930cup.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.1930cup.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.1930cup.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 and Keys

Sound wave illustration for: Authentication and Keys

Access the API by generating a unique key from your account dashboard at /get-api-key/. Each account maintains one active key, which is displayed alongside your current balance and usage statistics. This key serves as the sole credential for authenticating your API requests.

Generate API Key

Generate API Key

Navigate to the /get-api-key/ page to create your initial key. The system generates a token starting with "tts-" which you must copy immediately. This key is tied to your specific account and provides access to all endpoints.

Bearer Token Usage

Bearer Token Usage

Include your key in the HTTP header of every request using the format Authorization: Bearer tts-your-key-here. The API validates this token before processing synthesis. Ensure the key is sent in every call to avoid authentication errors.

Key Rotation Process

You can issue a new key at any time via the dashboard. When a new key is generated, the previous one becomes invalid immediately. This allows seamless rotation without downtime, ensuring that old keys stop working the moment the new one is active.

Endpoint: Create Audio

Sound wave illustration for: Endpoint: Create Audio

The core of the API is the speech generation endpoint. Send a POST request to https://api.1930cup.info/v1/audio/speech with your text and configuration. The service returns the audio file directly in the response body, allowing seamless integration into your e-learning production pipeline.

Each request supports up to 4096 characters of input text. For longer training modules, split the content into chunks and join the resulting audio files. Failed requests incur no charge, ensuring cost efficiency during integration testing.

POST /v1/audio/speech

Send a JSON payload to this endpoint to generate audio. The request must include authentication via the Bearer token. The API processes requests sequentially, so under load, synthesis may wait in a queue.

  • Supports standard TTS parameters: model, input, voice, response_format, and speed.
  • Returns audio data directly in the response body.
  • Handles text up to 4096 characters per call.

JSON Body Structure

The request body is a JSON object containing the text to synthesize and the desired output settings. All fields are optional except input.

The input field accepts plain text strings. Spaces and punctuation count toward the character limit. The API does not support SSML or phoneme dictionaries.

  • model: "tts-1" or "tts-1-hd"
  • input: string (max 4096 chars)
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25–4.0
  • language: optional ISO code

Required Fields

The input field is mandatory and contains the text for your training material. Without it, the API returns an error.

model and voice are strongly recommended. While the API may use defaults, specifying them ensures the correct audio quality and voice for your corporate content.

Use response_format to match your LMS requirements. MP3 is standard for web playback, while WAV or FLAC suits high-fidelity archival needs.

  • input: The text to synthesize.
  • model: Defines quality tier (tts-1 or tts-1-hd).
  • voice: Selects the speaker preset.

Voice and Model Selection

Sound wave illustration for: Voice and Model Selection

Selecting the correct model and voice ensures your e-learning modules meet specific pedagogical standards. Both models use the same underlying engine and pricing structure, but tts-1-hd offers higher audio quality. The primary difference lies in audio quality, as tts-1-hd offers higher fidelity than tts-1.

tts-1 vs tts-1-hd

The tts-1 and tts-1-hd models use the same engine but differ in audio quality. They share the same pricing structure ($0.01 per 1,000 characters). You can switch between them without affecting your budget calculations.

Available Voices List

We provide eight presets optimized for corporate training and instructional content. Each voice has a distinct tone suitable for different learning contexts, from calm narration to energetic promos.

  • Female: aria (warm, clear narrator), nova (bright, upbeat), luna (soft, storytelling), sage (calm, instructional)
  • Male: felix (energetic, promo), milo (friendly, conversational), atlas (neutral, news), orion (deep, documentary)

Speed Parameter Range

Adjust the speed parameter between 0.25 and 4.0 to match listener comprehension levels. Slower rates (0.5–0.75) benefit complex technical explanations, while faster rates (1.2–1.5) suit review modules. The default speed is 1.0.

Response Formats

Sound wave illustration for: Response Formats

The API accepts response_format to control audio output. Supported formats are mp3, wav, opus, flac, and pcm. This parameter determines the file type returned in the HTTP response body.

MP3 Output

MP3 is the default format. It provides a good balance between file size and quality for most e-learning applications. This format is widely supported by standard media players and LMS platforms.

WAV Output

WAV delivers uncompressed audio data. Use this format when maximum fidelity is required for archival purposes or when processing audio with tools that do not support compressed codecs. File sizes will be significantly larger than MP3.

Opus, FLAC, PCM Options

Opus offers high-quality compression suitable for low-bandwidth transmission. FLAC provides lossless compression, reducing file size without quality loss. PCM returns raw uncompressed audio samples, ideal for immediate playback or further digital signal processing.

Language Detection and Settings

Sound wave illustration for: Language Detection and Settings

Our API handles language selection through either automatic detection or explicit configuration. You can rely on the engine to infer the language from the text script, or provide a specific ISO code for precise control over multilingual e-learning content.

Auto-Detection Logic

If the language field is omitted, the system guesses the language based on the character set of the input text. This works reliably for standard scripts but may require explicit codes for mixed-language inputs.

  • Script-based inference from input text

Explicit Language Code

Pass the language parameter with a valid ISO code to ensure accurate synthesis. This is critical when the text contains ambiguous characters or when generating content for the supported languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

  • Supports 23 specific languages
  • Ensures correct voice rendering

Latin Script Default

When Latin script is detected and no language is specified, the system defaults to English. For other Latin-script languages (e.g., German or Spanish), you must set the language parameter explicitly to avoid incorrect pronunciation.

  • Latin script defaults to English
  • Explicit code required for other Latin languages
Language Detection and Settings

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Rate limits protect the API's stability during high-volume e-learning production. You are allowed 60 requests per minute per API key. This limit applies uniformly regardless of text length or voice selected.

60 Requests Per Minute

Each key supports up to 60 concurrent or sequential requests within a one-minute window. If you exceed this threshold, subsequent requests will receive a 429 Too Many Requests error until the window resets.

10 Requests Before Top-Up

New accounts starting without a top-up are restricted to 10 requests per minute. This lower limit ensures basic access while preventing resource exhaustion before a payment method is established. Top-ups via USDT (TRC-20) lift this restriction immediately upon credit confirmation.

  • Minimum top-up: $5 USDT on TRON network
  • Credits appear automatically within minutes
  • No monthly plans or seat limits

Queue Behavior

Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. Typical generation speed is roughly real-time (25 characters per second), but short phrases may take a few seconds. Plan your integration accordingly to avoid timeouts.

Example: cURL Request

Sound wave illustration for: Example: cURL Request

This section demonstrates a direct cURL request to generate audio. It covers the basic command structure, required headers, and the JSON body needed to synthesize speech using the VoxTrain API.

The example uses a standard POST request with a valid bearer token. It illustrates how to send text input and select a specific voice model for your e-learning content.

Basic Command Structure

Use the following cURL command to send a text-to-speech request. Replace YOUR_API_KEY with your actual key from the dashboard.

The command targets the https://api.1930cup.info/v1 base URL and uses the /audio/speech endpoint.

  • curl -X POST initiates the request.
  • -H "Authorization: Bearer YOUR_API_KEY" authenticates the request.
  • -H "Content-Type: application/json" specifies the payload format.

Headers and Body

The request body must include the model, input, voice, and response_format fields. The input text is limited to 4096 characters.

You can optionally set a speed parameter between 0.25 and 4.0. The language field is optional but recommended for non-English Latin script text.

  • model: "tts-1" or "tts-1-hd"
  • voice: e.g., "sage" for instructional content
  • response_format: "mp3", "wav", "opus", "flac", or "pcm"

Expected Response

A successful request returns an audio file in the specified format. If synthesis fails, the charge is returned in full.

The API returns the binary audio data directly in the response body. Ensure your client handles binary streams correctly.

Example: OpenAI SDK Integration

Sound wave illustration for: Example: OpenAI SDK Integration

The OpenAI SDKs work seamlessly with VoxTrain by overriding the base URL. This allows you to use familiar code structures while routing requests to our dedicated infrastructure.

Ensure your API key is securely stored and passed as a Bearer token. The SDK handles the JSON serialization automatically, simplifying integration for HR training pipelines.

Base URL Configuration

Set the base_url to https://api.1930cup.info/v1. This directs all API calls to our endpoint while maintaining compatibility with the standard OpenAI request shape.

Client Initialization

Initialize the client using your API key. The key starts with tts- and is issued from your dashboard. No additional SDK-specific parameters are required for basic usage.

Speech Generation Code

Call the audio.speech.create method with your model, input, voice, and response_format. For multilingual e-learning, explicitly set the language code if the text uses Latin script but is not English to ensure correct pronunciation.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Ensure your chosen format is supported by the devices your HR staff and trainees will use.

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. Python documentation
  4. FFmpeg documentation
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. TRON developer hub: TRC-20
  7. Tether (USDT)
  8. LibriVox public-domain audiobooks
  9. Creative Commons Attribution 4.0
  10. W3C WAI: making audio and video accessible
  11. LibriTTS-R corpus (OpenSLR 141)
  12. openai-node on GitHub

More on this site