Developer Documentation for Restaurant TTS API

By SavorVoice editorial team · Updated 2026-11-18

This documentation provides a complete reference for integrating SavorVoice’s text-to-speech API into restaurant technology applications. You will find clear instructions for generating audio from menu items, order notifications, and dining announcements using standard HTTP requests. The guide covers all essential parameters, including voice selection, audio formats, and speed adjustments, ensuring you can build reliable audio workflows with minimal configuration.

Designed for developers building solutions for restaurants and dining halls, this page details the technical specifics of the SavorVoice API. It explains how to handle requests, manage rate limits, and interpret responses using tools like cURL or the OpenAI SDK. Whether you are integrating with existing POS systems or creating new customer-facing apps, this guide gives you the exact endpoints and parameters needed to start generating synthetic speech immediately.

Developer Documentation for Restaurant TTS API

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

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

Quickstart with cURL

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

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 --version to check installation

Send POST Request

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

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

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

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

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

Error Handling

Rate Limits

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

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

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

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. IETF RFC 7845: Ogg Opus
  4. Python documentation
  5. Tether (USDT)
  6. MDN: Web Speech API
  7. OpenAI API reference: create speech
  8. curl documentation
  9. openai-node on GitHub
  10. TRON developer hub: TRC-20
  11. ISO 639 language codes
  12. W3C WAI: making audio and video accessible

More on this site