Frequently asked questions
Do I need a special SDK?
No. The API uses the same request shape as the OpenAI speech endpoint, so you can use any standard HTTP client or the official OpenAI SDKs by changing the base_url to https://api.playfomo7.com/v1. No custom SDK is required.
Can I use the OpenAI Python SDK?
Yes. The official OpenAI SDKs work by changing the base_url to https://api.playfomo7.com/v1. Use the same request shape as the OpenAI speech endpoint with your FomoVoice API key for authentication.
What is the maximum text length?
The input field supports up to 4096 characters per request. For longer texts, split the text into parts of up to 4096 characters and join the resulting audio files together.
Does the API support streaming?
No. The API does not support streaming, WebSockets, or real-time partial audio. Requests are processed synchronously, and you receive the complete audio file in the response once synthesis is finished.
Can I send SSML tags?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You can only send plain text input, along with voice, format, and speed parameters.
How do I set the language explicitly?
Pass the optional language field with an ISO code (e.g., 'en', 'de', 'fr'). If not set, the language is guessed from the script, defaulting to English for Latin text.
What formats are available?
You can choose from mp3, wav, opus, flac, and pcm via the response_format field. These formats cover most advertising and radio spot workflows.
Is there a rate limit per IP or per key?
Rate limits are applied per API key, not per IP. You are allowed 60 requests per minute per key, or 10 per minute before your first top-up.
How do I rotate my API key?
You can issue a new key at any time from your account page. The old key stops working immediately when the new one is active, ensuring a seamless transition.
Do I get charged for failed requests?
No. If synthesis fails, the charge is returned in full. You only pay for successful audio generation requests.
Can I generate audio in the background?
No. The API is synchronous. You send a request and wait for the audio file in the response. Requests are processed one after another, so under load, a request may wait in a queue.
Is the API synchronous or asynchronous?
The API is synchronous. You send a POST request and receive the audio file in the response. There is no webhook or background job system; you must poll or wait for the result.
Can I use the same key for multiple clients?
Yes. Each account has one active key that can be used by multiple clients or services. The rate limit of 60 requests per minute applies to the key as a whole.
What happens if I exceed the rate limit?
Requests will be queued and processed one after another. Under load, you may experience delays as requests wait in line. The limit is 60 requests per minute per key.
First request
curl
curl https://api.playfomo7.com/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.playfomo7.com/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.playfomo7.com/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 |
Authentication
Access the FomoVoice TTS API using a Bearer token in the Authorization header. This single key authenticates all requests from your account.
The API key is tied to your specific site account. You can generate a new key at any time via your dashboard.
Bearer Token Key
Include your key as Authorization: Bearer tts-... in every request header. This token validates your identity and tracks usage against your rate limits and balance.
- Format: Bearer tts-<your-key-here>
- Case-sensitive string
Single Active Key
Each account maintains one active API key at a time. If you issue a new key, the previous one becomes invalid immediately.
Key Rotation
Rotate your key anytime from the /get-api-key/ dashboard. The old key stops working instantly, ensuring secure access management for your ad agency workflows.
Endpoint Overview
The FomoVoice API provides three primary endpoints for generating and managing synthetic speech. The core generation endpoint accepts text and parameters to return audio files, while the metadata endpoints list available voices and models for integration planning.
POST /v1/audio/speech
This is the main endpoint for generating audio. Send a JSON body containing the text, voice selection, and desired format to receive an audio file. It supports texts up to 4,096 characters per request, with longer texts requiring client-side splitting.
- Accepts JSON body with model, input, voice, and response_format fields.
- Returns audio data directly in the response.
GET /v1/voices
Retrieve the list of available voices, their associated languages, supported formats, and current pricing. This endpoint helps developers dynamically update their UI to reflect current inventory and costs without hardcoding values.
- Returns details for all 8 voice presets.
- Includes language support and format options per voice.
GET /v1/models
List the available synthesis models. Currently, this includes "tts-1" and "tts-1-hd", which use the same engine and pricing structure. Use this to verify model availability before sending speech requests.
Request Parameters
Send your script text in the input field of the POST request. The API accepts up to 4096 characters per call, including spaces and punctuation. For longer radio spots or voiceovers, split your text into chunks and join the resulting audio files on your side.
Input Text Length
Each request is limited to 4,096 characters. This limit applies to the raw string sent in the input field, counting all spaces and punctuation marks. If your script exceeds this length, divide it into smaller segments and concatenate the returned audio files to create a complete spot.
Voice Selection
Choose from eight presets optimized for advertising workflows. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male options include Felix (energetic promo), Milo (conversational), Atlas (news), and Orion (documentary). Select the voice that matches your brand tone.
Every generated file includes an inaudible watermark identifying it as synthetic speech. This marks the file as synthetic speech.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
- Atlas: Neutral, news
- Orion: Deep, documentary
Response Format
Specify the audio format using the response_format parameter. Supported options are mp3, wav, opus, flac, and pcm. MP3 is recommended for web delivery due to its small file size, while WAV or FLAC offers higher quality for broadcast masters. PCM provides raw audio data for specialized processing pipelines.
Speed and Language
Adjust playback speed between 0.25 and 4.0 to fit ad timing precisely. Slower speeds enhance clarity for complex messages, while faster rates suit quick promotions. Each adjustment affects audio length proportionally without altering voice quality or character billing.
Speed Range 0.25–4.0
Set the speed parameter to control pacing. Values below 1.0 slow down the narration; values above 1.0 accelerate it. The default is 1.0. This feature helps match voiceovers to background music beats or radio station time slots.
- Minimum: 0.25 (half speed)
- Maximum: 4.0 (four times speed)
- Default: 1.0
Optional ISO Language Code
Pass the language parameter using a standard ISO 639-1 code (e.g., en, de, fr, es). This ensures correct pronunciation and intonation, especially for mixed-language content or when the default detection might misidentify the target language.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
Default English Detection
If language is omitted, the API guesses the language from the text script. Latin script defaults to English. For non-English Latin text (like Spanish or German), always specify the language code to prevent incorrect English pronunciation.
OpenAI SDK Integration
You can use the official OpenAI SDKs with minimal configuration. Simply update the base_url to point to our API endpoint, allowing you to leverage existing code structures without rewriting your integration logic.
The request shape is identical to the standard OpenAI speech endpoint. This means you can swap the provider in your application with just a few lines of code changes, keeping your development workflow smooth and familiar.
Change Base URL
Point your SDK’s base_url to https://api.playfomo7.com/v1. This single change directs all requests to our infrastructure while maintaining the standard OpenAI request format.
Use Official SDK
Install the standard OpenAI library as you normally would. Pass your tts-... Bearer token in the authorization header. The SDK handles serialization and response parsing exactly as it does for OpenAI’s service.
- No custom client required
- Standard authentication headers apply
Same Request Shape
The JSON body for POST /v1/audio/speech matches the OpenAI specification. Use parameters like model, input, voice, and response_format exactly as documented. Our API validates these fields identically to the reference implementation.
- Supports
tts-1andtts-1-hd - Accepts standard audio formats

