Written by Verbatik Support
Updated over 5 months ago

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:

https://api.verbatik.com/api/v1

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

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