Frequently asked questions
How do I get an API key?
Sign up at /get-api-key/ using Google or email and password. You receive one active key per account, displayed on the dashboard alongside your balance and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one.
What is the request format?
Send a POST request to /v1/audio/speech with a JSON body. Include the model, input text (up to 4096 characters), voice preset, response format, and optional speed or language parameters. The endpoint accepts standard JSON payloads for synchronous audio generation.
Does it work with OpenAI SDK?
Yes. The endpoint matches the OpenAI speech shape. Configure your OpenAI SDK’s base_url to https://api.play33ok.com/v1 and use your EchoQuest key. This allows you to use official OpenAI SDKs directly without writing custom HTTP clients for basic integration.
What models are available?
Two models exist: tts-1 and tts-1-hd. Both use the same engine and pricing structure. Select either based on your quality preference, as the underlying synthesis technology remains identical regardless of which model identifier you pass in the request payload.
How do I set the language?
Pass the optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures correct pronunciation for non-English texts, especially those using Latin characters.
Can I change speed?
Yes, adjust the speed parameter between 0.25 and 4.0. This allows you to speed up or slow down the narration to fit your game’s pacing. If you omit the speed field, the API uses a neutral default pace.
What if the request fails?
Failed requests are free. If synthesis fails, the charge is returned in full. You can retry the request without worrying about extra costs for unsuccessful attempts.
How do I handle long texts?
Split texts into parts of up to 4096 characters per request. Generate audio for each part individually, then join the resulting audio files in your pipeline. This ensures each segment stays within the character limit while maintaining consistent voice and quality.
Is there a WebSocket endpoint?
No. We do not offer streaming, WebSocket, or real-time partial audio. Requests are processed synchronously, and you receive the complete audio file upon completion. This fits standard game audio pipelines where assets are generated and cached rather than streamed live.
Do I need a custom SDK?
No. You can use the official OpenAI SDK by changing the base URL, or use plain HTTP requests. There is no proprietary EchoQuest SDK required. This flexibility allows you to integrate with your existing tools using standard libraries you already know.
How do I authenticate?
Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... . Each account has one active key. If you rotate the key, the old one stops immediately, so ensure your integration updates promptly to avoid auth errors.
What happens if I exceed limits?
The rate limit is 60 requests per minute per key (10 per minute before the first top-up). Exceeding this may cause requests to queue or fail. Monitor your usage via the dashboard to stay within limits and ensure smooth generation during peak loads.
Can I use FLAC format?
Yes. Supported response formats include mp3, wav, opus, flac, and pcm. FLAC provides lossless audio quality suitable for high-fidelity game assets. Select your preferred format in the request body based on your storage and playback requirements.
Is SSML supported?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You control pacing via the speed parameter and voice selection. For precise control, split your text into smaller segments and adjust parameters for each segment individually.
First request
curl
curl https://api.play33ok.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.play33ok.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.play33ok.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
Authentication is handled via a Bearer token passed in the Authorization header. Use your unique API key to authorize requests sent to the endpoint.
Each account holds one active key. You can rotate this key at any time; the old key stops working immediately upon issuance.
Bearer token in header
Include your key in every request header: Authorization: Bearer tts-.... This token authenticates your account against the API.
The key is generated on the /get-api-key/ dashboard and remains valid until you choose to replace it.
- Header format:
Authorization: Bearer <your_key> - Prefix:
tts-
One active key per account
Only one key is active at any given time for your account. If you generate a new key, the previous one becomes invalid immediately.
This ensures that if a key is compromised, you can revoke access instantly without waiting for a batch update.
- Single active key model
- Instant invalidation of old keys
Rotate keys anytime
You can issue a new key from your dashboard at any time. This is useful for security audits or after potential exposure.
The transition is seamless: the new key works immediately, and the old one stops working at once. No downtime for your game builds.
- Rotate via dashboard
- Old key stops immediately
Endpoint
Send your NPC dialogue text to the speech endpoint. The API returns a synthesized audio file ready for integration into your game engine. This single endpoint handles all generation requests.
POST /v1/audio/speech
Use the POST method to submit your request. The base URL is https://api.play33ok.com/v1. Append /audio/speech to the endpoint path for synthesis.
JSON request body
Pass parameters as a JSON object. Include the model type, input text, voice preset, and desired audio format. The input text must not exceed 4096 characters per request.
- model: "tts-1" or "tts-1-hd"
- input: your dialogue string
- voice: one of 8 presets
- response_format: mp3, wav, opus, flac, or pcm
OpenAI SDK compatible
The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.play33ok.com/v1 and providing your site-specific API key.
Parameters
The API accepts two model variants: tts-1 and tts-1-hd. Both run on the same engine with identical pricing and capabilities. Choose tts-1-hd for higher fidelity in cutscenes or tts-1 for bulk NPC dialogue where file size matters.
model: tts-1 or tts-1-hd
Select the model via the model field in your JSON payload. Both options deliver the same voice quality and character limit, allowing you to switch based on your audio pipeline needs without changing code logic.
input: text up to 4096 chars
Pass your dialogue script in the input field. The API accepts up to 4096 characters per request, including spaces and punctuation. For longer dialogues, split the text into chunks and concatenate the resulting audio files.
- Maximum length: 4096 characters per request.
- Spaces and punctuation count toward the limit.
- Split long texts and join audio files manually.
voice: one of 8 presets
Assign a voice using the voice parameter. Choose from eight licensed presets ranging from warm narrators to energetic promo styles. Each voice supports all 23 supported languages, allowing consistent character voices across localized builds.
- 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
Audio Formats
The API supports five audio formats: mp3, wav, opus, flac, and pcm. This flexibility allows you to choose the best codec for your game engine’s audio pipeline, balancing file size and quality for NPC dialogue assets.
Each format serves a specific use case within your workflow, from compressed delivery to uncompressed editing.
mp3, wav, opus, flac, pcm
Select the output format that matches your engine’s requirements. MP3 offers efficient compression for web or mobile builds. WAV and FLAC provide lossless quality for high-fidelity PC games. PCM is raw data for custom decoders. Opus is an efficient format suitable for interactive dialogue systems.
- mp3: Compressed, small file size
- wav: Uncompressed, standard compatibility
- opus: Low latency, efficient
- flac: Lossless compression
- pcm: Raw audio data
Choose based on pipeline
Match the format to your asset pipeline. Use uncompressed formats like WAV or PCM if you plan to process audio further in your DAW or engine. Choose MP3 or Opus for direct integration where storage and bandwidth matter. FLAC is ideal if you need lossless quality with smaller files than WAV.
Default format settings
This ensures consistent behavior without additional configuration. You can override this by setting the response_format field in your request body.
- Default: mp3
- Override via response_format
Speed Control
Speed control allows you to adjust the generation rate from 0.25x to 4.0x, giving you precise command over NPC dialogue pacing. This feature is essential for synchronizing voice lines with animation cycles or adjusting the urgency of combat commands without re-recording.
Range 0.25 to 4.0
Set the speed parameter in your request body to any float value between 0.25 and 4.0. Values below 1.0 slow the delivery, while values above 1.0 accelerate it. This range covers everything from slow, deliberate exposition to rapid-fire combat alerts.
Adjust NPC dialogue pace
Use slower speeds for emotional monologues or tutorial instructions to ensure clarity. Increase speed for background chatter or urgent battle cues to match high-action scenes. The engine maintains natural intonation across the entire range, ensuring the voice remains consistent regardless of tempo.
Default speed setting
If you omit the speed field, the API uses a neutral default pace. This is suitable for standard dialogue where timing is not critical. Explicitly setting speed ensures predictable output duration, which helps in estimating generation time and synchronizing with game engines.

