Cloud Text-to-Speech API: Integration Guide

By Vocafy editorial team · Updated 2026-11-19

This guide helps startups integrate Vocafy’s cloud text-to-speech API into their language learning products. You will learn how to send text and receive high-quality audio files using standard HTTP requests. The documentation covers authentication, available voices, and supported formats to ensure smooth implementation.

Developers can use the OpenAI SDK or plain HTTP to connect to our API. We provide concrete examples for cURL, Python, and JavaScript. Read on to understand rate limits, error handling, and best practices for splitting long texts and adjusting speech speed for optimal user experience.

Cloud Text-to-Speech API: Integration Guide

Frequently asked questions

How do I get my API key?

Sign up at /get-api-key/ using Google or email. Your key appears on the dashboard, starting with 'tts-'. Pass it via the Authorization header as 'Bearer tts-...'. You can issue a new key anytime via the dashboard; the old one stops immediately.

What is the base URL for the API?

The API base URL is https://api.tda7388.info/v1. Use POST https://api.tda7388.info/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models for configuration details.

Can I use the OpenAI SDK with this API?

Yes. The request shape matches the OpenAI speech endpoint. Change the SDK’s base_url to https://api.tda7388.info/v1 and use your Vocafy key. The official OpenAI SDKs work directly with this configuration.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Specify the format in the response_format field of your request body. The API returns the audio file in the selected format.

How do I handle texts longer than 4096 characters?

Split your text into parts of up to 4096 characters. Send each part in a separate request. Then join the resulting audio files client-side to create the final output.

What is the default language if not specified?

If the language field is omitted, the system guesses from the script. Latin script defaults to English. For non-English Latin text, explicitly set the language to ensure correct pronunciation.

How do I change the speech speed?

Use the speed parameter in your request body. Acceptable values range from 0.25 to 4.0. This adjusts the playback rate of the generated audio file.

Is there a limit on the number of voices?

You can choose from 8 preset voices: aria, nova, luna, sage, felix, milo, atlas, and orion. Select any voice for any supported language. There is no limit on switching between them.

How do I rotate my API key?

Issue a new key anytime via your dashboard. The new key becomes active immediately. The old key stops working at once. This allows seamless rotation without downtime.

What happens if I send invalid JSON?

The API returns an error response. Failed requests are free: if synthesis fails, the charge is returned in full. Ensure your JSON body matches the required schema.

Can I use the API with Python?

Yes. Use the official OpenAI Python SDK by setting the base_url to https://api.tda7388.info/v1. Alternatively, send standard HTTP POST requests with your API key in the Authorization header.

Does the API support streaming?

No. The API returns the complete audio file in the response. There is no streaming, WebSocket, or real-time partial audio support.

What is the difference between tts-1 and tts-1-hd?

Both models use the same engine and price. The choice is purely for your preference. There is no functional or cost difference between tts-1 and tts-1-hd in this API.

How do I check available voices?

Send a GET request to /v1/voices. This endpoint returns details on voices, languages, and formats.

First request

curl

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

Secure your access with a single API key issued upon account creation. This key authenticates all requests to the Vocafy TTS API, ensuring that only authorized startups can generate audio files for their language learning applications.

Use the key in the HTTP header as a Bearer token. You can rotate keys instantly via the dashboard; the previous key stops working immediately, allowing seamless transitions during deployment updates without downtime.

API Key Format

API Key Format

Keys begin with 'tts-' followed by a unique identifier. Store this string securely in your environment variables rather than hardcoding it into your application source code.

Each account holds one active key at a time, simplifying credential management for small engineering teams.

  • Format: tts-[unique-string]
  • Scope: Account-wide access
  • Limit: One active key per account

Bearer Token

Bearer Token

Include the header Authorization: Bearer tts-... in every POST request to the speech endpoint. The API validates this token before processing your text input.

Invalid or expired keys return a 401 Unauthorized error, allowing you to quickly detect configuration issues during integration.

Key Rotation

Generate a new key from the dashboard to invalidate the old one instantly. This is useful if you suspect a key has been exposed in logs or version control.

Since only one key is active, ensure your deployment pipeline updates the environment variable before issuing the new key to avoid service interruption.

Endpoints

Sound wave illustration for: Endpoints

The Vocafy API exposes three core endpoints for generating audio and managing resources. The speech endpoint handles synthesis requests, while the voices and models endpoints provide metadata about available options. All endpoints use standard HTTP methods and return JSON or audio data.

