Frequently asked questions
Which SDKs are compatible with this API?
The API uses the same request shape as the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playgperya.com/v1 and providing your site key. Alternatively, you can use any standard HTTP client to send POST requests with the required JSON body.
Does the API support streaming audio chunks?
No. The API returns the complete audio file in the response body after synthesis is finished. There is no streaming, WebSocket, or real-time partial audio support. You must wait for the full response to receive the audio data, which may take time depending on text length and queue load.
How do I handle long dialogue scripts?
Split your text into parts of up to 4096 characters. Send each part as a separate request to the speech endpoint. Then, join the resulting audio files in your application. This ensures you stay within the character limit per request while delivering the full dialogue sequence.
What is the maximum input character count?
The maximum input is 4096 characters per request. This limit includes spaces and punctuation. If your script exceeds this length, you must split it into multiple requests. Each request is processed independently, so plan your splitting logic to maintain audio continuity between chunks.
Can I specify the language explicitly?
Yes. You can pass an optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language parameter to ensure accurate synthesis and avoid misinterpretation.
Is the API endpoint HTTPS only?
Yes. The API endpoint is https://api.playgperya.com/v1/audio/speech. All requests are sent over HTTPS. Authentication is handled via the Authorization header. This ensures secure transmission of your text and API keys during the synthesis process.
Do I need to install a specific library?
No. There is no official SDK or specific library required. You can use the official OpenAI SDKs by adjusting the base URL, or use any standard HTTP library. Plain HTTP requests work perfectly, giving you flexibility in your preferred programming language and environment.
How do I authenticate my requests?
Include an Authorization header with your API key. The format is: Authorization: Bearer tts-... . Each account has one active key. If you issue a new key, the old one stops immediately. Ensure your key is valid and has sufficient balance before sending requests.
What happens if the server is down?
There is no SLA or uptime guarantee. If synthesis fails, the charge is returned in full. Requests are processed sequentially, so under load, your request may wait in a queue. Typical speed is roughly real-time, but short phrases may take a few seconds to generate.
Is there a webhook for async processing?
No. The API does not support webhooks for async processing. You must make a synchronous request and wait for the response. The audio file is returned directly in the response body once synthesis is complete. There is no separate notification mechanism for completion.
Can I mix voices in a single response?
No. Each request accepts only one voice parameter. To use different voices, you must send separate requests for each voice segment. You will then need to join the resulting audio files in your application to create a continuous dialogue sequence with varied voices.
Does the API support SSML tags?
No. The API does not support SSML tags, phoneme dictionaries, or custom pronunciation lexicons. You can only control speed, voice, and language. For precise control, adjust the speed parameter or split text into separate requests for different voices or pacing.
How do I detect the language of the input text?
If you do not specify the language, the system guesses it from the script. Latin text defaults to English. For non-English Latin-script text, you should explicitly set the language parameter. This ensures accurate synthesis, as the system may otherwise default to English.
Is the audio file compressed or raw PCM?
You choose the format. Supported response formats are mp3, wav, opus, flac, and pcm. PCM is raw uncompressed audio. MP3 and Opus are compressed. WAV and FLAC are lossless. Select the format that best fits your game engine’s audio processing pipeline.
First request
curl
curl https://api.playgperya.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.playgperya.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.playgperya.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
Authenticate requests with a Bearer token in the Authorization header. Keys are issued per account and must be included in every API call to verify usage against your balance.
The token format is strictly Bearer tts-<your_key>. Ensure no extra whitespace or characters are included, as the API validates the string exactly as provided.
Bearer token format
Include the header Authorization: Bearer tts-123abc... in every request. The token is unique to your account and must remain secret to prevent unauthorized usage of your character credits.
Keys do not expire automatically but can be rotated instantly. The format always begins with tts- followed by alphanumeric characters.
- Header:
Authorization: Bearer tts-<key> - Format:
tts-prefix + alphanumeric string
Key rotation policy
You can issue a new key at any time via the dashboard. The previous key stops working immediately upon generation of the new one.
This allows instant revocation if a key is compromised. Only one active key exists per account at any given time.
Single active key per account
Each account is limited to one active API key. When you generate a replacement, the old key becomes invalid immediately.
This simplifies security management for game studios, ensuring no stale keys continue consuming characters in your project.
Speech endpoint
The core synthesis endpoint accepts text and returns audio files directly. It follows the standard OpenAI speech request shape, allowing you to use official OpenAI SDKs by simply adjusting the base_url to https://api.playgperya.com/v1. This ensures straightforward integration into your game’s audio pipeline without learning a proprietary protocol.
POST /v1/audio/speech
Send a POST request to https://api.playgperya.com/v1/audio/speech with your Bearer token in the Authorization header. The endpoint processes text input and returns the synthesized audio file in the response body.
JSON request body
Provide the text as the input field, limited to 4096 characters per request. Specify the model ("tts-1" or "tts-1-hd"), the desired voice preset, and the response_format. You can optionally set speed between 0.25 and 4.0, and define a language ISO code to ensure correct synthesis for non-English Latin script text.
- input: string (max 4096 chars)
- model: "tts-1" or "tts-1-hd"
- voice: one of 8 presets
- response_format: mp3, wav, opus, flac, pcm
- speed: 0.25–4.0
- language: optional ISO code
Audio response format
The API returns the raw audio file corresponding to your requested format. Each generated file contains an inaudible watermark marking it as synthetic speech, which helps identify NPC dialogue generated by the system. Failed requests return no audio and are free of charge.

