Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playak56.com/v1. You send POST requests to /v1/audio/speech for synthesis. Other endpoints include GET /v1/voices for voice details and GET /v1/models. This structure matches the OpenAI speech endpoint, allowing easy integration with existing tools by simply updating the base URL configuration.
How do I set the API key in the header?
Include your key in the Authorization header using the Bearer scheme. The format is: Authorization: Bearer tts-... Your key is issued per account and can be retrieved from your dashboard. Ensure you use the active key associated with your account to authenticate your requests successfully.
Can I use the OpenAI Python SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.playak56.com/v1. Use your SavorVoice key instead of an OpenAI key. The request shape is identical to the OpenAI speech endpoint, allowing you to leverage existing code with minimal configuration changes.
What is the maximum character limit per request?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of 4096 characters or less. Generate audio for each chunk separately and join the resulting audio files to create the final output.
Does the API support streaming audio?
No, the API does not support streaming, WebSocket, or real-time partial audio. You receive the complete audio file in the response after synthesis finishes. This synchronous approach simplifies implementation for batch processing or standard menu audio generation.
How do I specify the language?
Include the optional 'language' field with an ISO code in your request. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate synthesis for non-English Latin-script texts or specific voice preferences within the supported 23 languages.
What happens if the request fails?
Failed requests are free. If synthesis fails, the charge is returned in full. You are only billed for successful audio generation. This ensures you do not pay for errors or timeouts, making the character-based pricing model reliable and predictable for your restaurant tech applications and budget planning.
Is SSML supported in the input text?
No, the API does not support SSML. Input text is plain text only. There are no emotion tags, phoneme dictionaries, or custom pronunciation lexicons available. You rely on the voice presets to determine tone and style. For precise control, select the appropriate voice preset that matches your desired audio style.
Can I generate audio in real-time?
No, the API does not support real-time streaming. Audio is generated synchronously and returned in the response. Typical speed is roughly real-time on long texts, but short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue.
How do I handle large menu texts?
Split large texts into parts of up to 4096 characters. Send each part as a separate request to the /v1/audio/speech endpoint. Receive the individual audio files and join them to create the complete audio for your menu. This approach ensures compatibility with the character limit per request.
What are the supported audio formats?
You can specify the response_format field with mp3, wav, opus, flac, or pcm. These formats are available for all voice presets. Choose the format that best suits your application's playback requirements. The generated audio files are returned directly in the API response for immediate use in your system.
Does the API return metadata with the audio?
The API returns the audio file in the response. Request metadata (time, characters, status) is kept for billing. You can track usage and costs via your dashboard, which shows characters left and usage history.
Can I change the speed of the audio?
Yes, you can adjust the speed using the 'speed' field, which accepts values between 0.25 and 4.0. This allows you to slow down or speed up the narration for menus or announcements. The speed adjustment applies to the synthesis process, ensuring the output matches your desired playback rate.
Is the API key permanent?
No, the API key is not permanent. You have one active key per account, but you can issue a new key at any time. When a new key is issued, the old one stops working immediately. This allows you to rotate keys for security.
First request
curl
curl https://api.playak56.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.playak56.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.playak56.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 |
Quickstart with cURL
SavorVoice’s API accepts standard JSON payloads, making it easy to integrate with existing restaurant management systems. You can test the endpoint immediately using command-line tools without installing complex libraries.
This guide demonstrates a basic request to generate audio for a menu item announcement. The process is straightforward: send your text, receive the audio file, and play it back.
Install cURL
Ensure cURL is installed on your system. Most modern Linux and macOS systems include it by default. Windows users can download it from the official cURL website or use WSL.
Once installed, verify the installation by running curl --version in your terminal to confirm the tool is ready for use.
- Linux/macOS: Pre-installed in most distributions
- Windows: Download from curl.se or use WSL
- Verification: Run
curl --versionto check installation
Send POST Request
Use the POST method to send your text to the SavorVoice API. Replace YOUR_API_KEY with your actual key from the dashboard.
The request body must include the model, input text, and voice preset. Ensure the text does not exceed 4096 characters.
Example cURL command: `curl -X POST https://api.playak56.com/v1/audio/speech -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "Welcome to SavorVoice", "voice": "nova"}'`
- Endpoint:
https://api.playak56.com/v1/audio/speech - Method:
POST - Headers:
Authorization: Bearer YOUR_API_KEY,Content-Type: application/json - Body:
model,input,voice
Receive Audio File
The API returns the audio file directly in the response body. Save the output to a file using the -o flag.
For example, to save the audio as menu.mp3, use: curl -o menu.mp3 -X POST ...
The file format is determined by the response_format parameter, defaulting to MP3 if not specified.
- Save output:
curl -o output.mp3 -X POST ... - Default format: MP3
- Specify format: Add
"response_format": "wav"to the JSON body
OpenAI SDK Integration
SavorVoice’s API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing integration code with minimal changes. By pointing your SDK to our base URL, you can generate audio from text using the same POST /v1/audio/speech method familiar to OpenAI developers.
Set Base URL
Configure your OpenAI SDK client to point to https://api.playak56.com/v1. This single change redirects all requests to our infrastructure while maintaining the standard request shape.
Use Speech Endpoint
Call the /audio/speech endpoint with your text payload. The API accepts standard parameters like model, voice, and input, returning audio files directly in the response body.
Pass API Key
Include your unique API key in the Authorization header as Bearer tts-.... This key authenticates your requests and tracks your character usage against your balance.
Request Parameters
Configure your API calls by selecting the synthesis model, defining the text payload, and choosing the appropriate voice preset. These parameters determine the audio quality, character consumption, and narrative tone of the generated speech for your restaurant application.
Model Selection
Specify either tts-1 or tts-1-hd in the request body. Both models use the same underlying engine and incur identical pricing, allowing you to choose based on preference without affecting your cost per character.
Input Text Limit
The input field accepts up to 4096 characters per request. Each request is processed sequentially, so longer menus or announcements should be split into chunks and joined afterward. Spaces and punctuation count toward the character limit.
Voice Presets
Select one of eight voice presets to match your brand voice. Options include aria for clear narration, nova for upbeat updates, atlas for neutral announcements, and orion for deeper, documentary-style audio. Each voice supports all 23 available languages.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Response Formats
The API returns audio files in formats compatible with standard restaurant POS systems and digital signage players. Selecting the right format ensures reliable playback across your hardware stack without unnecessary bandwidth usage.
All generated files include an inaudible watermark identifying the speech as synthetic. This applies regardless of the chosen format, ensuring brand transparency for your diners.
MP3 Format
MP3 is the default and most widely supported format for web-based menus and mobile apps. It offers a good balance between file size and audio quality, making it ideal for web-based menus and mobile apps.
- Compatible with 99% of web browsers and mobile players
- Optimal for bandwidth-constrained mobile applications
WAV Format
WAV provides uncompressed, high-fidelity audio suitable for local file storage or legacy POS hardware that requires specific codec support. Use this format when absolute audio fidelity is prioritized over file size.
- Uncompressed PCM audio
- Ideal for local hardware integration
OPUS and FLAC
OPUS offers superior compression for efficient data usage in modern digital displays, while FLAC provides lossless compression for archival purposes. Choose OPUS for efficient data usage or FLAC when preserving every audio detail is necessary for quality assurance.
- OPUS: Efficient data usage
- FLAC: Lossless quality for archival
Error Handling
Errors return standard HTTP codes with JSON bodies detailing the issue. Check your input parameters and API key validity to resolve most common issues quickly.
400 Bad Request
Occurs when the request body is invalid, such as exceeding the 4096 character limit or using an unsupported voice name. Ensure your JSON structure matches the expected format.
401 Unauthorized
Returned if the Authorization: Bearer header is missing or contains an invalid key. Regenerate your key via the dashboard if it has been revoked.
429 Rate Limit
Triggers when you exceed 60 requests per minute. New accounts start with a 10 requests/minute limit. Wait briefly or wait for top-up credit to resume.

