Developer Guide for TTS API Integration and Usage

By Viva Voice Labs editorial team · Updated 2026-11-18

This guide details the integration of the Viva Voice Labs TTS API for call center operators and indie developers building high-volume IVR systems. You will find concrete specifications for authentication, endpoint structures, and parameter handling required to generate synthetic audio files programmatically.

The documentation covers request formatting, response formats including MP3 and WAV, and practical implementation examples using cURL and standard SDKs. It also outlines rate limits, error handling, and latency expectations to ensure reliable integration into your telephony infrastructure.

Developer Guide for TTS API Integration and Usage

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playmvpviva.com/v1. You configure your SDK or HTTP client to use this endpoint for all requests. This includes the speech generation endpoint at /v1/audio/speech and the voices listing at /v1/voices. Ensure your application routes all API calls through this domain to interact with the service correctly.

How do I install the OpenAI SDK for this API?

Install the official OpenAI SDK using your preferred package manager. Then, initialize the client by setting the base_url to https://api.playmvpviva.com/v1. Use your API key for authentication. The request shape matches the OpenAI speech endpoint, allowing you to use existing code with minimal configuration changes for this independent storefront.

What is the maximum length for a single request?

The maximum length for a single request is 4096 characters. If your text exceeds this limit, you must split it into parts of up to 4096 characters each. Generate audio for each part separately and join the resulting audio files to create the complete output. Spaces and punctuation count toward this limit.

Can I stream audio as it is generated?

No, streaming is not supported. The API returns the complete audio file in the response body after synthesis finishes. You must wait for the request to complete before accessing the audio data. There is no WebSocket or real-time partial audio delivery available for this text-to-speech service.

How do I specify the language for Latin script text?

If the language is not set, the API guesses it from the script, defaulting to English for Latin text. To ensure correct pronunciation for non-English Latin-script text, explicitly set the language parameter to the appropriate ISO code. This prevents the system from defaulting to English and ensures accurate voice output.

What happens if I exceed the rate limit?

The rate limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. Requests before the first top-up are limited to 10 per minute. Failed requests are free, so you will not be charged for characters processed during a failed attempt due to rate limiting.

Does the API return a file URL or the file directly?

The API returns the audio file directly in the response body. It does not provide a file URL for later download. The generated audio is returned immediately upon completion of the synthesis process. The file is not stored on the server after the response is sent.

How do I handle requests larger than 4096 characters?

Split the input text into chunks of up to 4096 characters each. Send each chunk as a separate request to the /v1/audio/speech endpoint. Receive the individual audio files for each chunk. Finally, join these audio files programmatically to create the complete audio output for the original long text.

Is SSML supported in the input text?

No, SSML is not supported. The API accepts plain text input only. You cannot use SSML tags for pronunciation, breaks, or emphasis. The system processes the text as a simple string. For custom pronunciation, you must rely on the standard text input without any markup extensions.

Can I use custom voices in the standard API?

No, custom voice cloning is not offered. You must choose from the eight available presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings. You cannot upload your own voice or design a custom voice for use in the standard API requests.

What is the default speed setting?

The default speed is 1.0. You can adjust the speed between 0.25 and 4.0 using the speed parameter. This allows you to slow down or speed up the voice output. The default setting provides a natural speaking pace suitable for most IVR and call center applications.

How do I authenticate my requests?

Include an Authorization header with the value Bearer followed by your API key. The key format starts with tts-.... You can generate or view your key on the /get-api-key/ page. Each account has one active key; issuing a new one immediately invalidates the previous one.

Are there any required headers besides Authorization?

No other headers are strictly required for basic functionality. You must send the Authorization header with your Bearer token. The Content-Type header should be set to application/json for the request body. No other specific headers are mandated by the API specification for standard text-to-speech requests.

What is the difference between tts-1 and tts-1-hd in code?

In code, both models use the same request shape and endpoint. The difference is the engine quality; the price is the same. tts-1-hd offers higher quality audio. Both models have the same price of $10 per 1 million characters. Choose based on your quality requirements without worrying about code structure changes.

First request

curl

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

Access to the Viva Voice Labs API requires a valid bearer token. You can generate your key by signing in via Google or email on the /get-api-key/ page. Each account holds one active key; use the dashboard to view your current token and usage statistics.

Generating Your API Key

Generating Your API Key

Navigate to the /get-api-key/ page to create your account. Choose Google authentication for immediate trial credit ($0.50) or email/password for standard access. The dashboard displays your active key and character balance.

Authorization Header Format

Authorization Header Format

Include your token in every request using the standard HTTP header. The format is: Authorization: Bearer tts-.... Ensure no extra spaces exist before the token value.

  • Header: Authorization: Bearer tts-<your_key>
  • Case-sensitive prefix: Bearer

