Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email. You receive one active key per account. You can issue a new key at any time, which immediately invalidates the old one. The dashboard displays your key, balance, and usage statistics for easy reference.
What is the base URL for the API?
The API base URL is https://api.ub150.net/v1. You send POST requests to https://api.ub150.net/v1/audio/speech for synthesis. Other endpoints like voices and models are available at GET /v1/voices and GET /v1/models respectively.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. Simply change the base_url to https://api.ub150.net/v1 and use your site's key. The request shape matches the OpenAI speech endpoint, allowing seamless integration into your existing workflows without custom code.
How do I specify a voice?
Include the voice parameter in your JSON body. Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrator to deep documentary, suitable for various content types.
What is the maximum input length?
The maximum input length is 4096 characters per request. For longer texts, split them into parts of up to 4096 characters and join the resulting audio files. Spaces and punctuation count toward this character limit.
How do I set the language?
Set the language parameter using an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly set it for non-English Latin-script text to ensure accuracy.
What are the available formats?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the response_format field in your request. These options cover most standard audio needs for blogs, accessibility projects, and client deliverables.
How does speed affect generation?
Adjust speed between 0.25 and 4.0. Typical speed is roughly real-time (25 characters per second). Short phrases take a few seconds to generate.
What happens if I exceed rate limits?
The limit is 60 requests per minute per key (10 before first top-up). Exceeding this may cause requests to wait in a queue. Failed requests are free, so you are not charged for timeouts.
Are requests processed instantly?
Requests are processed sequentially. Under load, a request may wait in a queue. Typical speed is real-time for long texts, but short phrases take a few seconds. Expect slight delays during high traffic periods.
How do I handle errors?
If synthesis fails, the charge is returned in full. Check your request format and voice availability. Use the dashboard to monitor usage and balance. Failed requests incur no cost, protecting your budget during testing.
Is the API REST-based?
Yes, it is a standard REST API. Send POST requests for speech synthesis and GET requests for voices and models. Use JSON bodies for input and receive audio files in the response. It follows standard HTTP conventions.
Can I use Bearer token auth?
Yes, use Authorization: Bearer tts-... with your API key. One active key per account is supported. Issue a new key anytime to revoke the old one immediately. This ensures secure access to your billing and generation.
How do I find model details?
Send a GET request to /v1/models to see available models. You can also choose between tts-1 and tts-1-hd models. Both use the same engine and price. The /v1/voices endpoint provides details on voices, languages, formats, and pricing.
First request
curl
curl https://api.ub150.net/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.ub150.net/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.ub150.net/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 Your API Key
To start generating audio, you need an API key. Visit the /get-api-key/ page and choose your preferred method. This key authenticates your requests to the API and tracks your character usage against your balance.
Google Sign-In
Click the Google Sign-In button to create an account instantly. This method grants you an immediate free trial credit of $0.50, allowing you to generate approximately 50,000 characters within the first seven days.
- Instant account creation
- $0.50 free trial credit included
- Credits valid for 7 days
Email Sign-Up
Enter your email and create a password to register. Accounts created this way start with a zero balance, so you will need to top up via USDT (TRC-20) before making your first request. This option is ideal if you prefer not to use Google for authentication.
- No Google account required
- Standard email/password authentication
- No trial credit included
First Request
Start generating audio immediately with a single HTTP POST to the speech endpoint. The API accepts plain text and returns an audio file, allowing you to integrate voiceovers into client deliverables without managing infrastructure.
Curl Example
Use this command to test the endpoint. Replace YOUR_API_KEY with the key found on your dashboard and update the input text with your content.
- curl -X POST https://api.ub150.net/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"}'
JSON Body
The request requires a JSON object containing the text, voice selection, and output format. You can optionally specify a speed between 0.25 and 4.0 or lock the language ISO code.
SDK Integration
Integrate ReadAloud Freelance into your workflow using the OpenAI SDK, which is already familiar to most developers. The only adjustment required is pointing the client to our API base URL instead of OpenAI’s servers. This allows you to reuse existing code snippets and libraries without learning a new client structure.
Once configured, your scripts can generate speech in any of the 23 supported languages instantly.
OpenAI SDK
The TTS endpoint follows the same request shape as OpenAI’s speech API. You can use any standard OpenAI SDK version with the tts-1 or tts-1-hd models. Simply pass your text, voice, and format parameters as usual.
- Use standard
openaiPython or Node.js packages - Supports
tts-1andtts-1-hdmodels - Identical JSON body structure to OpenAI
Base URL Change
To direct requests to ReadAloud Freelance, update your SDK’s base URL configuration. Set the base URL to https://api.ub150.net/v1 and use your unique API key for authentication.
This single change routes all synthesis requests to our infrastructure while maintaining standard headers and response formats. Your existing rate-limiting and error-handling logic will continue to work as expected.
- Base URL: https://api.ub150.net/v1
- Auth:
Authorization: Bearer tts-... - No other code changes needed
Voices Endpoint
Fetch available voices and supported languages with a simple GET request to /v1/voices. This endpoint returns the full list of 8 presets, their audio characteristics, and the 23 supported languages, helping you choose the right voice for your client's content without guessing.
List Voices
Use GET /v1/voices to retrieve details for all 8 voice presets, including Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each voice has distinct tonal qualities suitable for blogs, tutorials, or documentaries. The response confirms available formats and pricing, ensuring you select the optimal model before generation.
- GET https://api.ub150.net/v1/voices
- Returns JSON array of voice objects
- Includes voice ID, name, and gender
Language Codes
Pass the language parameter as an ISO 639-1 code (e.g., en, de, fr) to ensure accurate pronunciation. While the API guesses language from the script, explicitly setting it prevents errors for Latin-script texts that aren't English. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
- en: English
- de: German
- fr: French
- es: Spanish
- ja: Japanese
- zh: Chinese
Models
The API offers two model options, tts-1 and tts-1-hd, which use the same underlying engine and share identical pricing. You can choose either without affecting your cost per character.
Both models support the full range of 8 voice presets and 23 languages, ensuring consistent quality regardless of your selection.
tts-1
This is the standard model for general text-to-speech generation. It delivers audio suitable for blog posts, audiobooks, and accessibility content.
- Standard quality output
- $0.01 per 1,000 characters
- Same engine as tts-1-hd
tts-1-hd
The high-definition variant provides audio fidelity. It is ideal for projects where sound quality is a priority, such as professional client deliverables or high-end podcasts.
- High-definition audio quality
- $0.01 per 1,000 characters
- Same engine as tts-1

