Integrate Text-to-Speech into Your Games with QuestVoice

By QuestVoice editorial team · Updated 2026-11-18

This guide helps game studios and indie developers integrate QuestVoice’s text-to-speech API into their existing engine workflows. You will learn how to generate NPC dialogue and ambient narration quickly using standard HTTP requests or the OpenAI SDK. We cover authentication, request structures, voice selection, and error handling so you can start synthesizing audio without enterprise overhead.

Here you’ll find concrete examples for authenticating with your API key, sending your first request, and interpreting responses. We also explain rate limits, supported output formats, and data privacy practices specific to game development. Whether you are building a startup or scaling a title, this page provides the technical details you need to deploy synthetic speech efficiently.

Integrate Text-to-Speech into Your Games with QuestVoice

Frequently asked questions

What is the endpoint URL for the API?

The endpoint is POST https://api.playa555.com/v1/audio/speech. You send a JSON body containing the text, model, voice, and other parameters. This endpoint handles the synthesis request and returns the generated audio file directly in the response, allowing you to integrate speech generation into your game engine or backend services easily.

How do I pass the API key in requests?

Include your API key in the HTTP header as Authorization: Bearer tts-.... Each account has one active key. If you need to revoke access or rotate credentials, you can issue a new key at any time, which immediately invalidates the old one, ensuring your integration remains secure and controlled.

Can I use the OpenAI Python SDK with this API?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.playa555.com/v1. You can use the same request shape as the OpenAI speech endpoint. This allows you to leverage familiar SDK patterns and libraries while directing requests to our infrastructure without needing to write custom HTTP client code from scratch.

What is the maximum character limit per request?

Each request supports up to 4096 characters in the input field. If your NPC dialogue or narration exceeds this limit, you must split the text into smaller chunks. Generate audio for each part separately and then join the resulting audio files to create the final continuous speech asset for your game.

How do I specify a specific language?

Pass the optional language parameter with an ISO code, such as en or de. 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 explicitly to ensure correct pronunciation and avoid incorrect voice selection by the model.

What are the available response formats?

You can choose from mp3, wav, opus, flac, and pcm via the response_format field. Select the format that best fits your game engine’s audio pipeline. MP3 offers small file sizes, while WAV and FLAC provide lossless quality. PCM is useful for raw audio processing before encoding by your engine’s audio system.

How do I handle rate limit errors?

The limit is 60 requests per minute per key (10 before the first top-up). If you exceed this, implement exponential backoff in your code. Since requests are processed sequentially, under load your request may wait in a queue. Monitor your usage via the dashboard and adjust your generation batch sizes to stay within limits.

Can I generate audio faster than real-time?

Typical speed is roughly real-time, about 25 characters of text per second of generation. Short phrases may take a few seconds. Requests are processed one after another, so under load, a request may wait in a queue.

Do I need to split long texts manually?

Yes, you must split texts longer than 4096 characters yourself. Generate audio for each part separately using multiple API calls. Then, join the resulting audio files in your game engine or post-processing pipeline to create a continuous speech asset. This ensures each chunk stays within the single-request character limit defined by the API.

What happens if the API returns an error?

If synthesis fails, the charge is returned in full. You can retry the request or handle the error in your application logic. Failed requests do not consume your character balance. Check the response status code and message to determine if the issue is transient, such as a rate limit, or a configuration error.

Is the API key shared across all accounts?

No, each account has its own unique API key. Keys are specific to the account created on playa555.com. This ensures that usage, billing, and rate limits are tracked individually per account. You can manage keys independently for different projects or teams by creating separate accounts or rotating keys as needed.

Can I issue a new key if the old one is compromised?

Yes, you can issue a new key at any time from your dashboard. When you generate a new key, the old one stops working immediately. This allows you to quickly revoke access if a key is leaked or if you want to rotate credentials without downtime, ensuring your API usage remains secure.

How do I check available voices via API?

Use the GET /v1/voices endpoint to retrieve a list of available voices, languages, formats, and pricing. This endpoint provides the necessary metadata to configure your API calls correctly. You can also use GET /v1/models to check available models. This allows you to dynamically select voices based on your game’s requirements.

Is there a webhook for long generation jobs?

No, there is no webhook support. The API is synchronous; you send a request and wait for the audio file in the response. For long texts, you must split them into chunks and process them using multiple requests. Monitor your queue wait times if you experience delays under load.

First request

curl

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

QuestVoice provides a single API key for each account, issued through the /get-api-key/ dashboard. This key authenticates all requests to the TTS endpoint. You can generate or rotate keys instantly from the dashboard interface.

The API key is used as a Bearer token in the Authorization header of every request. Keep this key secure; it grants full access to your account’s usage and billing.

Generate your key from the dashboard