Key Rotation Policy

You may issue a new key at any time via the dashboard. The previous key becomes inactive immediately upon generation of the new one. Rotate keys periodically for security without service interruption.

Endpoint Overview

Sound wave illustration for: Endpoint Overview

The API provides three primary endpoints for integration. The speech endpoint processes text into audio, while the voices and models endpoints provide metadata for configuration.

These endpoints operate under the base URL https://api.playmvpviva.com/v1. Use standard HTTP methods to retrieve voice lists or generate speech files.

Developers can implement these endpoints directly using cURL or language-specific SDKs. The speech endpoint accepts JSON payloads and returns the audio file directly in the response body, or an error code.

Speech Generation Endpoint

Send a POST request to /v1/audio/speech with your API key in the Authorization header. The request body must include the model, input text, voice selection, and response format.

The endpoint processes text up to 4096 characters and returns the synthesized audio file. Failed requests do not incur charges.

  • Method: POST
  • Path: /v1/audio/speech
  • Content-Type: application/json

Voice Listing Endpoint

Retrieve available voices, languages, and formats via a GET request to /v1/voices. This endpoint returns metadata for all 8 voice presets and supported languages.

Use this endpoint to dynamically update your IVR menu options based on available voice characteristics and language support.

  • Method: GET
  • Path: /v1/voices

Model Information Endpoint

Access model details using a GET request to /v1/models. This endpoint confirms the available models: tts-1 and tts-1-hd, which share the same engine and pricing.

Use this information to ensure compatibility with your chosen SDK configuration.

  • Method: GET
  • Path: /v1/models
  • Models: tts-1, tts-1-hd

Request Parameters

Sound wave illustration for: Request Parameters

The TTS API accepts input text via the input field in the JSON request body. Each request supports a maximum of 4,096 characters. Spaces and punctuation are counted toward this limit. If your text exceeds this length, you must split the content into chunks and join the resulting audio files manually.

Voice selection is controlled by the voice parameter, which accepts one of eight preset identifiers. These voices are designed for high-volume IVR use, offering consistent synthetic speech suitable for call centers. The available presets include female voices such as aria, nova, luna, and sage, and male voices including felix, milo, atlas, and orion.

You can adjust the playback speed using the speed parameter, which accepts values between 0.25 and 4.0. The language parameter accepts an optional ISO code to specify the output language. If omitted, the system guesses the language based on the script, defaulting to English for Latin text. All eight voices can speak all 23 supported languages, including English, Spanish, German, French, Japanese, Chinese, Arabic, and Hindi.

- input: Text string (max 4,096 characters) - voice: One of 8 preset identifiers (e.g., "aria", "atlas") - speed: Float between 0.25 and 4.0 - language: Optional ISO code (e.g., "en", "de") - Supported languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Input Text Limits

The TTS API accepts input text via the input field in the JSON request body. Each request supports a maximum of 4,096 characters. Spaces and punctuation are counted toward this limit. If your text exceeds this length, you must split the content into chunks and join the resulting audio files manually.

Voice Selection

Voice selection is controlled by the voice parameter, which accepts one of eight preset identifiers. These voices are designed for high-volume IVR use, offering consistent synthetic speech suitable for call centers. The available presets include female voices such as aria, nova, luna, and sage, and male voices including felix, milo, atlas, and orion.

Speed and Language Codes

You can adjust the playback speed using the speed parameter, which accepts values between 0.25 and 4.0. The language parameter accepts an optional ISO code to specify the output language. If omitted, the system guesses the language based on the script, defaulting to English for Latin text. All eight voices can speak all 23 supported languages, including English, Spanish, German, French, Japanese, Chinese, Arabic, and Hindi.

- input: Text string (max 4,096 characters) - voice: One of 8 preset identifiers (e.g., "aria", "atlas") - speed: Float between 0.25 and 4.0 - language: Optional ISO code (e.g., "en", "de") - Supported languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Response Formats

Sound wave illustration for: Response Formats

The API returns synthesized audio as a binary payload within the HTTP response body. Clients must handle the raw bytes directly, as the response does not include wrapper metadata or JSON structures around the audio data itself. This design ensures minimal overhead for high-volume IVR systems.

MP3 Audio Output

MP3 is one of the supported response formats, offering a balance between file size and compatibility. It is suitable for most standard telephony applications and web players. The encoder produces consistent bitrates without requiring additional configuration from the client.

WAV and FLAC Options

WAV provides uncompressed PCM audio, suitable for systems requiring linear pulse-code modulation. FLAC offers lossless compression, reducing bandwidth usage while preserving audio fidelity. Both formats are useful for quality assurance or archival purposes.

PCM and Opus Support