Request Parameters
Freelancers often need to convert blog posts or client copy into audio quickly. This API handles the heavy lifting, letting you focus on content strategy rather than infrastructure management.
Input Text
Send your script via the input field. You can send up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer articles, split the text and join the resulting audio files.
- Max 4096 characters per request
- Spaces and punctuation count as characters
- Split and join for longer content
Speed Control
Adjust the speed parameter to fit your project's tone. Valid values range from 0.25 to 4.0. Use slower speeds for instructional content and faster rates for quick summaries or energetic promos.
- Range: 0.25–4.0
- Adjustable per request
- No SSML or phoneme tags
Response Format
Successful synthesis returns the generated audio file directly in the response body. The format matches your response_format choice—mp3, wav, opus, flac, or pcm—allowing immediate playback or saving to your client’s project folder. Since requests are processed sequentially, longer texts may experience slight delays as they queue behind other users’ requests.
If synthesis fails, the API returns a standard error JSON with a code and message. Crucially, any failed request is completely free, so you will not be charged for characters that did not result in audio. This protects your budget when dealing with edge cases or network hiccups.
Audio File
The response body contains the raw audio bytes. Save this directly to disk or stream it to your audio player. Remember that input text is limited to 4096 characters per request; for longer scripts, split the text, generate each part, and join the resulting audio files.
Generated audio is not stored on our servers after the response is sent, ensuring your client’s content remains yours. Each file carries an inaudible watermark marking it as synthetic speech.
- Supported formats: mp3, wav, opus, flac, pcm
- Max input: 4096 characters per request
- Audio is returned in the response body, not stored
Error Codes
Errors return a JSON object with an error code and descriptive message. Common issues include invalid API keys, unsupported voices, or text exceeding the character limit.
Most importantly, failed requests are free. If synthesis fails, the charge is returned in full, so you can retry or debug without worrying about your balance. This makes testing your freelancer workflows risk-free.
- Failed requests are free
- Returns JSON with error code and message
- No hidden charges for failed synthesis
Rate Limits
Your API key allows 60 requests per minute, but starts at a conservative 10 requests per minute until you add your first top-up. This limit ensures fair usage across our shared infrastructure while you manage multiple client projects.
60 Requests Per Minute
Once you top up your USDT balance, your limit increases to 60 requests per minute. This tier supports high-volume freelance workflows, such as generating audio for long blog posts or accessibility documents without hitting walls.
- Starts at 10 req/min for new accounts
- Increases to 60 req/min after first top-up
- Limits apply per API key, not per project
Queue Handling
Requests are processed sequentially, meaning under heavy load, your synthesis job may wait in a queue. Short phrases typically generate in a few seconds, while longer texts process at roughly real-time speed (25 characters per second).
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. For content creators working with diverse audiences, language support is critical.
23 languages
Any voice speaks any of these languages.
