API Documentation and Quickstart Integration Guide

By PlayVeBet editorial team · Updated 2026-11-18

This documentation provides the technical specifications for the PlayVeBet Text-to-Speech API, designed for engineering teams integrating synthetic speech into language learning applications. You will find precise details on endpoint structures, request parameters, and authentication protocols required for seamless deployment.

The guide covers integration using the OpenAI SDK (for Python and Node.js) and cURL examples for immediate testing. It also details rate limits, error handling, and key rotation policies to ensure reliable audio generation within your educational workflows.

API Documentation and Quickstart Integration Guide

Frequently asked questions

How do I generate an API key?

Navigate to /get-api-key/ and sign up using Google or an email and password combination. The dashboard displays your active API key immediately. Each account holds one active key at a time. You can issue a new key at any time, which invalidates the previous one instantly.

What is the base URL for the API?

The API base URL is https://api.playvebet.com/v1. Use this endpoint for all requests. For example, send POST requests to https://api.playvebet.com/v1/audio/speech. This structure matches the OpenAI endpoint shape, allowing standard HTTP clients and compatible SDKs to connect directly.

Can I use the OpenAI Python SDK?

Yes. The API uses the same request shape as the OpenAI speech endpoint. Configure your OpenAI SDK by changing the base_url to https://api.playvebet.com/v1. Pass your PlayVeBet API key in the Authorization header. This allows seamless integration without modifying your existing code structure.

How do I set the voice parameter?

Include the voice parameter in your JSON body with one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices support all 23 languages. You can retrieve the full list of available voices via the GET /v1/voices endpoint.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key. If you exceed this, subsequent requests will be queued or rejected. New accounts start with a 10 requests per minute limit. Requests are processed sequentially, so high volume may cause queuing delays beyond the limit.

Does the API support WAV format?

Yes. You can specify the response_format parameter as wav, mp3, opus, flac, or pcm. Set this field in your JSON request body. The API returns the audio file in the requested format. Failed requests do not incur charges regardless of the format used.

How do I handle long texts in requests?

Split your text into parts of up to 4096 characters. Send each part as a separate request. Receive the resulting audio files and join them programmatically. This ensures compliance with the character limit per request while allowing you to generate longer content.

What is the maximum character limit?

The maximum input length is 4096 characters per request. This limit applies to the input field in the JSON body. Spaces and punctuation count toward this total. For texts exceeding this limit, you must split the input into multiple requests.

Is SSML supported in the input text?

No. The API does not support SSML. It accepts plain text input. Custom pronunciation lexicons and phoneme dictionaries are also not available. The system processes the text directly without SSML tags. Use standard text formatting for your input.

How do I rotate my API key?

Issue a new key from your dashboard at any time. The new key becomes active immediately. The previous key stops working at once. You can generate a new key without downtime if you update your applications to use the new credential.

What does the 2400 character limit mean?

The API accepts up to 4096 characters per request. If you encounter a 2400-character limit, it likely stems from your client’s default settings or a specific implementation detail, not the API itself. Ensure your integration respects the documented 4096-character maximum for single requests to optimize efficiency.

Can I stream audio as it generates?

No. The API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response. There is no real-time partial audio delivery. You must wait for the full synthesis to complete before receiving the audio data.

How do I specify the language code?

Include the language parameter with an ISO code in your JSON body. If omitted, the system guesses the language from the script. Latin text defaults to English. Set the language explicitly for non-English Latin-script text to ensure accurate synthesis.

What is the default response format?

The default response format is mp3. You can specify an alternative by setting the response_format parameter to wav, opus, flac, or pcm. If unspecified, the API returns mp3, ensuring compatibility with standard audio players. Note that the API does not support SSML or custom pronunciation lexicons, so format selection applies to the raw synthesized output.

First request

curl

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

Authentication for the PlayVeBet TTS API relies on a single active Bearer token per account. Developers must provision this key via the /get-api-key/ dashboard, where the current credential and usage metrics are displayed. The token authenticates all requests to the API base URL.

Generating API Keys

Generating API Keys

Create an account using Google Sign-In or email credentials. The dashboard displays your active key immediately upon registration. Only one key is active at any time; generating a new key invalidates the previous one instantly.

Bearer Token Usage

Bearer Token Usage

Include the key in the HTTP header as Authorization: Bearer tts-<your-key>. This header is required for all endpoints, including speech synthesis and voice listing. Ensure the key is transmitted securely over HTTPS.

Key Rotation Policy

Keys can be rotated at any time via the dashboard. Upon issuing a new key, the old one stops working immediately. This ensures quick revocation if a key is compromised, with no downtime for new keys.

Endpoint Configuration

Sound wave illustration for: Endpoint Configuration

