Frequently asked questions
What base URL should I use?
Use https://api.ufago.top/v1 as your base URL. This allows you to use the official OpenAI SDKs by simply changing the base_url configuration. Your API requests, such as POST /v1/audio/speech, are sent to this endpoint with your Bearer token in the Authorization header.
How do I create an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Each account receives one active API key starting with 'tts-'. You can issue a new key at any time, which immediately invalidates the old one, ensuring secure access control for your integrations.
Does the API support SSML?
No, the API does not support SSML. You send plain text in the 'input' field, up to 4096 characters. If you need pauses or emphasis, you can adjust the speed parameter between 0.25 and 4.0, or split your text into separate requests for precise control.
How long does generation take?
Generation is roughly real-time, processing about 25 characters per second. Short phrases take a few seconds, while longer texts take longer. Requests are processed sequentially, so under load, your request may wait in a queue before synthesis begins, affecting total latency during high traffic periods.
What happens on error?
If synthesis fails, the charge is returned in full. Failed requests are free. You will receive an error response indicating the issue, allowing you to retry or adjust parameters like text length or voice selection without losing any of your prepaid character balance.
Can I change the speed?
Yes, you can adjust the speed between 0.25 and 4.0. This allows you to slow down narration for clarity or speed up content for quick updates. The speed parameter is part of the JSON request body sent to the /v1/audio/speech endpoint.
What formats are supported?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format in the 'response_format' field of your request. This flexibility allows you to choose the best balance between file size and quality for your specific application needs.
Is there a rate limit?
Yes, the limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. If you exceed this, you may experience delays. Ensure your application handles rate limit errors gracefully by implementing exponential backoff for retries.
Can I send multiple requests in parallel?
Yes, you can send multiple requests concurrently. However, requests are processed one after another, so under load, they may queue up. Parallel requests do not guarantee simultaneous completion, especially if the system is busy. Monitor your queue times to optimize your throughput effectively.
How do I handle long texts?
Split texts into parts of up to 4096 characters per request. Generate audio for each part, then join the resulting audio files. This ensures each request stays within the character limit while allowing you to create longer narrations by combining the outputs programmatically.
Is the API public?
Yes, the API is public. You can access it from any application that can make HTTP requests. Use your API key for authentication. There are no restrictions on where you can call the API from, making it suitable for web, mobile, or server-side integrations.
Which voices are available?
Eight voices are available: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each has a distinct tone, from warm narrators to deep documentary styles. You can specify any voice in the 'voice' field, and they support all 23 languages provided by the API.
Can I use my own voice?
No, custom voice cloning is not offered. You cannot upload your own voice or design a custom voice. The API uses eight preset voices based on licensed recordings. If you need a specific voice, you must choose from the available presets provided in the API.
Is data stored?
Input text is used only to produce audio and is not used for training. Generated audio is returned in the response and not stored. Request metadata, including time, characters, and status, is kept for billing purposes. Your data remains private and secure during processing.
First request
curl
curl https://api.ufago.top/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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.ufago.top/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.ufago.top/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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Get API Key
Get your API key to start generating audio. Visit the /get-api-key/ page to sign up using Google or create an account with email and password. This gives you immediate access to the API base URL and a ready-to-use cURL example.
Each account comes with one active key. You can issue a new key at any time, and the old one stops instantly. Start with a $0.50 free trial if you sign in with Google, valid for 7 days.
Google Sign-in
Click ‘Sign in with Google’ on the /get-api-key/ page. You receive $0.50 in trial credit immediately, valid for 7 days. This covers about 50,000 characters of text.
Your API key appears on the dashboard alongside your balance and usage stats.
- Instant trial credit
- No credit card required
- Access to all voices
Email Sign-up
Enter your email and password to create an account. Unlike Google sign-ups, email accounts start without trial credit. You must top up to begin generating audio.
Your key is displayed immediately after verification.
- No trial credit included
- Secure email verification
- Standard access
Manage Keys
Your dashboard shows your current API key, balance, and character usage. You can generate a new key anytime. The old key stops working immediately upon issuance.
Use the key in the Authorization header: Bearer tts-....
- One active key per account
- Instant invalidation of old keys
- View usage history
First Request with cURL
Start by pointing your requests to the API base URL. This endpoint handles the JSON payload and returns the audio file directly.
Set Base URL
Use https://api.ufago.top/v1 as your base URL. This ensures compatibility with standard HTTP clients and allows you to use the official OpenAI SDKs by simply changing the base_url parameter.
- Base URL: https://api.ufago.top/v1
- Method: POST
- Endpoint: /v1/audio/speech
Create JSON Body
Construct a JSON body with the model, input, voice, and response_format fields. You can optionally specify speed (0.25–4.0) and language (ISO code). Text must not exceed 4096 characters.
- model: "tts-1" or "tts-1-hd"
- input: your product description text
- voice: e.g., "aria", "nova"
- response_format: "mp3", "wav", "opus", "flac", or "pcm"
Process Response
The API returns an audio file in the requested format. Failed requests are free, so you only pay for successful synthesis. Include your API key in the Authorization: Bearer header.
Use OpenAI SDK
The OpenAI SDKs work seamlessly with our API by simply adjusting the base URL. Point your client to https://api.ufago.top/v1 and use your standard tts-... API key. This allows you to leverage familiar libraries while accessing our 23 languages and 8 voice presets without learning a new syntax.
Below is a minimal Python example using the OpenAI SDK. It sends a text request for the 'nova' voice and saves the resulting MP3 file locally. This approach keeps your code clean and leverages existing error-handling patterns from the OpenAI ecosystem.
Change Base URL
Update your SDK configuration to point base_url to https://api.ufago.top/v1. Ensure your Authorization header uses the Bearer tts-... key generated from your account dashboard. This single change routes requests to our TTS endpoint while maintaining compatibility with standard OpenAI client structures.
The SDK expects the same JSON body shape as the OpenAI speech endpoint. You can continue using standard parameters like model, input, voice, and response_format. No additional custom headers or body fields are required beyond what the OpenAI API defines.
- Base URL: https://api.ufago.top/v1
- Auth Header: Bearer tts-<your-key>
- SDK Compatibility: OpenAI Python/Node.js libraries
Code Example
This Python snippet demonstrates how to generate speech using the OpenAI SDK. It configures the client with our base URL, requests an MP3 file using the 'nova' voice, and writes the binary response to disk. Adjust the input text and voice preset as needed for your product descriptions.
```python import openai client = openai.OpenAI(base_url="https://api.ufago.top/v1", api_key="tts-<your-key>") with client.audio.speech.with_streaming_response.create( model="tts-1", voice="nova", input="Hello, welcome to our store." ) as response: response.stream_to_file("output.mp3") ```
The request processes text up to 4096 characters. For longer content, split your text into chunks, generate each part, and concatenate the audio files. The SDK handles the streaming efficiently, ensuring minimal memory usage during file creation.
Error Handling
Handle standard HTTP errors like 400 for invalid parameters or 429 for rate limits. Failed synthesis requests are free, so check the status code to ensure you aren’t charged for errors. Implement retry logic with exponential backoff for 500 errors.
If you receive a 429 error, pause briefly before retrying, as you may have hit the 60 requests per minute limit. For 400 errors, verify that your voice or model parameters match our supported presets. The SDK will raise an exception, which you can catch and log appropriately.
Voices & Languages
Choose the right voice and language to match your product descriptions or help text. Ufago provides eight distinct voice presets and supports 23 languages, ensuring natural-sounding audio for your online store team.
Our voices are based on licensed recordings from LibriTTS and LibriVox, offering clear, professional tones without the need for hiring voice actors. You can generate speech in any of the supported languages using any of the eight voices.
8 Available Voices
Select from eight presets tailored for different content types, from warm narrators to energetic promo voices.
Female voices include aria (warm, clear narrator), nova (bright, upbeat), luna (soft, storytelling), and sage (calm, instructional). Male voices include felix (energetic, promo), milo (friendly, conversational), atlas (neutral, news), and orion (deep, documentary).
23 Languages
Generate audio in Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish. Any voice can speak any of these languages.
Set Language
If you do not set the language field, the API guesses the language from the script (Latin text defaults to English). For non-English Latin-script text, always set the language parameter to ensure accurate pronunciation.
Audio Formats
Choose the audio format that best fits your store’s workflow. MP3 offers universal compatibility for web players, while WAV provides uncompressed quality for high-fidelity needs. We support OPUS, FLAC, and PCM for specific use cases like efficient storage or raw data processing.
MP3
MP3 is a common choice for most web integrations. It balances file size and quality, ensuring smooth playback across all devices and browsers without extra configuration.
WAV
WAV files are uncompressed and ideal for editing or high-quality archival. Use this format if your product team needs pristine audio for accessibility compliance or detailed review.
OPUS, FLAC, PCM
OPUS offers high quality at low bitrates, perfect for mobile data efficiency. FLAC provides lossless compression for archival purposes. PCM delivers raw, uncompressed audio data for specialized processing pipelines.
- OPUS: Efficient compression for mobile
- FLAC: Lossless archival quality
- PCM: Raw uncompressed data

