Cloud Text-to-Speech API: Endpoint, Voices & Quickstart

By NPC Audio editorial team · Updated 2026-11-18

This page documents the NPC Audio API for game developers integrating NPC dialogue. You will find the exact endpoint structure, required JSON parameters, and voice presets needed to synthesize speech directly into your game engine or middleware. The guide covers authentication, request formatting, and response handling for reliable deployment.

Use the provided cURL examples and OpenAI SDK compatibility notes to get your first audio file quickly. We cover model selection, speed adjustments, and supported audio formats like MP3 and WAV. This reference is designed for engineers who need precise control over synthesis parameters without unnecessary abstraction or proprietary SDKs.

Cloud Text-to-Speech API: Endpoint, Voices & Quickstart

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

Python (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
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

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

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

Speech endpoint

Request parameters

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

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

Sound wave illustration for: 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_KEY or 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
OpenAI SDK integration

cURL example

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

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

Voices endpoint

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

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. OpenAI API reference: create speech
  3. openai-node on GitHub
  4. curl documentation
  5. Creative Commons Attribution 4.0
  6. W3C WAI: making audio and video accessible
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. FFmpeg documentation
  9. TRON developer hub: TRC-20
  10. openai-python on GitHub
  11. Node.js documentation
  12. LibriTTS-R corpus (OpenSLR 141)

More on this site