Comprehensive API Documentation for Text-to-Speech Integration

By VoxCraft editorial team · Updated 2026-11-18

This documentation provides the essential reference for integrating VoxCraft’ text-to-speech API into your applications. We designed this guide for indie developers and startups who need a reliable, straightforward API without enterprise overhead. You will find precise details on authentication, request parameters, and supported audio formats, ensuring a smooth integration process from the first line of code.

The API follows the standard OpenAI request shape, allowing you to use official SDKs by simply adjusting the base URL. We cover critical operational details such as rate limits, error handling, and character limits to help you build robust workflows. Whether you are generating short phrases or long-form audio, this guide ensures you understand exactly how the service behaves under load and how to manage your API keys effectively.

Comprehensive API Documentation for Text-to-Speech Integration

Frequently asked questions

How do I get an API key?

Navigate to /get-api-key/ and sign up using Google or an email and password. The dashboard displays your active API key, balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one. Each account is tied to the specific site domain.

Can I use the OpenAI Python SDK with this API?

Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDK by changing the base_url to https://api.play55kk.com/v1 and providing your site-specific key. This allows you to leverage existing OpenAI client libraries without writing custom HTTP handlers.

What is the maximum length of text I can send?

Each request supports up to 4096 characters of input text. For longer texts, you must split the content into chunks of this size. Generate audio for each chunk separately and then join the resulting audio files to create the final output. Spaces and punctuation count toward the character limit.

How do I set the language for the speech?

Include an optional language field with an ISO code in your request. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language is recommended for non-English Latin-script texts to ensure accurate pronunciation and synthesis quality.

What audio formats are available?

You can choose from mp3, wav, opus, flac, and pcm formats. Specify your preference using the response_format field in the request body. These formats cover various use cases, from web streaming to high-fidelity archival storage, allowing flexibility in how you handle the generated audio files.

How do I handle rate limits in my code?

The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so under load, they may queue. Implement exponential backoff or simple retry logic in your code to handle temporary delays or rate limit responses gracefully without dropping requests.

Is the API endpoint standard REST?

Yes. The endpoint is POST https://api.play55kk.com/v1/audio/speech. It accepts JSON bodies and returns audio files. Other endpoints like GET /v1/voices and GET /v1/models provide metadata. The structure mirrors standard RESTful conventions, making it easy to integrate with existing HTTP clients and libraries.

What happens if the API returns an error?

If synthesis fails, the charge is returned in full. You will receive an error response indicating the issue. Failed requests do not consume your character balance. Ensure your code checks for successful HTTP status codes and handles errors appropriately to maintain accurate billing records.

Do I need to install a specific library?

No. You can use any standard HTTP client or the official OpenAI SDK. There is no proprietary library required. Using the OpenAI SDK is convenient if you adjust the base_url, but plain HTTP requests work equally well. This keeps dependencies minimal and flexible for your project.

How do I pass the audio file to my frontend?

The API returns the complete audio binary in the response body, not a URL. Since synthesis is not real-time and does not support streaming, the entire file is ready before transmission begins. You can save this binary data to a temporary file or upload it to your storage to generate a URL. Then, pass that URL to your frontend for playback, ensuring your client handles the full file download rather than expecting a live stream.

Can I use the same key for multiple projects?

Yes. One active key per account serves multiple projects, sharing the 60 requests/minute limit and character balance. For isolated limits or billing, create separate accounts to gain distinct keys and rate limits. You can also issue a new key at any time, which immediately invalidates the previous one, allowing you to rotate credentials without downtime.

What is the speed parameter range?

The speed parameter accepts values between 0.25 and 4.0. This allows you to slow down or speed up the speech synthesis. Adjusting speed can help match specific pacing requirements for narrations, audiobooks, or interactive applications without needing post-processing audio tools.

Is SSML supported in the input text?

No, the API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. Input must be plain text, limited to 4096 characters per request. You cannot inject emotion tags or custom pauses via markup. Instead, control tone and pacing by selecting one of the eight voice presets, adjusting the speed parameter (0.25–4.0), and specifying the language ISO code.

How do I split long texts for generation?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the API. Collect the resulting audio files from each response and join them sequentially. While you can send multiple requests concurrently, the server processes them one after another, so under load a request may wait in a queue before synthesis begins.

First request

curl

curl https://api.play55kk.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.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.play55kk.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.play55kk.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
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

Authentication for the VoxCraft API relies on a simple Bearer token strategy. You must include your API key in the request header as Authorization: Bearer tts-.... This key authorizes all requests sent to the endpoint and is the sole credential for your account.

Bearer token authentication method