The API operates on a strict RESTful structure accessible via https://api.playvebet.com/v1. All requests must target this base URL, ensuring compatibility with standard HTTP libraries and the official OpenAI SDKs when the base URL is overridden.

Base URL Structure

Use https://api.playvebet.com/v1 as the base endpoint for all API interactions. This base URL replaces the default OpenAI endpoint in your SDK configuration, allowing you to use the official OpenAI SDKs without modification to the request body shape.

Speech Endpoint Path

Send text-to-speech requests to POST /v1/audio/speech. This endpoint accepts JSON bodies containing the model, input, voice, and optional response_format or speed parameters. The API returns the generated audio file directly in the response body.

Voice Listing Endpoint

Retrieve available voices, supported languages, and audio formats by sending a GET request to /v1/voices. This endpoint provides the necessary metadata to correctly format your speech requests, including the valid voice IDs such as aria, nova, or atlas.

Request Parameters

Sound wave illustration for: Request Parameters

The API requires specific parameters to generate audio correctly. You must define the model, input text, voice, and optional formatting options in the JSON body of your POST request. These fields determine the synthesis engine, audio quality, and output characteristics.

Proper configuration ensures consistent results across language learning applications. Verify that all inputs adhere to the defined constraints before submission to avoid processing delays or silent failures.

Model Selection Options

Select between 'tts-1' or 'tts-1-hd'. Both models use the same engine and pricing structure. The choice does not affect cost or engine quality; both models use the same engine and pricing.

The model field is required for every request. Using either value yields identical audio quality for standard use cases.

  • Model values: 'tts-1', 'tts-1-hd'

Input Text Constraints

The 'input' field accepts a string of up to 4096 characters. Spaces and punctuation count toward this limit. Longer texts must be split into multiple requests and joined client-side.

If the text exceeds the limit, the request will fail. Ensure your application handles character counting before sending data to the endpoint.

  • Maximum length: 4096 characters per request

Voice ID Assignment

Assign one of eight preset voices using the 'voice' field. Each voice has a distinct tone suitable for educational content. Examples include 'aria' for narration or 'atlas' for neutral delivery.

Optionally specify a 'language' ISO code if the text script does not clearly indicate the language. Without this, the system guesses the language, defaulting to English for Latin script.

  • Supported voices: aria, nova, luna, sage, felix, milo, atlas, orion
  • Optional language parameter for disambiguation

Response Handling

Sound wave illustration for: Response Handling

The API returns the synthesized audio file directly in the response body, eliminating the need for secondary polling or file retrieval steps. Depending on your chosen response_format, the payload is delivered as MP3, WAV, OPUS, FLAC, or PCM data, ensuring compatibility with standard educational media players and LMS integrations.

Audio Format Output

Generated audio is returned in the response and not stored. Clients receive the raw audio bytes immediately upon successful synthesis, allowing for direct streaming or local caching within your application's memory or temporary storage.

Select the format that best matches your language learning platform's requirements. MP3 offers efficient compression for web delivery, while WAV or FLAC provides uncompressed quality for high-fidelity pronunciation exercises.

  • Supported formats: mp3, wav, opus, flac, pcm
  • No server-side storage of generated audio files
  • Direct binary response body

Status Code Interpretation

A 200 OK status indicates successful synthesis. The response body contains the audio data. Other 2xx codes confirm successful processing of the request.

Non-2xx codes indicate errors. Failed requests are free, and any pre-charged amounts are returned in full. Check the response headers for specific error details.

Error Message Structure

Errors follow a standard JSON structure with an error object containing type and message fields. This structure aids in automated error handling within your integration.

Common errors include invalid API keys, input text exceeding 4096 characters, or unsupported voice IDs. Review the message to correct the request parameters before retrying.

  • JSON error response format
  • Includes type and message fields
  • Failed requests incur no charge

SDK Integration Examples

Sound wave illustration for: SDK Integration Examples

PlayVeBet’s API mirrors the OpenAI speech endpoint structure, allowing direct integration with existing OpenAI SDKs. This compatibility enables rapid deployment for language learning applications by requiring only a base URL adjustment when using the official OpenAI SDKs.

Python SDK Configuration

Import the OpenAI library and initialize the client with your Bearer token. Set the base_url to https://api.playvebet.com/v1 to route requests through our infrastructure. This ensures all synthesis calls utilize the correct PlayVeBet endpoint.

  • Use openai.OpenAI(base_url="https://api.playvebet.com/v1", api_key="tts-...")
  • Call client.audio.speech.create() with standard parameters
  • Response includes audio bytes directly in the response body

Node.js SDK Setup

Install the openai npm package and configure the client similarly. Pass the API key and override the base URL to point to the PlayVeBet service. This method supports both synchronous and asynchronous text-to-speech generation for web applications.

  • Initialize with new OpenAI({ baseURL: 'https://api.playvebet.com/v1', apiKey: 'tts-...' })
  • Supports Promise-based audio generation
  • Compatible with standard Node.js event loops