Rate Limits
The API enforces a hard limit of 60 requests per minute for standard keys, ensuring consistent performance for menu updates and order notifications. This cap applies per API key, so monitor usage to avoid throttling during peak hours.
60 Requests Per Minute
Once your account is active and funded, you can process up to 60 synthesis requests every 60 seconds. This allows for rapid bulk generation of audio files for large digital menus or multiple announcement triggers without exceeding the system's processing capacity.
- Standard limit: 60 req/min
- Per API key basis
- Suitable for high-frequency notifications
10 Requests Initial
New accounts or those with zero balance start with a reduced limit of 10 requests per minute. This ensures stability during the initial trial phase. The limit automatically increases to 60 req/min once you top up your USDT balance.
- Initial limit: 10 req/min
- Increases after first top-up
- Automatic adjustment upon funding
Queue Processing
Requests are processed sequentially within the rate limit window. If you exceed the limit, subsequent requests may wait in a queue rather than failing immediately, though this can increase total latency for long texts. Failed requests are free.
- Sequential processing
- Queueing on overflow
- Increased latency possible
Audio Speed Control
The SavorVoice API allows you to adjust the playback speed of synthesized speech between 0.25 and 4.0. This feature lets you optimize audio for menu announcements or quick notifications, ensuring clarity without sounding robotic or rushed.
Speed Range 0.25-4.0
Set the speed parameter in your POST request to control generation tempo. Values outside this range will be rejected. Slower speeds improve comprehension for complex menu items, while faster speeds suit brief alerts.
- Minimum speed: 0.25 (half time)
- Maximum speed: 4.0 (quadruple time)
- Accepts decimal values for fine tuning
Adjust for Clarity
For detailed restaurant instructions, lower the speed to ensure every syllable is distinct. For simple status updates, increase speed to reduce customer wait time. Test with your specific voice preset to find the right balance.
Default Speed
If you omit the speed field, the API uses a default rate of 1.0. This provides a natural, conversational pace suitable for most standard use cases like reading out daily specials.
Voice Selection
SavorVoice provides eight distinct voice presets designed for restaurant applications, from menu announcements to order notifications. Each voice is engineered for clarity and natural cadence, ensuring your audio content remains intelligible in busy dining environments.
8 Available Voices
The API supports eight specific voice profiles: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. These presets cover a range of tones suitable for different restaurant contexts, from casual dining to formal service.
- 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 Options
Voices are categorized by gender to match your brand identity. Female voices include Aria, Nova, Luna, and Sage. Male voices include Felix, Milo, Atlas, and Orion.
Tone Variations
Select a tone that aligns with your service style. Use Felix for energetic promotional announcements or Milo for friendly conversational updates. For instructional menu items, Sage provides a calm, clear delivery.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Your input text is used exclusively to generate the requested audio file and is not retained for model training.
23 languages
Any voice speaks any of these languages.