Include your key in the Authorization header of every POST request. The format is strictly Authorization: Bearer YOUR_API_KEY. Ensure no extra spaces or quotes surround the token value to avoid 401 Unauthorized errors.

One active key per account

Each account maintains a single active API key. You can view and manage this key on your dashboard at /get-api-key/. This design simplifies integration by removing the need to track multiple credential sets.

Revoke old keys instantly upon issuing new ones

When you generate a new key, the previous one becomes invalid immediately. There is no grace period. Ensure your application is updated with the new key before issuing the replacement to prevent service interruption.

  • Old key stops working instantly
  • No overlap period
  • Update application config immediately

Base Endpoint and SDK Usage

Sound wave illustration for: Base Endpoint and SDK Usage

The core synthesis endpoint accepts a POST request to https://api.play55kk.com/v1/audio/speech. You send a JSON body containing the text, voice model, and audio format preferences. The API processes the request and returns the generated audio file directly in the response body, allowing straightforward integration into your application workflow.

This API is fully compatible with the official OpenAI SDKs. By simply adjusting the configuration to point to our infrastructure, you can leverage existing client libraries without rewriting your integration logic. This ensures a smooth migration or initial setup for developers already familiar with the OpenAI speech endpoint structure.

POST /v1/audio/speech endpoint

Send your text payload to this specific path. The endpoint handles the conversion from text to audio, respecting the specified model and voice parameters. It returns the binary audio data or a JSON response depending on the format requested, ensuring your application receives the media file efficiently.

Compatible with official OpenAI SDKs

Use the standard OpenAI SDKs for Python, JavaScript, or other supported languages. The request shape matches the OpenAI speech endpoint exactly, meaning you do not need to learn a new API structure. This compatibility reduces development time and leverages familiar error handling and response parsing patterns.

Change base_url to https://api.play55kk.com/v1

Update your SDK client configuration to set the base URL to https://api.play55kk.com/v1. Ensure your authentication header uses your unique Bearer token. This single configuration change redirects all SDK calls to our infrastructure while maintaining the same request and response formats you expect from the OpenAI interface.

Base Endpoint and SDK Usage

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis parameters to define how text is converted into audio. The API accepts a model, input text, voice preset, and optional language code to control the output characteristics.

Model selection: tts-1 or tts-1-hd

Both tts-1 and tts-1-hd utilize the same underlying engine and incur identical pricing. The distinction lies solely in the audio quality preference, allowing you to choose between standard or high-definition output without affecting your costs or performance characteristics.

Input text limit of 4096 characters

Each request supports a maximum of 4096 characters in the input field. Spaces, punctuation, and special characters are counted toward this limit. For texts exceeding this length, split the content into chunks of 4096 characters, generate audio for each, and join the resulting files.

Voice preset and language code options

Select one of eight voice presets to define the tone and character of the speech. While the API can guess the language from the script (defaulting to English for Latin text), explicitly setting the language parameter via ISO code ensures accurate synthesis for non-English Latin-script text.

  • Female voices: aria, nova, luna, sage
  • Male voices: felix, milo, atlas, orion
  • Supported languages: 23 total, including English, Spanish, German, and Japanese
  • Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali

Response Formats and Audio

Sound wave illustration for: Response Formats and Audio

The API returns the generated audio file directly in the response body, eliminating the need for separate download steps. You can choose from MP3, WAV, Opus, FLAC, or PCM formats based on your storage and playback requirements. Each format serves a different use case, from web-optimized compression to archival-grade fidelity.

All synthesized audio files include an inaudible watermark that marks them as synthetic speech, ensuring clear identification of AI-generated content without affecting the listening experience.

Supported formats: MP3, WAV, Opus, FLAC, PCM

Select the format that best fits your application’s bandwidth and quality needs. MP3 offers compressed efficiency for web delivery, while WAV provides uncompressed audio for high-fidelity playback. FLAC is the only lossless format in the list, preserving exact audio data. Opus is a lossy compression format, ideal for efficient streaming. PCM provides raw, uncompressed data for immediate processing.

  • MP3: Compressed, widely supported
  • WAV: Uncompressed, high quality
  • Opus: Lossy, efficient streaming
  • FLAC: Lossless, archival quality
  • PCM: Raw, uncompressed data

Audio file returned in response body

The audio binary is embedded directly in the HTTP response body. This simplifies integration, as you do not need to manage temporary URLs or separate download requests. Simply parse the response stream to save or play the audio immediately.

Inaudible watermark on all generated files

Every generated audio file carries an inaudible watermark that marks it as synthetic speech. This metadata is embedded within the audio data itself, allowing for easy verification of AI-generated content without altering the audible quality or requiring external tools for detection.

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