Request parameters
Configure the synthesis engine and payload constraints before sending requests. Select the model, define the text input within strict limits, and choose a voice preset to determine the output characteristics.
Model selection (tts-1, tts-1-hd)
Use "tts-1" or "tts-1-hd" for the model field. Both presets use the same synthesis engine and incur identical pricing per character, allowing you to swap them without cost or format implications.
Input text limit
The input field accepts a maximum of 4096 characters per request. Spaces and punctuation count toward this limit. For longer dialogue lines, split the text into segments, synthesize each part, and join the resulting audio files.
Voice preset selection
Select one of eight presets (e.g., aria, nova, atlas) to define the NPC's vocal identity. Each voice supports all 23 languages; if the language parameter is omitted, the engine guesses the language from the script, defaulting to English for Latin text.
- 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 formats
The API returns audio in the format specified by the response_format field, defaulting to MP3. This format is universally compatible with game engines and standard audio players, ensuring seamless integration into your dialogue system without requiring additional conversion steps.
Choose WAV for lossless quality when file size is not a constraint. FLAC and Opus are available for efficient storage and streaming, offering high fidelity with significantly smaller file sizes compared to uncompressed options. Note that the API does not support streaming audio delivery; these formats are returned as complete files.
All generated files include an inaudible watermark to mark synthetic speech, which may need to be accounted for in your audio pipeline if strict raw audio is required for specific analysis tools.
MP3 compatibility
MP3 is the default and most widely supported format. It offers a good balance between quality and file size, making it ideal for most in-game dialogue assets.
Most game engines natively support MP3 playback, reducing the need for custom audio decoders or additional middleware dependencies in your project.
- Default format for all requests
- Universal playback support
- Optimal size-to-quality ratio
WAV lossless option
Select wav for uncompressed, lossless audio. This preserves the full fidelity of the synthesized speech, which is useful for post-processing or voice-over work where quality is paramount.
WAV files are larger than MP3 or Opus, so consider your storage limits and bandwidth constraints when choosing this format for large dialogue trees.
- Uncompressed audio
- Highest fidelity
- Larger file size
FLAC and Opus support
FLAC provides lossless compression, reducing file size without sacrificing audio quality. It is suitable for archival purposes or high-quality storage where bandwidth is a concern.
Opus offers excellent compression for streaming and real-time applications. It is ideal for dynamic dialogue systems where low latency and small packet sizes are critical for performance.
- Lossless compression with FLAC
- Efficient streaming with Opus
- Reduced bandwidth usage
OpenAI SDK integration
The API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDK clients with minimal changes. By adjusting the base URL and authentication header, you can integrate NPC Audio’s synthesis engine directly into your game’s audio pipeline without rewriting client logic.
This approach simplifies integration for developers already familiar with OpenAI’s Python or JavaScript libraries. You simply point the client to our API domain and use the standard speech method to generate NPC dialogue files.
Base URL configuration
Configure your SDK client to use https://api.playgperya.com/v1 as the base URL. This redirects requests to our synthesis endpoint while maintaining the standard OpenAI request shape.
Ensure your environment variables or configuration files update the base_url property before initializing any speech clients.
- Set base_url to https://api.playgperya.com/v1
- Use standard OpenAI SDK version 1.x or later
Client initialization
Initialize the client using your API key with the Authorization: Bearer tts-... header. The SDK handles header injection automatically when configured correctly.
Pass the key via the standard initialization parameter, ensuring it matches the active key issued to your account.
- Use
OPENAI_API_KEYor equivalent config variable - Ensure key starts with
tts-
Method compatibility
The speech method accepts model, input, voice, response_format, and speed parameters exactly as defined in the endpoint spec.
Since the request shape is identical, no parameter mapping is required. Responses return audio files directly, compatible with standard game audio engines.
- Supported methods: speech
- Unsupported: streaming, SSML, phonemes

