Quickstart: Generate NPC Voices with Our API

By VoxQuest editorial team · Updated 2026-11-19

This guide helps freelance game developers integrate synthetic NPC dialogue quickly. You will learn how to generate audio files for characters using simple HTTP requests, compatible with tools you already use. We provide clear presets and transparent pricing so you can focus on game design rather than voice actor negotiations.

You will see exactly which voices fit different character types and how to handle language detection. The guide covers basic cURL examples, OpenAI SDK integration, and practical tips for managing rate limits and errors. By the end, you will have a working endpoint for your game’s audio pipeline.

Quickstart: Generate NPC Voices with Our API

Frequently asked questions

What is the endpoint URL?

Send your POST request to https://api.playmm9.com/v1/audio/speech. Use the standard JSON body with fields like model, input, voice, and response_format. This endpoint accepts text up to 4096 characters and returns the generated audio file directly in the response.

Do I need an SDK to use the API?

No. The API follows the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.playmm9.com/v1 and providing your API key. Plain HTTP requests work just as well.

How do I handle long dialogue text?

Split your text into parts of up to 4096 characters per request. Generate audio for each part individually, then join the resulting audio files to create the final NPC dialogue track. This ensures compatibility with the single-request character limit.

Can I stream audio as it generates?

No streaming or WebSocket support exists. Requests are processed sequentially, so you must wait for the full audio file to be generated and returned in the response before playing it. Short phrases may take a few seconds to complete.

What is the maximum text length?

Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer dialogue lines, you must split the text into multiple chunks and generate separate audio files for each chunk.

Do I need to set the language field?

It is optional. The system guesses the language from the script, defaulting to English for Latin text. However, for non-English Latin-script text, you should explicitly set the language field to ensure accurate synthesis from the 23 supported languages.

Are the voices copyrighted?

Voices are based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings. Every generated file carries an inaudible watermark marking it as synthetic speech, ensuring clear attribution and usage rights for your game projects.

How do I split audio for long texts?

Divide your input text into segments of 4096 characters or fewer. Send each segment as a separate POST request to the speech endpoint. Once you receive all audio files, concatenate them in order to produce the complete dialogue audio.

What happens if I hit the rate limit?

You are limited to 60 requests per minute per key. If you exceed this, requests may wait in a queue. New accounts start with a 10 requests per minute limit until the first top-up is processed. Requests are processed sequentially.

Is there a WebSocket endpoint?

No. There is no WebSocket endpoint for real-time partial audio. You must use the standard POST endpoint to receive the complete audio file. Streaming is not supported, so you must wait for the full synthesis to finish.

Can I use the API in a mobile app?

Yes, you can use the API in a mobile app via HTTP requests. There is no dedicated mobile SDK, but the standard OpenAI SDK or any HTTP client works. Ensure you manage your API key securely within your mobile environment.

How do I rotate my API key?

You can issue a new API key at any time from your account dashboard. The new key becomes active immediately, and the old key stops working at once. This allows for seamless key rotation without downtime for your integration.

What formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format in the response_format field of your request. This allows you to choose the best balance between file size and quality for your game engine.

Do I need to pay for failed requests?

No. If synthesis fails, the charge is returned in full. You only pay for successful requests. This ensures you are not charged for audio that was not generated correctly, keeping your development costs predictable and fair.

First request

curl

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

Get Your API Key

Sound wave illustration for: Get Your API Key

Visit /get-api-key/ to create your account using Google or email. You receive a single active API key immediately, along with your balance and usage stats. This key authenticates all requests to the API base URL.

Sign Up on the Portal

Sign Up on the Portal

Start by signing up on the portal. Accounts are per site, so ensure you are on playmm9.com. Google sign-in includes a $0.50 free trial valid for 7 days, giving you about 50,000 characters to test your first NPC lines.

Locate Your Key

Locate Your Key

Your unique key appears on the dashboard alongside your current balance and character count. Use this key in the Authorization: Bearer header for every API call. Keep it secure, as it is your only credential.

  • Key format: tts-...
  • Starts with tts-

