VoicePilot TTS API Integration with OpenAI SDKs

By VoicePilot editorial team · Updated 2026-11-19

This guide helps product teams and developers integrate our text-to-speech API using official OpenAI SDKs. You will learn how to configure your base URL, manage authentication keys, and structure requests for our 8 licensed voices across 23 languages. The documentation covers all essential endpoints, from generating audio to retrieving voice details, ensuring a smooth setup for voice assistants and chatbot deployments.

We provide concrete examples in Python, JavaScript, and cURL to get you started quickly. You will find clear explanations of rate limits, response formats, and error handling specific to our infrastructure. By following this guide, you can efficiently switch your OpenAI client configuration to use our high-quality synthetic speech with minimal code changes.

VoicePilot TTS API Integration with OpenAI SDKs

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.mp3

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication and Keys

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.
Response Formats

Rate Limits and Performance

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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_url to https://api.tam300.info/v1
  • Use standard api_key from 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_KEY with your key
  • Set response_format to 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 Bearer token 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. LibriTTS-R corpus (OpenSLR 141)
  3. MDN: Web Speech API
  4. LibriVox public-domain audiobooks
  5. curl documentation
  6. FFmpeg documentation
  7. Node.js documentation
  8. OpenAI API reference: create speech
  9. TRON developer hub: TRC-20
  10. openai-python on GitHub
  11. W3C WAI: making audio and video accessible
  12. Creative Commons Attribution 4.0

More on this site