Frequently asked questions
How do I get my API key?
Navigate to /get-api-key/ and sign up using Google or an email password. Your unique API key appears on the dashboard. Accounts created via email do not receive the free trial credit, while Google sign-ins receive $0.50 valid for seven days.
Is the API compatible with OpenAI SDK?
Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use official OpenAI SDKs by simply changing the base_url to https://api.tam300.info/v1. This allows you to leverage existing client libraries without needing our own SDK.
What is the base URL for the API?
The base URL is https://api.tam300.info/v1. Use this for all API calls, including the POST /v1/audio/speech endpoint for synthesis and GET /v1/voices for voice information. Ensure your SDK configuration points to this domain to correctly route your authentication and request payloads.
Can I use the same key for multiple projects?
Yes, each account has one active key that can be used across multiple projects. The rate limit of 60 requests per minute applies to the key itself, not individual projects. You can use this single key for your projects.
What happens if I lose my API key?
If you lose your key, you can issue a new one from the dashboard. The old key stops working immediately upon issuing the new one. This ensures that lost credentials cannot be used indefinitely. You can rotate keys at any time to maintain security.
How do I rotate my API key?
Go to the /get-api-key/ page and generate a new key. The previous key becomes invalid instantly. This immediate revocation prevents unauthorized access if a key was compromised. You can rotate keys as often as needed without any downtime or additional fees.
What is the maximum input length?
Each request supports up to 4096 characters of text. For longer texts, split the content into chunks of this size and join the resulting audio files. Spaces and punctuation count toward the character limit, so plan your splitting logic accordingly for large-scale deployments.
Does the API support SSML?
No, the API does not support SSML. It accepts plain text input for synthesis. If you need precise control over pronunciation or pauses, you must manage those details within your text input or post-process the audio. We do not offer phoneme dictionaries either.
Can I stream audio in real-time?
No, the API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response. Requests are processed sequentially, so long texts may take time. You must wait for the full file before playing it.
What formats are supported for output?
You can choose between mp3, wav, opus, flac, and pcm formats. Select the desired format using the response_format field in your request. Each format has different file sizes and quality characteristics, so choose based on your storage and bandwidth constraints for the generated audio.
How do I handle rate limits?
The limit is 60 requests per minute per key. Before your first top-up, this limit is 10 requests per minute. If you exceed the limit, requests may queue or fail. Monitor your usage via the dashboard and implement exponential backoff in your client logic.
What is the retry policy for failed requests?
Failed requests are free, and the charge is returned in full. You can retry failed requests without incurring additional costs. This allows you to implement robust retry logic in your application without worrying about wasting credits on transient errors or server-side synthesis failures.
Do I need to install a specific SDK?
No, you do not need a specific SDK. You can use the official OpenAI SDK by adjusting the base URL, or use plain HTTP requests. Any HTTP client capable of sending JSON and receiving binary data works. We do not provide a dedicated mobile SDK.
How do I authenticate requests?
Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... . Ensure the key is active and valid. The system validates this token for every request to your account. Keep your key secure and rotate it if compromised.
First request
curl
curl https://api.tam300.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.tam300.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.tam300.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 | |
|---|---|
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 and Keys
Access to the VoicePilot API requires a valid Bearer token. You can generate your key via the /get-api-key/ page using Google Sign-In or an email account. Each account maintains one active key at a time, ensuring clear audit trails for billing and usage monitoring.
Generate Your API Key
Navigate to the dashboard to create your credential. Google sign-up includes a $0.50 trial credit, while email accounts start with zero balance. Keys are displayed immediately after creation, ready for use in your integration scripts.
- Supported sign-up methods: Google OAuth or Email/Password
- Trial credit ($0.50) applied automatically for Google users
Bearer Token Format
Include your key in the HTTP header as Authorization: Bearer tts-<your-key>. This standard format ensures compatibility with the official OpenAI SDKs and any standard HTTP client. Ensure no extra spaces surround the token string.
Rotate Keys Instantly
You can issue a new key at any time from the dashboard. The previous key stops working immediately upon generation of the new one. This allows for zero-downtime rotation without managing multiple active credentials simultaneously.
Base URL and SDK Setup
VoicePilot’s TTS API is fully compatible with the official OpenAI SDKs, allowing you to reuse existing client code with minimal changes. By adjusting the base URL, your applications can seamlessly switch between OpenAI’s infrastructure and VoicePilot’s service without rewriting the core logic.
This approach simplifies integration for product teams already familiar with the OpenAI ecosystem. You can maintain a single codebase while leveraging VoicePilot’s specific voice presets and pricing structure, ensuring a smooth transition for large-scale deployments.
OpenAI SDK Compatibility
The API accepts the same JSON request body as the OpenAI Speech endpoint. This means you can use the official Python, Node.js, or other OpenAI SDKs directly. You only need to point the client to our API base URL instead of OpenAI's.
- Compatible with official OpenAI SDKs
- Same JSON request shape
- No custom client library needed
Changing the Base URL
Update your SDK configuration to point to https://api.tam300.info/v1. This single change redirects all speech synthesis requests to VoicePilot's servers. Ensure your environment variables or configuration files reflect this new base URL before running your application.
- Base URL: https://api.tam300.info/v1
- Update SDK configuration only
- Works with existing OpenAI SDK versions
Request Headers Configuration
Include your API key in the Authorization header using the Bearer scheme. The format is Authorization: Bearer tts-.... This key is generated on the /get-api-key/ page and must be kept secure. Ensure no other conflicting headers override the standard OpenAI format.
- Header: Authorization: Bearer tts-...
- Use the key from /get-api-key/
- Standard Bearer token format
API Endpoints
The API exposes three core endpoints to manage voice synthesis and configuration. The primary speech endpoint accepts text and parameters to generate audio files, while the metadata endpoints provide information about available voices and models without consuming credits.
POST /v1/audio/speech
Send text to generate audio files. This endpoint accepts JSON bodies with model, input, voice, and format parameters. It is the only endpoint that consumes your character balance, charging $0.01 per 1,000 characters used. Failed requests are refunded automatically.
GET /v1/voices
Retrieve a list of all available voices, their associated languages, and supported audio formats. This allows your application to dynamically populate voice selection menus without hardcoding preset names like 'aria' or 'atlas'.
GET /v1/models
Fetch the list of available models, specifically 'tts-1' and 'tts-1-hd'. Both models use the same engine and pricing, allowing you to verify model availability or update your integration configuration dynamically.
Request Parameters
The model parameter accepts either "tts-1" or "tts-1-hd". Both utilize the same underlying engine and incur identical pricing, so you can choose based on preference without affecting your budget or performance characteristics.
Text input is capped at 4,096 characters per request. For longer content, split your text into chunks of this limit and join the resulting audio files. Spaces and punctuation count toward this character limit.
Model Selection (tts-1 vs tts-1-hd)
Both tts-1 and tts-1-hd map to the same engine and price tier. Since there is no technical difference in output quality or processing speed between them, you may use either parameter value interchangeably for voice assistant and chatbot deployments.
Input Text Limits
Each API call accepts a maximum of 4,096 characters in the input field. If your script exceeds this, split the text into smaller segments and concatenate the returned audio files. All characters, including spaces and punctuation, are counted toward the limit.
- Maximum: 4,096 characters per request
- Spaces and punctuation count as characters
- Split and join for longer texts
Voice and Language Selection
Select one of 8 voices (e.g., aria, nova, felix) via the voice parameter. Each voice can speak any of the 23 supported languages. If the language field is omitted, the system guesses the language, defaulting to English for Latin script. Explicitly set the ISO code for non-English Latin texts to ensure accuracy.
- 8 voice presets available
- 23 supported languages
- Any voice supports any language
- Default language guess: English for Latin script
Response Formats
Select the response_format parameter to define the audio container your application receives. MP3 is the default, offering efficient compression for web delivery and standard playback across most voice assistant platforms.
MP3 Output
MP3 is the recommended format for general use, providing a balance between file size and audio quality. It is ideal for chatbots and voice assistants where bandwidth efficiency matters without sacrificing clarity for the end-user.
WAV for High Quality
Choose WAV when you need uncompressed, lossless audio for professional voiceovers or high-fidelity voice assistant responses. This format preserves the full quality of the TTS engine, ensuring the best possible sound for critical user interactions.
OPUS, FLAC, and PCM Options
OPUS provides excellent compression, while FLAC offers lossless quality. PCM returns raw, uncompressed audio data, suitable for immediate processing by other audio tools without decoding overhead.
- OPUS: Efficient for streaming and variable bandwidth.
- FLAC: Lossless compression, smaller than WAV.
- PCM: Raw audio data for immediate processing.

