Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Accounts are specific to this site. Once registered, you can view your active API key, balance, and usage details directly on the dashboard page.
What is the base URL?
The API base URL is https://api.playfb7.com/v1. You use this endpoint for all requests, including POST /v1/audio/speech for synthesis, GET /v1/voices for available options, and GET /v1/models for model information. Ensure your client library points to this specific domain.
How do I use the OpenAI SDK?
The official OpenAI SDKs work by changing the base_url to https://api.playfb7.com/v1. Use your CivicVoice API key for authentication. The request shape matches the OpenAI speech endpoint, allowing you to generate audio files using the same code structure you would use for OpenAI's TTS service.
What parameters are required?
You must provide the model ("tts-1" or "tts-1-hd"), input text (up to 4096 characters), and voice (one of eight presets). Optional parameters include response_format, speed (0.25–4.0), and language. The language defaults to English if not set and the script is Latin.
What is the character limit?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split the content into parts of 4096 characters or less, generate audio for each part, and join the resulting audio files.
What audio formats are supported?
Supported formats are mp3, wav, opus, flac, and pcm. You specify the desired format using the response_format parameter in your request. The API returns the generated audio file in the specified format directly in the response body.
What is the rate limit?
The limit is 60 requests per minute per API key. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed. Requests are processed sequentially, so high load may cause queuing delays.
How do I handle errors?
If synthesis fails, the charge is returned in full. Monitor your response status codes to detect failures. Failed requests do not consume your character balance. Ensure your input text is within the 4096 character limit and the voice ID is valid.
Can I change the speed?
Yes. Use the speed parameter with values between 0.25 and 4.0 to adjust playback rate. This allows you to slow down narration for clarity or speed up content for efficiency. You can explicitly set the value to suit your specific audio requirements.
Is the API compatible with OpenAI?
Yes. The API accepts the same JSON request shape as OpenAI, so the official OpenAI SDKs work by changing the base_url to https://api.playfb7.com/v1. The models tts-1 and tts-1-hd use our engine, but the request structure remains identical. We are not affiliated with OpenAI.
How do I rotate my API key?
You can issue a new API key at any time from your account dashboard. When a new key is generated, the old one stops working immediately. This ensures secure access management without needing to wait for manual approval or expiration.
What happens if I exceed the limit?
If you exceed 60 requests per minute, subsequent requests may queue or fail. New accounts have a 10 requests per minute limit until the first top-up is credited. Failed requests are free, so exceeding limits does not incur extra charges; it only affects processing speed or results in a free failure.
Can I use multiple voices?
Yes, you can choose from eight voice presets: aria, nova, luna, sage, felix, milo, atlas, and orion. Each voice can speak any of the 23 supported languages. You specify the voice in each request to vary the audio output.
Is there a limit on request size?
The input text is limited to 4096 characters per request. This includes all spaces and punctuation. For longer content, you must split the text into smaller chunks, generate audio for each chunk, and then concatenate the resulting audio files.
First request
curl
curl https://api.playfb7.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.playfb7.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.playfb7.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
Accessing the CivicVoice API requires a valid authentication key, which is issued upon account creation via /get-api-key/. Each account maintains a single active key, ensuring straightforward credential management for government and NGO developers integrating audio synthesis into their digital services.
The key is transmitted as a Bearer token in the Authorization header of every request. This standard approach ensures compatibility with existing HTTP clients and the official OpenAI SDKs, allowing teams to switch base URLs without modifying their core authentication logic.
API Key Management
Keys are generated on the /get-api-key/ dashboard page alongside your current balance and usage statistics. You can revoke and issue a new key at any time from this same interface, immediately invalidating the previous token.
- One active key per account
- Issued via /get-api-key/ dashboard
- Immediate invalidation upon rotation
Bearer Token Usage
Include your key in the header: Authorization: Bearer tts-.... This format works seamlessly with both plain HTTP requests and the OpenAI Python/Node SDKs when the base_url is adjusted to https://api.playfb7.com/v1.
The token grants access to all endpoints, including speech synthesis and voice listing. Ensure the key is kept secure in your deployment environment variables rather than hardcoding it in client-side code.
- Header:
Authorization: Bearer <key> - Compatible with OpenAI SDKs
- Supports standard HTTP clients
Key Rotation
Rotating your key is instant. Generate a new key on the dashboard, and the old one stops working immediately. This allows you to update credentials in your infrastructure without a service interruption, provided you switch the token before the old one expires or is revoked.
There is no downtime during rotation. Update your application configuration to use the new key, and subsequent requests will succeed while older requests using the old key will return a 401 Unauthorized error.
- Instant invalidation of old key
- Zero downtime if configured correctly
- No manual approval required
Endpoint Overview
The API exposes three primary endpoints for generating and managing audio. The Speech endpoint accepts text and returns audio files, while the Voices and Models endpoints provide metadata for configuration. This structure allows developers to integrate CivicVoice into existing workflows with minimal overhead.
Each endpoint serves a distinct purpose in the synthesis pipeline. Developers use the Voices and Models endpoints to verify available parameters before sending requests to the Speech endpoint. This separation ensures that applications can adapt to changes in voice availability or model updates without disrupting the core audio generation process.
Speech Endpoint
Send a POST request to /v1/audio/speech with your text and desired parameters. The API processes requests sequentially, so under load, synthesis may queue briefly before returning. The response contains the generated audio file in the requested format.
Failed requests are free, with charges returned in full if synthesis fails. The input text is limited to 4096 characters per request. For longer texts, split the input and join the resulting audio files.
- Endpoint: POST /v1/audio/speech
- Returns: Audio file (mp3, wav, opus, flac, pcm)
- Limit: 4096 characters per request
Voices Endpoint
The GET /v1/voices endpoint returns a list of available voice presets, supported languages, and audio formats. This allows your application to dynamically populate user interfaces with valid options. You can verify that the selected voice supports the desired language before making a speech request.
- Endpoint: GET /v1/voices
- Returns: Voice presets, languages, formats
- Use: Validate options before synthesis
Models Endpoint
The GET /v1/models endpoint lists available models, such as tts-1 and tts-1-hd. Both models use the same engine and pricing. Use this endpoint to confirm model availability and ensure your application requests a valid model identifier.
- Endpoint: GET /v1/models
- Returns: Available model identifiers
- Use: Confirm valid model names