Integration begins with the speech endpoint, where you send text and receive an audio file. The voices endpoint lists all 8 presets and 23 supported languages, helping you choose the right voice for your language learning app. The models endpoint confirms available engine versions.

Speech Endpoint

Send a POST request to https://api.tda7388.info/v1/audio/speech with a JSON body containing model, input, and voice. The API returns an audio file directly in the response body. Text is limited to 4096 characters per request.

If your text exceeds this limit, split it into chunks and concatenate the resulting audio files. The endpoint supports response_format for mp3, wav, opus, flac, or pcm output.

  • Endpoint: POST /v1/audio/speech
  • Input: JSON body with input (max 4096 chars)
  • Output: Audio file (mp3, wav, opus, flac, pcm)

Voices Endpoint

Access GET https://api.tda7388.info/v1/voices to retrieve a list of all available voices, their IDs, and supported languages. This endpoint helps you verify which voices support specific languages like German or Japanese before making synthesis requests.

The response includes details on each voice’s gender and tone, such as 'aria' for warm narration or 'atlas' for neutral news style.

  • Endpoint: GET /v1/voices
  • Returns: Voice ID, name, gender, supported languages
  • Use case: Pre-flight check for voice availability

Models Endpoint

Call GET https://api.tda7388.info/v1/models to list available models. Currently, the API supports tts-1 and tts-1-hd, both using the same engine and price point.

This endpoint ensures compatibility with your integration setup, confirming that standard models are available for all regions.

  • Endpoint: GET /v1/models
  • Returns: Model ID, name, and status
  • Supported models: tts-1, tts-1-hd

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis request with precise parameters to control voice generation. Select the model, input text, and voice preset to generate audio that matches your startup's multilingual needs.

Model Selection

Choose between tts-1 and tts-1-hd. Both use the same engine and pricing, allowing you to switch based on quality preferences without changing your integration logic.

Input Text

Send plain text in the input field, limited to 4096 characters per request. Spaces and punctuation count toward this limit, so split longer scripts into chunks and join the resulting audio files.

Voice Selection

Select one of eight presets like aria or atlas. Every voice supports all 23 languages, but you must set the language parameter for non-English Latin text to ensure correct pronunciation.

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

Response Formats

Sound wave illustration for: Response Formats

The API returns audio data directly in the response body, allowing seamless integration with standard HTTP clients. You can choose between compressed formats for efficient bandwidth usage or lossless formats for high-fidelity playback, depending on your application's needs.

MP3 Output

MP3 is the default and most widely compatible format. It offers a good balance between file size and audio quality, making it ideal for web players and mobile applications where bandwidth efficiency is important.

WAV Output

WAV provides uncompressed, high-quality audio suitable for professional editing or playback systems that require lossless fidelity. It is larger than MP3 but ensures no data loss during transmission.

Opus and FLAC

Opus offers superior compression at low bitrates, perfect for voice-heavy applications. FLAC provides lossless compression, reducing file size without sacrificing quality, ideal for archival or high-end audio processing.

Rate Limits

Sound wave illustration for: Rate Limits

The Vocafy API enforces a standard rate limit of 60 requests per minute per API key. This ceiling ensures fair usage. Generation speed is roughly 25 characters of text per second on long texts, but requests are processed sequentially and may wait in a queue under load. Requests are processed sequentially, so high-volume applications may experience brief queuing during peak times.

When you first create an account, your initial limit is set to 10 requests per minute. This lower threshold helps verify your integration setup before scaling up. Once you complete your first top-up, the limit automatically increases to the full 60 requests per minute.

60 Requests Per Minute

Each API key supports up to 60 requests per minute. This limit applies to all endpoints, including speech synthesis and voice retrieval. If you exceed this threshold, the API returns a 429 Too Many Requests error. You should implement exponential backoff in your client code to handle retries gracefully without overwhelming the server.

  • Limit is per API key, not per IP address.
  • Applies to all request types equally.
  • Exceeding the limit returns a 429 status code.

Initial Limit

New accounts start with a restrictive limit of 10 requests per minute. This allows you to test integration with the OpenAI SDK or plain HTTP without risking a high burst of characters. The limit remains in effect until you add funds to your account via USDT on the TRON network.

  • Applies to new accounts only.
  • Applies to both free trial and paid accounts.
  • Unlocks fully after first top-up.

Limit Increases