Rate limits protect API stability by capping concurrent processing. Each API key is restricted to 60 requests per minute, ensuring consistent performance for standard workloads. This limit applies uniformly across all endpoints.

60 requests per minute per key

Once your account is funded, you can process up to 60 synthesis requests every minute. This capacity is sufficient for most batch generation tasks and real-time applications requiring moderate throughput.

  • Limit applies per API key, not per IP or account.

10 requests per minute before first top-up

New accounts starting with the free trial credit are limited to 10 requests per minute. This lower throttle helps manage load during the initial testing phase before a top-up is processed.

  • Applies only until the first successful USDT top-up is confirmed.

Queued processing during high load

Requests are processed sequentially. Under high load, synthesis may wait in a queue. Short phrases take a few seconds; long texts process at roughly real-time speed. Patience is required during peak usage.

Rate Limits and Throttling

Error Handling and Status Codes

Sound wave illustration for: Error Handling and Status Codes

The API returns standard HTTP status codes to indicate request outcomes. Use these codes to determine if a request succeeded or if client-side adjustments are needed for parameters like voice or format.

Standard HTTP error codes

Successful synthesis returns a 200 OK with the audio file. Other codes like 400 Bad Request or 401 Unauthorized indicate issues with your input or authentication. Check the response body for details on what went wrong.

Failed requests do not consume credits

If synthesis fails due to server errors or invalid inputs, the charge is returned in full. You are not billed for characters processed in failed requests, ensuring your balance accurately reflects successful generations.

Retry logic for temporary issues

During high load, requests may queue or return temporary errors. Implement exponential backoff in your client to handle 5xx errors gracefully. This ensures reliable delivery without overwhelming the service during peak usage times.

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

The cURL commands below demonstrate how to generate speech using the VoxCraft API. You can send a POST request to the endpoint with your authentication header and payload to receive raw audio data directly.

Basic cURL command example

Use the following command to send a simple request. Replace YOUR_API_KEY with your key from the dashboard. The command sends a POST request to the speech endpoint with a sample text and the Nova voice preset.

  • curl -X POST https://api.play55kk.com/v1/audio/speech \ \n -H "Authorization: Bearer YOUR_API_KEY" \ \n -H "Content-Type: application/json" \ \n -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}' \ \n -o output.mp3

Setting headers and body data

The request body is a JSON object containing the model, input text (up to 4096 characters), voice, and response_format. The Authorization header must include your Bearer token. Optional fields like speed (0.25–4.0) and language can be included to customize the output.

Parsing JSON response for audio URL

Unlike some APIs, this endpoint does not return a JSON object with a download URL. The response body contains the raw audio bytes directly. To save the file, redirect the output to a file as shown in the example, or write the binary data to disk in your script.

Quickstart with cURL

Code Examples with OpenAI SDK

Sound wave illustration for: Code Examples with OpenAI SDK

Leverage the official OpenAI SDKs by simply overriding the base URL to point at our API. This allows you to use familiar client libraries without rewriting your integration logic, ensuring a smooth transition for indie developers and startups.

The following snippets demonstrate how to configure the Python and JavaScript SDKs. By setting the base_url to https://api.play55kk.com/v1, you can utilize the same request shape as the standard speech endpoint.

Python SDK configuration snippet

Initialize the client with your API key and override the base URL to direct requests to our infrastructure. This setup ensures compatibility with the OpenAI SDK structure while using our TTS engine.

  • Install the official openai package.
  • Set base_url="https://api.play55kk.com/v1".
  • Pass your tts-... key via api_key.

JavaScript SDK configuration snippet

Configure the JavaScript client by providing the base URL and API key. This approach maintains the standard SDK interface while routing audio synthesis requests to our endpoints.

  • Import the OpenAI client library.
  • Pass baseURL in the constructor options.
  • Set apiKey to your secret key.

Base URL override implementation

The core integration step is redirecting the SDK's default endpoint. By changing the base URL to https://api.play55kk.com/v1, all subsequent calls like speech are routed correctly to our service.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. indie developers can build rapid prototypes to validate startup ideas without needing large teams or significant funding.

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. Node.js documentation
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. Tether (USDT)
  5. LibriTTS-R corpus (OpenSLR 141)
  6. openai-node on GitHub
  7. openai-python on GitHub
  8. Creative Commons Attribution 4.0
  9. IETF RFC 7845: Ogg Opus
  10. LibriVox public-domain audiobooks
  11. OpenAI API reference: create speech
  12. Python documentation

More on this site