Base URL Override Method

The core integration strategy relies on overriding the default base URL. Since the request shape matches the OpenAI standard, developers can switch providers by changing a single configuration variable. This simplifies testing and production deployments for educational tools.

  • Change base_url to https://api.playvebet.com/v1
  • Retain standard model, voice, and input fields
  • No custom SDK installation required
SDK Integration Examples

Curl Command Examples

Sound wave illustration for: Curl Command Examples

To generate audio directly from the command line, send a POST request to the speech endpoint with your bearer token and desired parameters. The API returns the audio file in the specified format, allowing for immediate integration into language learning workflows without complex SDK dependencies.

Basic Speech Request

Use this command to convert text into speech using the default model and voice. Replace YOUR_API_KEY with your actual key and input_text with the content you wish to synthesize. The response will contain the audio binary data.

  • POST https://api.playvebet.com/v1/audio/speech
  • Headers: Authorization: Bearer YOUR_API_KEY
  • Body: {"model": "tts-1", "input": "Hello world", "voice": "aria"}

Speed Adjustment Request

Adjust the playback speed between 0.25 and 4.0 to match learner pacing. This parameter is useful for creating clear audio for language acquisition exercises. The API processes the request synchronously, ensuring consistent audio quality regardless of speed variations.

  • --data '{"model": "tts-1", "input": "Fast speech", "voice": "nova", "speed": 1.5}'

Format Selection Request

Specify the output format using the response_format field. Supported formats include mp3, wav, opus, flac, and pcm. Choosing the appropriate format ensures compatibility with your existing audio processing pipelines and reduces bandwidth usage for language learning applications.

  • --data '{"model": "tts-1", "input": "Audio file", "voice": "sage", "response_format": "mp3"}'

Rate Limiting Details

Sound wave illustration for: Rate Limiting Details

Rate limits are enforced per API key to ensure stable service for language learning applications. After the first top-up, each key allows 60 requests per minute. This throughput supports typical educational workflows without requiring complex batching logic.

Requests Per Minute Limit

After the first top-up, each key allows 60 requests per minute. This limit applies to all synthesis requests, including those with varying speeds or formats. Exceeding this threshold results in standard HTTP 429 responses.

Pre-Top-Up Limit

Accounts without an active top-up operate under a reduced limit of 10 requests per minute. This ensures fair usage during the initial trial phase or before financial verification is complete.

Queuing Behavior

Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. This behavior ensures deterministic processing order but may increase latency for bulk generation tasks.

Troubleshooting Common Issues

Sound wave illustration for: Troubleshooting Common Issues

The API returns a 401 Unauthorized status when the Bearer token is missing, expired, or incorrect. Verify that your key begins with "tts-" and matches the active key in your PlayVeBet dashboard. If you rotated your key, ensure the old one is no longer in use, as rotation invalidates previous credentials immediately.

Input Text Length Errors

The API rejects payloads exceeding 4096 characters, returning a 413 error. Each request must contain a single text segment within this limit. For longer content, implement client-side splitting to divide the input into chunks, process each separately, and concatenate the resulting audio files.

  • Maximum input length: 4096 characters per request.
  • Spaces and punctuation count toward the character limit.
  • Split long texts client-side before sending requests.

Network Timeout Handling

Short phrases typically generate within a few seconds, but longer texts may take longer due to real-time processing speeds (approximately 25 characters per second). Under load, requests queue sequentially, which may extend response times beyond standard thresholds. Implement exponential backoff for retries to handle temporary delays without overwhelming the endpoint.

  • Set HTTP timeout to at least 30 seconds for short texts.
  • Expect longer latency for texts exceeding 1000 characters.
  • Retry with backoff if the queue is full.

Invalid API Key Errors

Ensure the Authorization header uses the format Bearer tts-.... Keys are case-sensitive and must match the active key in your PlayVeBet account dashboard. If you issued a new key, the previous one stops working immediately. Use the dashboard’s "Revoke" or "Generate" functions to manage active credentials.

  • Header format: Authorization: Bearer tts-<your-key>.
  • One active key per account; rotation invalidates old keys instantly.
  • Check dashboard for current key status and balance.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Empower your global team with intuitive language learning tools that bridge cultural gaps and accelerate collaboration.

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. curl documentation
  3. ISO 639 language codes
  4. openai-node on GitHub
  5. IETF RFC 7845: Ogg Opus
  6. TRON developer hub: TRC-20
  7. W3C WAI: making audio and video accessible
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. FFmpeg documentation
  10. Node.js documentation
  11. Python documentation
  12. OpenAI API reference: create speech

More on this site