Quickstart with cURL
CivicVoice’s API accepts text input and returns synthesized audio via a simple POST request. This quickstart demonstrates the essential cURL command, covering the required JSON body, authentication header, and expected response structure for immediate integration testing.
Request Structure
Send a POST request to https://api.playfb7.com/v1/audio/speech. The body must include the model ("tts-1" or "tts-1-hd"), the input text (max 4096 characters), and a voice preset. Include your API key in the Authorization header as a Bearer token.
- Endpoint:
POST /v1/audio/speech - Auth:
Authorization: Bearer tts-... - Body:
model,input,voice,response_format,speed
Response Format
Successful requests return the audio file directly in the response body, with the content type matching your requested response_format (e.g., audio/mpeg for MP3). No additional JSON wrapper is included, allowing direct file saving or streaming into audio players.
Error Handling
If synthesis fails, the API returns an error status code. Crucially, failed requests incur no charge, and any pre-paid balance remains intact. Check the response body for details on why the request failed, such as invalid character limits or unsupported voices.
OpenAI SDK Integration
Integrating CivicVoice with existing codebases is straightforward because the API follows the same request structure as the OpenAI Speech endpoint. By simply adjusting the base URL, developers can leverage standard OpenAI SDKs without learning a new library or format.
This approach allows government and NGO teams to maintain their current development workflows while accessing multilingual TTS capabilities for accessibility projects.
Base URL Configuration
Set the SDK base URL to https://api.playfb7.com/v1. This directs all standard speech requests to the CivicVoice infrastructure. Ensure your API key is valid for this specific site domain.
Client Initialization
Initialize the OpenAI client using your standard language SDK. Pass the base URL and your tts-... Bearer token via the Authorization header. The SDK handles JSON serialization automatically.
Request Examples
Use the standard AudioResponse model or plain HTTP POST to https://api.playfb7.com/v1/audio/speech. Send a JSON body with model, input, voice, and response_format. The SDK returns the audio file directly for playback or storage.
Parameters Reference
The API accepts two model identifiers, "tts-1" and "tts-1-hd," which utilize the identical underlying engine and carry the same price per character. Selecting one over the other does not alter the base processing cost or the fundamental audio source, though the "hd" label may imply a different file encoding context for clients expecting high-definition metadata.
Model Selection
Choose "tts-1" or "tts-1-hd" based on your client's existing configuration expectations. Both parameters trigger the same synthesis engine, ensuring consistent voice characteristics regardless of the identifier used. The pricing remains uniform at $0.01 per 1,000 characters, so the choice is primarily about API contract alignment rather than cost or engine difference.
Voice Selection
Select from eight preset voices, each designed for specific tonal needs. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male options include Felix (energetic), Milo (conversational), Atlas (neutral news), and Orion (documentary). Any voice supports all 23 languages; set the language code explicitly for non-English Latin text to ensure accurate pronunciation.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
Speed Control
Adjust playback speed between 0.25 and 4.0 using the speed parameter. This allows fine-tuning of audio duration without re-synthesizing the text. Note that synthesis itself is not real-time; longer texts are split into 4,096-character chunks and processed sequentially, so speed adjustments apply to the final output file rather than the generation queue latency.