Your rate limit increases automatically after your first successful top-up. There is no need to contact support or wait for manual verification. Once the USDT transfer is confirmed on the TRON network, your account immediately scales to the full 60 requests per minute, ready for production language learning features.

  • No manual verification required.
  • Instant activation after blockchain confirmation.
Rate Limits

Error Handling

Sound wave illustration for: Error Handling

Handling errors correctly ensures your application remains robust when the API encounters issues. The service returns standard HTTP status codes alongside descriptive messages, allowing you to distinguish between transient failures and permanent configuration mistakes. Understanding these responses helps you implement appropriate retry logic or user feedback mechanisms without unnecessary delays.

Our error responses are designed to be developer-friendly, providing clear context about what went wrong. This enables quick debugging whether you are testing integration scripts or running production workloads for language learning applications.

Common Errors

The API uses standard HTTP status codes to indicate success or failure. A 200 OK status means your audio file is ready. Any non-200 status indicates an issue that requires attention.

You may encounter 4xx errors for client-side issues like missing authentication headers or invalid parameters. 5xx errors indicate temporary server-side problems. Always check the response body for a detailed message explaining the specific cause of the failure.

  • 401 Unauthorized: Invalid or missing API key.
  • 400 Bad Request: Malformed JSON or missing required fields.
  • 500 Internal Server Error: Temporary service issue.

Rate Limit Exceeded

You are limited to 60 requests per minute per API key. If you exceed this limit, the API returns a 429 Too Many Requests error. This helps maintain stability for all users during peak usage times.

If you consistently hit this limit, consider implementing exponential backoff in your retry logic. You can also monitor your usage via the dashboard to adjust your request pacing accordingly.

  • 429 Too Many Requests: You have exceeded the 60 requests/minute limit.
  • Retry-After header: Indicates how many seconds to wait before retrying.

Invalid Input

Common input errors include exceeding the 4096 character limit per request or using an unsupported voice or format. Ensure your text input is within the allowed length and that the voice ID matches one of the eight available presets.

If you specify an invalid language code, the API may guess the language incorrectly. Always provide a valid ISO language code for non-English Latin-script text to ensure precise pronunciation.

  • 400 Bad Request: Input text exceeds 4096 characters.
  • 400 Bad Request: Invalid voice ID or response format.
  • 400 Bad Request: Unsupported language code.

Code Examples

Sound wave illustration for: Code Examples

Integrate Vocafy’s TTS API using standard HTTP or the OpenAI SDK. The API mirrors OpenAI’s speech endpoint, allowing you to swap the base URL and use existing client libraries with minimal code changes. This ensures a smooth transition for teams already familiar with modern API patterns.

Below are concrete examples for generating audio files in various formats. Each snippet demonstrates how to pass text, select a voice, and handle the response efficiently in your startup’s backend.

Curl Command

Use this command to generate speech instantly. Replace YOUR_API_KEY with your key from /get-api-key/. This example generates an MP3 clip using the nova voice.

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

OpenAI SDK

Leverage the official OpenAI SDK by pointing it to our base URL. This approach works with any language supported by the OpenAI client.

```python import openai client = openai.OpenAI(base_url="https://api.tda7388.info/v1", api_key="YOUR_API_KEY") with client.audio.speech.create( model="tts-1", voice="luna", input="Welcome to our language learning app" ) as response: response.stream_to_file("welcome.mp3") ```

Python Example

For direct HTTP requests, use the requests library. This method gives you full control over headers and retries, useful for handling rate limits or network issues in production environments.

```python import requests headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"} data = {"model": "tts-1-hd", "voice": "atlas", "input": "German pronunciation guide", "language": "de"} response = requests.post("https://api.tda7388.info/v1/audio/speech", headers=headers, json=data) with open("guide.wav", "wb") as f: f.write(response.content) ```

Best Practices

Sound wave illustration for: Best Practices

Efficient integration requires managing character limits and audio continuity. Since each request supports up to 4096 characters, longer texts must be split and reassembled by your client code to ensure seamless playback.

Text Splitting

Break input text into chunks of 4096 characters or fewer. Concatenate the resulting audio files in your application to create a continuous audio file.

Speed Adjustment

Use the speed parameter (0.25–4.0) to match your content style. Faster speeds reduce generation time, while slower rates improve clarity for educational materials.

Language Code

Always specify the language ISO code for non-English Latin-script text. Without it, the system defaults to English, which may cause pronunciation errors for other languages.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Pricing clarity is vital for startups scaling voice features.

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

More on this site