Rate Limits and Performance
Our API enforces a strict limit of 60 requests per minute per API key, ensuring fair usage across all developers. New accounts start with a lower threshold of 10 requests per minute until the first top-up is processed, helping you test integration stability without overwhelming the queue.
60 Requests Per Minute
Each active key allows up to 60 synthesis requests in a single minute. If you exceed this, subsequent requests will receive a 429 Too Many Requests error. This limit applies globally to your key, so distribute load carefully across your services.
- Standard limit: 60 requests/minute per key
- New account limit: 10 requests/minute
Queue Handling Under Load
Requests are processed sequentially during high traffic. If your application sends bursts of requests, they will wait in a queue until slots become available. This ensures consistent audio quality but may introduce slight delays during peak usage periods.
Real-Time Speed Expectations
Generation speed is roughly real-time on long texts (about 25 characters of text per second of generation); short phrases take a few seconds. Short phrases may take a few seconds to process due to initialization overhead. Plan your client-side buffering accordingly to maintain smooth playback for voice assistants.
Error Handling
When synthesis encounters an issue, the API returns a standard error JSON with a specific code and message. Understanding these codes helps you quickly identify whether the problem lies with your request structure, authentication, or quota limits. Most errors are immediate and self-correcting, allowing your application to retry or adjust parameters without human intervention.
Errors are distinct from rate limits. If you exceed 60 requests per minute, you receive a 429 status. Unlike other errors, this indicates a temporary capacity constraint rather than a malformed request. Your application should implement exponential backoff to handle these moments gracefully without disrupting the user experience.
Common Error Codes
The API uses standard HTTP status codes to indicate the nature of the failure. A 400 Bad Request typically means your JSON body is malformed or contains invalid characters. A 401 Unauthorized indicates an invalid or expired API key. A 429 Too Many Requests signals that you have exceeded the 60 requests per minute limit for your key.
- 400: Invalid JSON or missing required fields like 'model' or 'input'.
- 401: Invalid API key provided in the Authorization header.
- 429: Rate limit exceeded (60 requests/minute).
- 500: Internal server error; retry after a short delay.
Failed Request Refunds
If a synthesis request fails due to a server-side issue or an invalid response, the charge is returned in full. You are only billed for successfully generated audio files. This ensures that temporary network glitches or engine timeouts do not result in unnecessary costs for your account balance.
Debugging Tips
Start by verifying your API key format; it must begin with 'tts-'. Ensure your text input does not exceed 4096 characters, as larger texts must be split manually. Check that the voice ID exists in the /v1/voices list. If using the OpenAI SDK, confirm that the base_url points correctly to https://api.tam300.info/v1.
Code Examples
This section provides ready-to-use code snippets for integrating VoicePilot’s TTS API with common development tools. Use these examples to quickly generate speech from text in your applications, ensuring correct authentication and parameter structure.
All examples assume the OpenAI SDK or standard HTTP libraries. Replace YOUR_API_KEY with your key from the dashboard. The base URL is https://api.tam300.info/v1. These snippets cover Python, cURL, and JavaScript to help you start testing immediately.
Python SDK Example
Install the OpenAI SDK and configure the base URL to point to VoicePilot. Use the tts-1 or tts-1-hd model with your chosen voice and language code.
```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["VOICEPILOT_API_KEY"], base_url="https://api.tam300.info/v1" ) speech_file = client.audio.speech.create( model="tts-1", voice="nova", input="Hello, this is a test of VoicePilot's API.", response_format="mp3" ) speech_file.write_to_file("output.mp3") ```
- Set
base_urltohttps://api.tam300.info/v1 - Use standard
api_keyfrom your dashboard - Supports all 8 voices and 23 languages
cURL Command Line
Use cURL for quick testing or scripting. Send a POST request with your text and voice selection. The API returns the audio file directly.
```bash curl https://api.tam300.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "voice": "aria", "input": "Hello from cURL", "response_format": "wav"}' \ -o speech.wav ```
- Replace
YOUR_API_KEYwith your key - Set
response_formatto mp3, wav, opus, flac, or pcm - Text is limited to 4096 characters
JavaScript Fetch Example
Use the native fetch API to send requests. This example demonstrates a simple POST request to generate speech. Handle the response blob to save the audio file.
```javascript const response = await fetch("https://api.tam300.info/v1/audio/speech", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ model: "tts-1", voice: "nova", input: "Hello from JavaScript", response_format: "mp3" }) }); const audioBlob = await response.blob(); // Save audioBlob to file or play it ```
- Use
Bearertoken for authentication - Supports JSON body for all parameters
- Returns audio as a Blob for easy handling
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Your voice is often the first touchpoint for users, so it must align with your product’s personality while remaining intelligible across diverse contexts.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R corpus (OpenSLR 141)
- MDN: Web Speech API
- LibriVox public-domain audiobooks
- curl documentation
- FFmpeg documentation
- Node.js documentation
- OpenAI API reference: create speech
- TRON developer hub: TRC-20
- openai-python on GitHub
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