Error Codes
When your request fails, the API returns a specific HTTP status code to help you fix the issue quickly. Most errors are caused by incorrect parameters, exceeding limits, or temporary service issues.
400 Bad Request
This error means your JSON body is invalid or missing required fields like model, input, or voice. Ensure input is under 4096 characters and response_format is one of the supported audio formats.
429 Rate Limit
You have exceeded the limit of 60 requests per minute per key. If you are new and haven’t topped up yet, the limit is stricter at 10 requests per minute. Wait a few seconds and retry.
500 Server Error
A temporary issue on our side prevented speech synthesis. Failed requests are free, so you can retry the same text without worrying about your balance. If the issue persists, contact us via email.
Rate Limits
Every API key allows 60 requests per minute. If you exceed this limit, the API returns a 429 error. You can monitor your usage directly in your account dashboard to stay within these bounds.
Before your first top-up, you are limited to 10 requests per minute. This lower limit helps prevent accidental bursts while you are testing the service. Once you add USDT, your standard 60 requests per minute limit applies immediately.
60 Requests per Minute
Your active key supports up to 60 requests per minute. This is sufficient for many batch processing tasks. If you need higher throughput, consider splitting your workload across multiple keys.
- Limit: 60 requests/minute per key
- Applies to all request types
10 Requests Before Top-up
New accounts start with a 10 requests per minute limit. This ensures fair usage during the trial phase. The limit increases automatically after you add credit.
- Initial limit: 10 requests/minute
- Increases after top-up
Queue Behavior
Requests are processed sequentially. Under heavy load, a request may wait in a queue. Short phrases typically take a few seconds to generate. Longer texts may take longer due to processing time.
- Sequential processing
- Queuing under load
Code Examples
These examples show how to generate audio for product descriptions or help text using your API key. They cover the standard request format and handle the JSON response containing the audio blob.
Python Script
Use the OpenAI SDK for Python. Set the base URL to https://api.ufago.top/v1 and provide your Bearer token. The code sends the text and voice parameters, then saves the returned audio file locally.
JavaScript Snippet
Fetch works directly with the endpoint. Construct the POST request with the JSON body containing model, input, and voice. Decode the base64 response body to save as an MP3 or WAV file in your storefront.
cURL Command
Run this command in your terminal to test synthesis. Replace YOUR_API_KEY and the input text. The response returns the audio data, which you can redirect to a file for immediate playback or storage.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. OPUS offers superior compression efficiency for web delivery.
23 languages
Any voice speaks any of these languages.