Audio Formats
CivicVoice allows you to select the audio container that best fits your infrastructure. You can request MP3, WAV, OPUS, FLAC, or PCM formats by passing the response_format parameter in your JSON body. The API returns the synthesized audio file in the specified format, ensuring compatibility with your existing playback systems.
MP3 Support
MP3 is the most widely supported format for web players and mobile applications. It provides a balance between file size and audio quality, making it suitable for general distribution to multilingual communities.
WAV Support
WAV files are generated without additional compression layers. This format is ideal for local storage or processing pipelines that require raw audio data without decoding overhead.
OPUS and FLAC Support
OPUS offers high efficiency with good quality, often preferred for voice communication streams. FLAC provides lossless compression, ensuring the audio remains identical to the source while reducing storage requirements compared to WAV.
Rate Limits and Quotas
CivicVoice enforces strict rate limits to ensure stable synthesis performance. Each API key is permitted 60 requests per minute once funded, with a lower baseline of 10 requests per minute for new accounts prior to the first top-up. These quotas reset on a sliding window basis.
Requests Per Minute
New accounts without a top-up are limited to 10 requests per minute. After your first USDT transfer is credited to your balance, the limit increases to 60 requests per minute. This higher limit applies to your active key as soon as the credit appears in your account, not instantly upon sending the transfer.
Character Limits
Each request can process up to 4096 characters. Spaces and punctuation count toward this limit. For texts exceeding this threshold, you must split the input into multiple requests and join the resulting audio files.
Queue Behavior
Requests are processed sequentially. During periods of high load, your request may wait in a queue before synthesis begins. Short phrases typically take a few seconds to generate, while longer texts process at roughly real-time speed (25 characters per second).

Error Codes
Understanding error responses ensures your integration handles failures gracefully without unnecessary retries. CivicVoice returns standard HTTP status codes to indicate the nature of the issue, allowing developers to adjust request parameters or authentication headers accordingly.
400 Bad Request
This error indicates a problem with the request structure or content. Common causes include missing required fields, invalid voice IDs, or text exceeding the 4,096-character limit per request. Review the JSON payload to ensure all parameters match the expected schema.
- Ensure
inputdoes not exceed 4,096 characters. - Verify
voicematches one of the 8 available presets. - Check that
modelis eithertts-1ortts-1-hd.
401 Unauthorized
A 401 error occurs when the API key is missing, incorrect, or invalid. Ensure your Authorization: Bearer tts-... header is present and matches the key issued in your dashboard. If you rotated your key, the old one stops immediately.
429 Too Many Requests
This response signifies that you have exceeded the rate limit of 60 requests per minute per key. During high-volume usage, requests are processed sequentially, so exceeding limits may result in queuing delays before the error appears. Wait before retrying.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Simplify grant applications to empower indie developers navigating complex government and NGO funding landscapes effectively.
23 languages
Any voice speaks any of these languages.