cURL example
The API accepts standard JSON payloads via cURL. Send your NPC dialogue text directly to the speech endpoint for immediate synthesis.
Configure headers with your Bearer token and specify the desired output format. The response returns the binary audio stream.
This approach works for batch processing dialogue lines or quick integration tests without needing a full SDK.
Basic request structure
Send a POST request to /v1/audio/speech. Include the model, input text, and voice preset in the JSON body.
Example: `curl -X POST https://api.playgperya.com/v1/audio/speech -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Hello, traveler.", "voice": "atlas"}'`
Header configuration
Always include Authorization: Bearer tts-<your-key> in the request headers. This authenticates your account for character usage.
Set Content-Type: application/json to ensure the server correctly parses your text and voice parameters.
Audio output handling
The response contains the raw audio binary. Use > output.mp3 to save the file directly to your local drive.
For debugging, use -v to view headers. The audio format matches your response_format parameter, defaulting to mp3.
Error handling
API responses include standard HTTP status codes to indicate success or failure. A 200 OK response returns the audio binary, while 4xx errors indicate client-side issues such as missing authentication or malformed JSON. Server-side issues return 500 series codes.
HTTP status codes
Use the status code to determine next steps. 200 indicates successful synthesis. 400–499 errors require fixing the request body or headers. 500–599 errors are temporary; retry with exponential backoff.
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 429: Too Many Requests
- 500: Internal Server Error
Rate limit errors
The API enforces a limit of 60 requests per minute per key. If you exceed this, the server returns a 429 status code. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed.
- Standard limit: 60 req/min
- Initial limit: 10 req/min
- Error code: 429
Invalid input errors
Errors occur if the input text exceeds 4096 characters, the voice ID is invalid, or the JSON structure is malformed. Failed requests are free, so no charge is applied to your balance for these errors. Ensure the input field is a valid string within the character limit.
- Max text length: 4096 characters
- Free if synthesis fails
- Check JSON structure

Voices endpoint
The /v1/voices endpoint returns a JSON array of available voice presets, including metadata for each voice such as ID, gender, and supported languages. This allows your application to dynamically populate voice selection menus based on the current API state.
Each voice is backed by licensed recordings from LibriTTS-R (CC BY 4.0), from LibriVox public-domain audiobook readings. Every generated audio file contains an inaudible synthetic watermark for identification purposes.
GET /v1/voices
Send a GET request to /v1/voices with your Bearer token to retrieve the full list of available voice presets. The response includes voice IDs, names, gender labels, and supported language codes.
This endpoint is read-only and does not consume your character quota. Use it to verify voice availability before initiating speech synthesis requests.
- - GET https://api.playgperya.com/v1/voices
- - Returns JSON array of voice objects
- - Includes voice ID, name, gender, and languages
List available presets
The API provides eight distinct voice presets designed for consistent NPC dialogue delivery. Female voices include Aria (warm narrator), Nova (bright), Luna (soft storytelling), and Sage (calm instruction). Male options include Felix (energetic), Milo (conversational), Atlas (neutral news), and Orion (deep documentary).
Select the voice that best matches your character's archetype. All voices support the full range of 23 languages, allowing you to maintain consistent audio quality across diverse linguistic contexts.
- - 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
Language support details
The API supports 23 languages, including English, Spanish, French, German, Japanese, Korean, Chinese, and Arabic. Any voice can speak any of these supported languages, ensuring flexibility for multi-lingual game projects.
If the language field is omitted, the system guesses the language from the script (Latin text defaults to English). For non-English Latin-script text, explicitly set the language parameter to ensure accurate pronunciation. Languages like Vietnamese, Thai, and Ukrainian are not supported.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. The game developer hired a freelancer to voice the quirky NPCs in their new fantasy title.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- OpenAI API reference: create speech
- openai-node on GitHub
- curl documentation
- Creative Commons Attribution 4.0
- W3C WAI: making audio and video accessible
- LibriTTS-R paper (arXiv 2305.18802)
- FFmpeg documentation
- TRON developer hub: TRC-20
- openai-python on GitHub
- Node.js documentation
- LibriTTS-R corpus (OpenSLR 141)