Access the /get-api-key/ page after signing in via Google or email. Your unique API key appears on this page alongside your current balance and usage statistics. You can issue a new key at any time without downtime.

  • Sign in via Google or email
  • View key, balance, and usage
  • Issue new key instantly

Use Bearer token in Authorization header

Include your key in the Authorization header as a Bearer token for every API call. The format is: Authorization: Bearer tts-... This ensures your requests are authenticated against your specific account.

Ensure the header is correctly formatted in your HTTP client or SDK. Mistyped keys will result in a 401 Unauthorized error.

  • Format: Authorization: Bearer tts-...
  • Required for all endpoints
  • Returns 401 if invalid

One active key per account at a time

Each account holds one active key. When you generate a new key from the dashboard, the previous key becomes invalid immediately. This ensures only one key is active at any given time.

This simplifies security management. If a key is compromised, you can revoke it instantly by generating a replacement from the dashboard.

  • Single active key per account
  • Old key invalidates immediately
  • Instant rotation via dashboard

First Request with cURL

Sound wave illustration for: First Request with cURL

Send a POST request to https://api.playa555.com/v1/audio/speech with your bearer token to generate NPC dialogue. The API returns an audio file directly, allowing you to integrate sound assets into your game engine seamlessly.

Basic JSON body structure

Construct your request body as a JSON object containing the model, input text, and voice selection. This simple structure mirrors the standard OpenAI speech endpoint, making it easy to drop into your existing codebase.

Required fields: model, input, voice

Specify model as "tts-1" or "tts-1-hd", both using the same engine. Provide your input text (up to 4096 characters) and select one of the eight voice presets, such as "aria" for narration or "felix" for energetic promos.

Optional fields: speed, language, format

Adjust speed between 0.25 and 4.0 for pacing control. Set language to an ISO code if the script differs from the default guess. Choose response_format from mp3, wav, opus, flac, or pcm to match your engine's requirements.

First Request with cURL

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

The QuestVoice API follows the same request shape as the OpenAI speech endpoint. By adjusting the base URL, you can leverage the official OpenAI SDKs without rewriting your integration logic. This allows game studios to drop TTS into their existing engine workflows with minimal code changes.

Set base_url to our API endpoint

Configure your SDK client to point to https://api.playa555.com/v1. This single change routes all standard TTS requests to our infrastructure while maintaining the familiar JSON structure you already use.

Use standard speech endpoint method

Call the standard speech method exactly as you would for OpenAI. The SDK handles the JSON payload construction for you, ensuring compatibility with our POST /v1/audio/speech endpoint.

Pass your API key as usual

Provide your unique key in the standard authorization header. The SDK injects the Bearer token automatically, allowing you to authenticate NPC dialogue generation just like any other service call.

Available Voices and Models

Sound wave illustration for: Available Voices and Models

QuestVoice offers two identical-engine models, tts-1 and tts-1-hd, which use the same engine and price. All eight voice presets deliver high-fidelity NPC dialogue and ambient narration suitable for game audio pipelines.

You can retrieve the full list of available voices, languages, and formats by calling the GET /v1/voices endpoint. This ensures your game client can dynamically select the perfect voice tone for any character or narrative context.

Two models: tts-1 and tts-1-hd

Both tts-1 and tts-1-hd use the same underlying engine and pricing. You can switch between them instantly by changing the model field in your request body, enabling easy A/B testing of audio quality for your game's specific audio budget.

Eight voice presets with distinct tones

Choose from four female voices (Aria, Nova, Luna, Sage) and four male voices (Felix, Milo, Atlas, Orion). Each preset offers a distinct character, from warm narrators to energetic promo styles, providing immediate variety for diverse NPC dialogues without complex voice design.

  • Female: Aria, Nova, Luna, Sage
  • Male: Felix, Milo, Atlas, Orion
  • All voices support 23 languages

List voices via GET /v1/voices endpoint

Use the GET /v1/voices endpoint to fetch real-time details on available voices, supported languages, and output formats. This allows your game to programmatically populate voice selection menus or verify compatibility before generating dialogue.

Response Formats and Speed

Sound wave illustration for: Response Formats and Speed

QuestVoice supports MP3, WAV, OPUS, FLAC, and PCM output formats via the response_format field, letting you choose the best balance of quality and file size for your game engine. MP3 offers efficient compression, while FLAC provides lossless audio.

MP3, WAV, OPUS, FLAC, PCM outputs

Select the format that best fits your pipeline. MP3 is ideal for web-based or mobile games where bandwidth matters. WAV and FLAC provide uncompressed clarity for local playback, while PCM offers raw data for custom processing.

  • MP3: Standard compression, small file size
  • WAV: Uncompressed, widely supported
  • OPUS: High efficiency
  • FLAC: Lossless compression
  • PCM: Raw audio data