PCM returns raw, uncompressed audio samples, allowing clients to apply their own encoding or processing pipelines. Opus provides high-quality audio at lower bitrates, optimizing bandwidth for VoIP integrations. Select the format that aligns with your specific infrastructure constraints.

Integration Examples

Sound wave illustration for: Integration Examples

Integration requires minimal configuration. Developers can immediately begin synthesizing speech by pointing their client to the API base URL and providing a valid bearer token.

cURL Request Example

Use the following command to generate audio. Replace the placeholder with your actual API key and desired voice preset.

  • POST https://api.playmvpviva.com/v1/audio/speech
  • Content-Type: application/json
  • Authorization: Bearer tts-your-api-key-here

Python SDK Configuration

The official OpenAI Python SDK works by overriding the base URL. Initialize the client with https://api.playmvpviva.com/v1 and pass your key.

  • pip install openai
  • from openai import OpenAI
  • client = OpenAI(base_url="https://api.playmvpviva.com/v1", api_key="tts-...")

Node.js Implementation

Configure the Node.js client similarly. Set the base URL to the API endpoint to ensure requests route correctly to the speech generation service.

  • import OpenAI from "openai"
  • const client = new OpenAI({
  • baseURL: "https://api.playmvpviva.com/v1",
  • apiKey: "tts-..."
  • })
Integration Examples

Error Handling

Sound wave illustration for: Error Handling

Proper error handling ensures your IVR system remains stable during API interactions. Responses include standard HTTP codes and detailed JSON bodies to help you diagnose issues quickly without manual intervention.

Common HTTP Status Codes

The API returns standard HTTP status codes to indicate request outcomes. A 200 OK response confirms successful audio generation. Use 4xx codes for client-side issues like missing authentication or invalid parameters, and 5xx for server-side failures.

Rate Limit Errors

You receive a 429 Too Many Requests error if you exceed 60 requests per minute. New accounts start with a stricter limit of 10 requests per minute. Implement exponential backoff to handle these throttling events gracefully without dropping calls.

Invalid Parameter Messages

Invalid inputs such as out-of-range speeds or unsupported voices return a 400 Bad Request. The response body includes a specific error message describing the invalid field. Ensure your input text does not exceed 4096 characters per request to avoid truncation errors.

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

The API enforces a strict rate limit of 60 requests per minute per active key. This limit applies to all synthesis endpoints and ensures stable throughput for high-volume IVR systems. Exceeding this threshold results in standard HTTP 429 responses, allowing developers to implement exponential backoff strategies without service interruption.

60 Requests Per Minute

Each API key supports up to 60 requests per minute. This capacity is suitable for high-volume IVR systems. Requests are processed sequentially; under heavy load, a request may wait in a queue before synthesis begins.

  • Limit applies per key, not per IP address
  • Standard limit for all active accounts
  • Queued requests preserve character count billing

Initial Limit for New Accounts

New accounts start with a reduced rate limit of 10 requests per minute. This limit remains in effect until the first top-up is completed. Once a minimum $5 USDT transfer is processed on the TRON network, the account automatically upgrades to the standard 60 requests per minute capacity.

Queue Processing Behavior

Requests are processed one after another. If the queue is full, new requests wait until a slot becomes available. Long texts are split into 4096-character parts and joined after generation, which may increase total latency. Typical speed is roughly real-time, but short phrases may take a few seconds to generate.

  • Sequential processing ensures consistent voice quality
  • Queue wait times vary by server load
  • Failed requests do not consume quota

Advanced Usage

Sound wave illustration for: Advanced Usage

For IVR systems processing extended prompts, split input text into segments of 4096 characters or fewer before sending individual requests. This ensures compliance with the single-request character limit and prevents payload rejection.

Handling Long Text Strings

Divide your script into chunks not exceeding 4096 characters. Send each chunk as a separate POST request to the speech endpoint. Concatenate the resulting audio files sequentially to reconstruct the full message.

Audio File Joining Logic

Receive separate audio files for each chunk. Use your preferred media library to join these files in the exact order of the original text segments. The API does not handle concatenation; this logic resides in your client application.

Latency Expectations

Generation speed averages roughly 25 characters per second. Long texts process in real-time, but short phrases may take a few seconds. Requests are processed sequentially, so high load may introduce queue delays. Plan your IVR timeout thresholds accordingly.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. This voice is optimal for general call center announcements where clarity is paramount.

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. openai-node on GitHub
  3. W3C WAI: making audio and video accessible
  4. FFmpeg documentation
  5. curl documentation
  6. MDN: Web Speech API
  7. ISO 639 language codes
  8. openai-python on GitHub
  9. Creative Commons Attribution 4.0
  10. LibriVox public-domain audiobooks
  11. IETF RFC 7845: Ogg Opus
  12. OpenAI API reference: create speech

More on this site