Rotate Keys Securely

You can issue a new key at any time from the dashboard. When you generate a new key, the old one stops working immediately. This is useful if you suspect a key has been exposed in your game client.

First cURL Request

Sound wave illustration for: First cURL Request

Generate NPC dialogue by sending a POST request to the speech endpoint. This method returns an audio file directly, allowing you to download and integrate voices into your game engine without managing complex streaming pipelines.

You need to provide your API key in the Authorization header and specify the model, voice, and input text. The API handles the synthesis and returns the binary audio data.

Basic POST Request ['Send a POST request to https://api.playmm9.com/v1/audio/speech. Include your Bearer token in the header and the JSON payload in the body. This simple structure works with standard HTTP clients.', {'h3': 'Required Fields', 'paras': ['The model field accepts "tts-1" or "tts-1-hd". The input field contains your NPC dialogue text, limited to 4096 characters. Set the voice to one of the eight presets, such as "aria" or "atlas". Specify response_format like "mp3" or "wav". Optionally, set speed between 0.25 and 4.0.', 'bullets']}, {'h3': 'Response Format', 'paras': ["The API returns the audio file directly in the response body. The content type matches your requested format, such as audio/mpeg for MP3. You can save this response directly to a file in your project's assets folder.", 'bullets']}] A developer's dual-monitor setup showing a code editor with a curl command on one screen and a 3D game character model on the other, with a simple audio waveform graphic floating between them, clean and modern

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Integrating VoxQuest into your game’s audio pipeline is straightforward if you’re already familiar with the OpenAI Python or Node.js SDKs. Since our API mirrors the standard speech endpoint structure, you don’t need to learn a new library from scratch. The only adjustment required is pointing the SDK to our specific API base URL.

This approach allows you to maintain clean, standard code while leveraging our affordable, non-copyrighted NPC voices. You simply update the base URL configuration in your SDK client, and all other method calls remain identical to the standard OpenAI implementation.

Change base_url

Locate your API key on the /get-api-key/ portal. Update your SDK client’s base_url configuration to https://api.playmm9.com/v1. This single change directs all requests to our infrastructure while keeping the familiar request shape.

Ensure you include the Authorization: Bearer <your-key> header. The SDK will handle the header injection automatically if configured correctly.

  • Set base_url to https://api.playmm9.com/v1
  • Use your unique tts-... key from the dashboard

Use Official SDKs

You can use the official OpenAI SDKs for Python or Node.js. Pass your parameters (model, voice, input, response_format) exactly as you would for the standard speech endpoint.

The SDK handles the JSON serialization and HTTP transmission, allowing you to focus on integrating the audio into your game engine’s audio mixer or file system.

  • Python: openai.OpenAI(base_url="https://api.playmm9.com/v1", api_key="tts-...")
  • Node.js: new OpenAI({ baseURL: 'https://api.playmm9.com/v1', apiKey: 'tts-...' })

Audio File Response

Upon successful synthesis, the SDK returns a binary audio stream or a file object, depending on your language binding. This audio data corresponds directly to the NPC dialogue text you submitted.

Save the returned binary data to your project’s assets folder. Since each request generates a unique file, you can cache these assets to avoid redundant API calls for repeated dialogue lines.

Supported Voices

Sound wave illustration for: Supported Voices

VoxQuest provides eight distinct voice presets, each crafted from licensed LibriTTS-R recordings. These voices cover a wide range of NPC archetypes, from warm narrators to energetic promo speakers, ensuring your characters have unique, consistent personalities without the legal headaches of traditional voice acting.

List of 8 Presets

Our library includes four female and four male voices, designed for clear speech in game dialogue. Each voice offers a specific tonal character to help define your NPCs instantly.

  • 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

Gender and Tone Variations

The voices are based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings. Every generated file carries an inaudible watermark marking it as synthetic speech, protecting your project from copyright claims.

Voice Selection Logic

Any voice can speak any of the 23 supported languages. You select the voice that best matches your character’s role, regardless of the language spoken. For example, use Atlas for neutral news updates or Orion for deep documentary-style lore.