cURL Example
Use cURL to test synthesis directly from your terminal. The following command sends a short script to the API and saves the resulting audio file locally, allowing you to verify voice quality before building your automation pipeline.
Basic Request
Run this command to generate speech. Replace YOUR_API_KEY with your secret key from /get-api-key/.
- ```bash
- curl -X POST https://api.playfomo7.com/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Hello, this is a test spot.", "voice": "nova"}' \
- -o output.mp3
- ```
Headers Setup
The Authorization header must contain your Bearer token. The Content-Type must be application/json. Ensure your key starts with tts-.
Response Handling
On success, the API returns the audio file directly. Save it to a local file using the -o flag. Failed requests return JSON with an error message and no charge.
Rate Limits
The FomoVoice API enforces strict rate limits to ensure stable synthesis performance for all users. Each API key is allowed a maximum of 60 requests per minute under normal conditions. This limit applies globally to your account, so plan your batch voiceover generation accordingly.
60 Requests Per Minute
Standard keys can process up to 60 requests per minute. This throughput allows you to generate multiple radio spot variations.
10 RPM for New Keys
New API keys start with a lower limit of 10 requests per minute. This applies until you make your first top-up. Once you add funds via USDT (TRC-20), your limit increases to the standard 60 RPM immediately.
Queue Behavior
Requests are processed sequentially. If you exceed the limit or send many requests simultaneously, additional requests will wait in a queue. You will receive the audio file once your turn arrives.
Longer texts take more time to synthesize. Keep this in mind when planning your API calls to avoid unnecessary queuing delays during peak usage times.
- 60 RPM for verified keys
- 10 RPM for new keys
- Requests are processed sequentially
- Limit increases after top-up
Error Handling
The API is designed to protect your budget by ensuring you only pay for successful synthesis. If a request fails due to server errors or invalid parameters, no charge is applied to your balance.
Failed Request Refund
Any request that does not return a valid audio file is considered failed. The system automatically reverses any attempted charge, so your character count remains unchanged. This applies to both transient network issues and permanent configuration errors.
Common Error Codes
Standard HTTP status codes indicate the issue. A 400 error means invalid input, such as text exceeding 4096 characters or an unknown voice ID. A 401 error indicates an expired or incorrect API key. A 500 error suggests a temporary server issue during synthesis.
- 400: Bad Request (invalid format or text length)
- 401: Unauthorized (invalid or revoked key)
- 429: Too Many Requests (rate limit exceeded)
- 500: Internal Server Error (synthesis failure)
Retry Logic
For 500 errors, implement a simple exponential backoff retry. Do not retry 400 errors as they will fail again. If you hit the 60 requests per minute limit, pause briefly before sending the next batch to avoid queuing delays.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