Speed range from 0.25x to 4.0x

Adjust the speed parameter between 0.25 and 4.0 to match your game’s pacing. Slower speeds work well for ambient narration or emotional dialogues, while faster rates suit quick UI prompts or action sequences. This flexibility helps maintain immersion without re-recording.

Audio returned directly in response

The generated audio file is returned directly in the HTTP response body, allowing immediate integration into your game’s audio system. There is no need to poll for a download link or manage external storage for short-lived assets.

Response Formats and Speed

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

QuestVoice enforces a standard rate limit of 60 requests per minute per API key. This allows you to generate NPC dialogue lines or ambient narration efficiently without overwhelming the service. Requests are processed one after another, so under load a request may wait in a queue.

60 requests per minute per key

The standard limit of 60 requests per minute accommodates most indie projects. If you need higher throughput, you can issue a new API key to get a separate 60 requests per minute quota.

10 requests per minute initially

New accounts start with a lower limit of 10 requests per minute. This protects the infrastructure while you test integration. You can quickly increase this limit by adding funds to your balance.

Limit increases after first top-up

Once you make your first top-up via USDT (TRC-20), your rate limit automatically increases to the standard 60 requests per minute. Top-ups are credited within minutes, so you can resume high-volume generation almost immediately.

Handling Errors and Limits

Sound wave illustration for: Handling Errors and Limits

QuestVoice returns clear HTTP status codes to help you debug integration issues quickly. Understanding these responses ensures your game’s audio pipeline handles edge cases gracefully without crashing.

Rate limits protect service stability during peak usage. If you exceed the threshold, pause briefly and retry; failed requests do not consume your character credit.

429 status for rate limit exceeded

A 429 error indicates you have surpassed the allowed request rate. The limit is 60 requests per minute per key (10 per minute before the first top-up).

Include the Retry-After header value in your client logic to wait the specified duration before resuming requests. This prevents unnecessary retries during queue processing.

400 status for invalid input

This error occurs when the JSON body is malformed or missing required fields like model or input. Ensure your text does not exceed 4096 characters, as longer texts must be split and joined by your client.

Verify that the voice parameter matches one of the eight available presets and that response_format is one of mp3, wav, opus, flac, or pcm.

401 status for missing or bad key

A 401 response means the Authorization: Bearer tts-... header is missing or contains an invalid key. Ensure you are using the correct key from your dashboard.

Note that only one key is active per account at a time. If you issue a new key, the old one stops immediately, which may cause this error if your game cache still holds the old token.

Handling Errors and Limits

Data Privacy and Storage

Sound wave illustration for: Data Privacy and Storage

QuestVoice is built for studios that value player trust and clean pipelines. We do not use your input text to train our models, ensuring your dialogue scripts remain proprietary. Generated audio is returned directly in the response and is not stored on our servers after delivery.

We retain only request metadata—such as timestamp, character count, and status—for billing accuracy. This data is used solely to verify usage and process charges, keeping your creative assets and usage patterns private.

Input text not used for training

Your dialogue scripts, character lines, and narrative text are processed solely to generate the audio file. We do not ingest this text into our training datasets, meaning your unique storytelling remains yours. This ensures that your NPC voices and ambient narration are not repurposed for other customers or model improvements without your explicit consent.

This approach is particularly valuable for indie developers and studios who treat their script as a core intellectual property asset. You can generate thousands of lines without worrying about your content becoming part of our general model knowledge.

Audio not stored after generation

Once the audio file is delivered to your client or server, we do not keep a copy of the generated speech. This minimizes storage overhead and reduces the attack surface for potential data leaks. If you need to keep the audio, you store it in your own infrastructure.

This ephemeral nature of our storage means you are never billed for storage fees, only for the computation used to create the audio. It also simplifies data retention policies, as there is no long-term audio archive to manage.

Metadata kept for billing purposes

We store minimal metadata including the request timestamp, character count, and status code. This information is used strictly to calculate your usage-based charges and to troubleshoot any billing discrepancies. No audio content or input text is retained in these logs.

This metadata helps us ensure fair usage and helps you track your spending patterns. You can review this data in your dashboard to understand exactly how many characters were processed and when, providing full transparency for your studio's budget.

  • Timestamp of request
  • Character count processed
  • Request status (success/failed)

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Craft immersive game worlds where NPCs feel truly alive and responsive to player choices.

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 paper (arXiv 2305.18802)
  3. TRON developer hub: TRC-20
  4. openai-python on GitHub
  5. Python documentation
  6. curl documentation
  7. ISO 639 language codes
  8. OpenAI API reference: create speech
  9. IETF RFC 7845: Ogg Opus
  10. openai-node on GitHub
  11. LibriTTS-R corpus (OpenSLR 141)
  12. Creative Commons Attribution 4.0

More on this site