Remember that voices are static presets; we do not offer custom voice cloning or emotion tags. Choose the preset that closest matches your desired NPC persona.

Audio Formats

Sound wave illustration for: Audio Formats

Choose your output format based on your game engine’s requirements and target platform. MP3 offers a balance of file size and quality for web-based games, while WAV provides uncompressed clarity for high-fidelity audio pipelines.

MP3 for Web

MP3 is ideal for browser-based games or mobile apps where storage and bandwidth matter. It keeps file sizes small while maintaining clear voice quality for NPC dialogue.

WAV for High Quality

Use WAV when you need lossless audio for professional-grade sound design or when your engine prefers uncompressed formats. It ensures no data loss during processing.

OPUS and FLAC Options

OPUS provides efficient compression for streaming or low-bandwidth scenarios, while FLAC offers lossless compression for archiving or high-end audio workflows without increasing file size significantly.

  • MP3: Suitable for web and mobile.
  • WAV: Uncompressed, high fidelity.
  • OPUS: Efficient for low-bandwidth scenarios.
  • FLAC: Lossless compression.
Audio Formats

Rate Limits

Sound wave illustration for: Rate Limits

VoxQuest enforces a global limit of 60 requests per minute per API key. This cap applies to all endpoints and ensures fair usage for freelance developers generating NPC dialogue batches.

60 Requests Per Minute

Before the first top-up, the rate limit is 10 requests per minute. Once you top up with USDT, the limit instantly returns to 60 requests per minute.

10 Requests Before Top-Up

Requests are processed sequentially. Under heavy load, your request may wait in a queue behind others. This ensures stability but means generation time varies based on current server traffic.

Queue Handling

Each request processes one text segment. For long dialogues, split your text into chunks of 4096 characters. The API returns each audio file independently, allowing you to stitch them later in your game engine.

Error Handling

Sound wave illustration for: Error Handling

API responses include standard HTTP codes to indicate success or failure. If synthesis fails, the charge is returned in full, ensuring you only pay for completed audio files.

Common Error Codes

Use 401 for invalid keys, 429 for rate limits, and 422 for invalid parameters like unsupported voices or text exceeding 4096 characters.

Retry Logic

Implement exponential backoff for 429 errors. Since requests are processed sequentially, waiting briefly prevents queue congestion.

  • Retry after 1 second, then 2, then 4 seconds for 429 errors.

Debugging Tips

Check the input length and ensure the text uses supported languages. Verify your Authorization header matches the key from your portal.

Language Settings

Sound wave illustration for: Language Settings

Choose your NPC's language automatically or specify it explicitly. The API guesses the language from the text script, defaulting to English for Latin characters, but manual control ensures accuracy for mixed scripts or less common languages.

Auto-Detection

Set the language field to null or omit it entirely. The engine analyzes the input text to determine the appropriate voice model. This works well for standard English, French, or German text, but may misidentify similar Latin-script languages.

Manual Language Code

Pass the ISO 639-1 language code (e.g., "ja" for Japanese, "es" for Spanish) in the request body. This forces the engine to use the correct phonetics and intonation, preventing accidental English pronunciation for non-English lines.

  • Use standard two-letter codes.
  • Applies to all 23 supported languages.
  • Overrides auto-detection logic.

Unsupported Languages

The API does not support Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali, or any language outside the listed 23. If you send text in an unsupported language, the engine will default to English pronunciation, which may sound unnatural for your NPCs.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This preset is excellent for tutorial systems, helping new users understand controls or rules with a friendly, approachable demeanor.

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. Creative Commons Attribution 4.0
  3. OpenAI API reference: create speech
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. W3C WAI: making audio and video accessible
  6. openai-node on GitHub
  7. FFmpeg documentation
  8. TRON developer hub: TRC-20
  9. Tether (USDT)
  10. IETF RFC 7845: Ogg Opus
  11. openai-python on GitHub
  12. LibriVox public-domain audiobooks

More on this site