Language Handling
Language detection is automatic for Latin script text, defaulting to English. For non-English Latin-script content, you must explicitly set the language parameter to ensure correct pronunciation.
Optional ISO code
Set the language field to an ISO 639-1 code (e.g., de, fr, ja). This overrides auto-detection and ensures the engine uses the correct voice model for the target language.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Auto-detect for Latin
If language is omitted, the system guesses from the script. Latin script defaults to English. This works well for English NPC dialogue but may mispronounce other Latin-based languages.
Explicit set for non-English
Always specify the language for non-English Latin text (e.g., language: 'es' for Spanish). Any voice can speak any of the 23 supported languages.
Rate Limits
Your API key supports a maximum throughput of 60 requests per minute. This limit applies globally to all endpoints under your account, ensuring fair usage during peak integration phases. Exceeding this threshold triggers a 429 Too Many Requests response until the window resets.
60 requests per minute
The standard rate limit allows 60 requests per minute for established accounts. This capacity allows for bulk generation of NPC dialogue lines.
10 req/min before top-up
New accounts without a top-up start with a reduced limit of 10 requests per minute. This lower tier helps prevent resource exhaustion during the trial phase or initial testing.
Queue handling
Requests are processed one after another, so under load a request may wait in a queue. If your input exceeds the generation capacity, additional requests enter a queue. Longer texts may take several seconds, so implement exponential backoff in your client to handle transient delays gracefully.
- Implement retry logic with jitter for 429 responses
- Monitor usage via the dashboard
- Top-up immediately to raise the limit
Error Handling
The API returns standard HTTP status codes to indicate request success or failure. Common responses include 200 for successful synthesis, 400 for invalid parameters, 401 for authentication errors, and 429 when rate limits are exceeded. These codes allow your game’s audio manager to handle errors programmatically without guessing the cause of a missing audio file.
Every request is billed only when synthesis completes successfully. If the server returns an error (4xx or 5xx), no characters are deducted from your balance. This ensures you never pay for audio that was not delivered, simplifying cost tracking for your production pipeline.
Standard HTTP errors
Use the HTTP status code to determine the next step in your integration logic. A 400 error usually indicates a malformed JSON body or an unsupported voice ID. A 401 error means your API key is invalid or expired. A 429 error indicates you have exceeded the 60 requests per minute limit.
For 500-level errors, the service experienced a temporary issue. Since failed requests are free, you can safely retry the same request without worrying about double-charging your account.
- 400: Bad Request - Check JSON structure and voice ID
- 401: Unauthorized - Verify your Bearer token
- 429: Too Many Requests - Wait before retrying
- 500: Internal Server Error - Retry with exponential backoff
Retry logic
Implement exponential backoff for transient failures (5xx errors) to avoid overwhelming the server during high load. Start with a short delay and increase it progressively with each retry attempt. This is crucial for maintaining stable audio delivery in real-time game loops.
Since requests are processed sequentially, under heavy load a request may wait in a queue. If you receive a 429 error, wait at least one minute before retrying. Retrying immediately after a 429 error is likely to fail again.
- Retry 5xx errors with exponential backoff
- Wait 60 seconds after a 429 error
- No character deduction on failed retries
Failed requests are free
If synthesis fails for any reason, the request is not charged. This applies to both client-side errors (like invalid input) and server-side failures. You can rely on this behavior to build robust error handling without complex billing logic.
This policy extends to retries. If you retry a failed request and it succeeds, you are charged only for the successful attempt. If the retry also fails, no charge is applied. This ensures you only pay for usable audio assets.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- TRON developer hub: TRC-20
- Node.js documentation
- MDN: Web Speech API
- IETF RFC 7845: Ogg Opus
- OpenAI API reference: create speech
- LibriTTS-R paper (arXiv 2305.18802)
- openai-python on GitHub
- openai-node on GitHub
- LibriTTS-R corpus (OpenSLR 141)
- Python documentation
- W3C WAI: making audio and video accessible
