Introduction
Welcome to the Verbatik API documentation. This API allows you to convert text to speech using advanced neural voice technology. With support for multiple languages and voices, you can create natural-sounding audio content for your applications.
Authentication
All API requests require authentication using an API token. You can obtain an API token from your Verbatik dashboard.
API Token
Include your API token in the Authorization header of all requests:
Authorization: Bearer vbt_your_api_token
If no token is provided or an invalid token is used, the API will return a 401 Unauthorized error.
Rate Limiting
API requests are subject to rate limiting to ensure fair usage. The default rate limit is 60 requests per minute, but this can be customized in your account settings.
If you exceed your rate limit, the API will return a 429 Too Many Requests error with the following response:
{ "error": "Too Many Requests", "message": "Rate limit exceeded" }
Character Credits
Each API request consumes character credits from your account. The number of characters consumed is based on the length of the text being converted to speech.
If you don't have enough character credits, the API will return a 402 Payment Required error with the following response:
{ "error": "Insufficient character balance", "required": 150, "available": 100 }You can purchase additional character credits from your dashboard.
API Endpoints
Base URL
All API endpoints are relative to:
1. Text-to-Speech Synthesis
Convert text to speech and receive an audio file.
Endpoint:
POST /tts
Headers:
Authorization: Bearer vbt_your_api_token(required)X-Voice-ID: VoiceName(optional, defaults to "Matthew")X-Store-Audio: true(optional, defaults to false)
Request Body:
Plain text or SSML content
SSML Support:
You can use Speech Synthesis Markup Language (SSML) to control aspects of speech such as pronunciation, volume, pitch, and rate. If you send plain text, it will be automatically wrapped in SSML tags.
Example SSML:
<speak version="1.0"> Hello, <break time="1s"/> welcome to <emphasis>Verbatik</emphasis>! </speak>
Two Ways to Call the API:
Method 1: Direct Audio Response
By default, or when X-Store-Audio: false, the API returns the audio file directly in the response. This is useful for immediate playback or when you want to handle the audio file yourself.
Example Request:
curl -X POST "https://api.verbatik.com/api/v1/tts" \ -H "Authorization: Bearer vbt_your_api_token" \ -H "X-Voice-ID: Matthew" \ -H "Content-Type: application/ssml+xml" \ -d "Hello, welcome to Verbatik!" \ --output speech.mp3
Response:
The response will be the binary audio data with Content-Type: audio/mpeg. You'll need to save this as an MP3 file or process it accordingly.
Method 2: AWS S3 URL Response
When you set X-Store-Audio: true, the API will store the audio file in AWS S3 and return a URL. This is useful when you want to avoid handling binary data or need a persistent URL to the audio.
Example Request:
curl -X POST "https://api.verbatik.com/api/v1/tts" \ -H "Authorization: Bearer vbt_your_api_token" \ -H "X-Voice-ID: Matthew" \ -H "X-Store-Audio: true" \ -H "Content-Type: text/plain" \ -d "Hello, welcome to Verbatik!"
Response:
{ "success": true, "audio_url": "https://s3.eu-west-2.amazonaws.com/speak.verbatik.com/audio/filename.mp3" }The returned URL can be used directly in audio players, shared with users, or embedded in applications. The audio files are stored with public read access but have randomized filenames for security.
Error Responses:
401 Unauthorized: Invalid or missing API token
402 Payment Required: Insufficient character balance
429 Too Many Requests: Rate limit exceeded
400 Bad Request: Invalid request format
500 Internal Server Error: Server-side error
2. List Available Voices
Get a list of all available voices.
Endpoint:
GET /voices
Headers:
Authorization: Bearer vbt_your_api_token(required)
Response:
[ { "name": "Matthew", "gender": "Male", "language_code": "en-US" }, { "name": "Joanna", "gender": "Female", "language_code": "en-US" }, ... ]Voice Selection
Verbatik supports a wide range of voices across multiple languages and providers. You can specify the voice using the X-Voice-ID header.
Language Support
The API supports multiple languages, including but not limited to:
English (US, UK, AU)
Spanish
French
German
Italian
Japanese
Chinese
And many more
Best Practices
Optimize Character Usage
To optimize your character usage:
Keep your text concise and to the point
Use SSML for better control over speech synthesis
Monitor your usage in the dashboard
Error Handling
Always implement proper error handling in your application to handle potential API errors:
Check for sufficient character balance
Handle rate limiting with exponential backoff
Validate your input before sending to the API
Security
Keep your API token secure and never expose it in client-side code
Rotate your API tokens periodically
Set appropriate rate limits to prevent abuse
Code Examples
Method 1: Direct Audio Response
cURL
curl -X POST "https://api.verbatik.com/api/v1/tts" \ -H "Authorization: Bearer vbt_your_api_token" \ -H "X-Voice-ID: Matthew" \ -H "Content-Type: application/ssml+xml" \ -d "Hello, welcome to Verbatik!" \ --output speech.mp3
JavaScript
async function synthesizeSpeech(text, voiceId = 'Matthew') { const response = await fetch('https://api.verbatik.com/api/v1/tts', { method: 'POST', headers: { 'Authorization': 'Bearer vbt_your_api_token', 'X-Voice-ID': voiceId, 'Content-Type': 'application/ssml+xml' }, body: text }); if (!response.ok) { const error = await response.json(); throw new Error(error.message || 'Failed to synthesize speech'); } const blob = await response.blob(); return URL.createObjectURL(blob); }PHP
function synthesizeSpeech($text, $voiceId = 'Matthew') { $ch = curl_init(); $headers = [ 'Authorization: Bearer vbt_your_api_token', 'X-Voice-ID: ' . $voiceId, 'Content-Type: application/ssml+xml' ]; curl_setopt($ch, CURLOPT_URL, 'https://api.verbatik.com/api/v1/tts'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $text); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode !== 200) { $error = json_decode($response, true); throw new Exception($error['message'] ?? 'Failed to synthesize speech'); } // Save the audio file file_put_contents('speech.mp3', $response); return 'speech.mp3'; }Method 2: AWS S3 URL Response
cURL
curl -X POST "https://api.verbatik.com/api/v1/tts" \ -H "Authorization: Bearer vbt_your_api_token" \ -H "X-Voice-ID: Matthew" \ -H "X-Store-Audio: true" \ -H "Content-Type: text/plain" \ -d "Hello, welcome to Verbatik!"
JavaScript
async function synthesizeSpeechWithUrl(text, voiceId = 'Matthew') { const response = await fetch('https://api.verbatik.com/api/v1/tts', { method: 'POST', headers: { 'Authorization': 'Bearer vbt_your_api_token', 'X-Voice-ID': voiceId, 'X-Store-Audio': 'true', 'Content-Type': 'text/plain' }, body: text }); if (!response.ok) { const error = await response.json(); throw new Error(error.message || 'Failed to synthesize speech'); } const data = await response.json(); return data.audio_url; }PHP
function synthesizeSpeechWithUrl($text, $voiceId = 'Matthew') { $ch = curl_init(); $headers = [ 'Authorization: Bearer vbt_your_api_token', 'X-Voice-ID: ' . $voiceId, 'X-Store-Audio: true', 'Content-Type: text/plain' ]; curl_setopt($ch, CURLOPT_URL, 'https://api.verbatik.com/api/v1/tts'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $text); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode !== 200) { $error = json_decode($response, true); throw new Exception($error['message'] ?? 'Failed to synthesize speech'); } $data = json_decode($response, true); return $data['audio_url']; }
Logs
Billing
Support
If you encounter any issues or have questions about the API, please contact our support team at [email protected].