API Documentation

Introduction

The LuvVoice API enables you to convert text into high-quality, natural-sounding speech using advanced AI technology. Our API supports multiple voices with customizable rate, pitch, and volume settings. Audio is generated in MP3 format, and the voice ID determines the language and characteristics.

Base URL

https://luvvoice.com/api/v1/text-to-speech

Authentication

The LuvVoice API uses Bearer token authentication. You'll need to include your API token in the Authorization header of every request.

⚠️ Pro Plan Required

API access is only available to Pro plan users. Upgrade your plan to get started.

Getting Your API Token

Sign in to your LuvVoice account
Navigate to Dashboard → API Tokens
Click "Create New Token"
Give your token a descriptive name
Copy and securely store your token

Authorization Header Format:

Authorization: Bearer YOUR_API_TOKEN

Getting Available Voices

You can retrieve the complete list of available voices using a GET request with the action=voices parameter.

Request Example

bash

curl -X GET "https://luvvoice.com/api/v1/text-to-speech?action=voices" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Format

JSON

{
  "success": true,
  "voices": [
    {
      "voice_id": "voice-001",
      "name": "Jenny",
      "gender": "Female",
      "language": "en-US",
      "language_name": "English (United States)"
    },
    {
      "voice_id": "voice-002",
      "name": "Guy",
      "gender": "Male",
      "language": "en-US",
      "language_name": "English (United States)"
    },
    {
      "voice_id": "voice-050",
      "name": "Alvaro",
      "gender": "Male",
      "language": "es-ES",
      "language_name": "Spanish (Spain)"
    }
  ],
  "total_voices": 290,
  "languages_supported": 85
}

Voice Object Fields:

voice_id - Unique identifier for the voice (use this in TTS requests)
name - Display name of the voice
gender - Voice gender (Female/Male/Unknown)
language - Language code (e.g., "en-US", "zh-CN")
language_name - Full language name

API Endpoint

POST/text-to-speech

Convert text to speech using AI-powered voices.

Request Parameters

Parameter	Type	Required	Description
text	string	Required	The text to convert to speech. Maximum 20,000 characters.
voice_id	string	Required	The ID of the voice to use. See available voices below.
rate	number	Optional	Speech rate/speed. Range: -50 to 50. Default: 0
pitch	number	Optional	Speech pitch. Range: -50 to 50. Default: 0
volume	number	Optional	Speech volume. Range: -50 to 50. Default: 0

Available Voices

Voice IDs use the format "voice-XXX" (e.g., voice-001, voice-002). To get the complete list of available voices:

Get Voice List:

curl -X GET "https://luvvoice.com/api/v1/text-to-speech?action=voices" \ -H "Authorization: Bearer YOUR_API_TOKEN"

Popular voice examples:

voice-001 (Jenny - English Female)voice-002 (Guy - English Male)voice-050 (Alvaro - Spanish Male)voice-093 (Xiaoxiao - Chinese Female)voice-111 (Katja - German Female)voice-120 (Nanami - Japanese Female)

API Responses

Success Response (200 OK)

JSON

{
  "success": true,
  "audio_url": "https://cdn.luvvoice.com/audio/generated_audio_123.mp3",
  "audio_data": "<base64-encoded-mp3-data>",
  "credits_consumed": 42,
  "credits_remaining": 9958,
  "duration_ms": 1234
}

Response Fields:

success - Always true for successful requests
audio_url - Direct URL to the generated audio file (MP3 format)
audio_data - Base64 encoded audio data (present when audio is streamed)
credits_consumed - Number of credits used for this request
credits_remaining - Your remaining credit balance
duration_ms - Processing time in milliseconds

Error Response

JSON

{
  "error": "Insufficient credits. Required: 100, Available: 50",
  "message": "Please upgrade your plan or purchase more credits",
  "timestamp": "2024-01-15T10:30:00Z",
  "api_version": "v1",
  "credits_consumed": 0
}

Code Examples

cURL

bash

curl -X POST "https://luvvoice.com/api/v1/text-to-speech" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world! This is a test of the LuvVoice API.",
    "voice_id": "voice-001",
    "rate": 0,
    "pitch": 0,
    "volume": 0
  }'

JavaScript (Fetch API)

javascript

const response = await fetch('https://luvvoice.com/api/v1/text-to-speech', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Hello, world! This is a test of the LuvVoice API.',
    voice_id: 'voice-001',
    rate: 0,
    pitch: 0,
    volume: 0
  })
});

const result = await response.json();

if (response.ok) {
  if (result.audio_url) {
    console.log('Audio URL:', result.audio_url);
  } else if (result.audio_data) {
    // Convert Base64 to Blob and download as MP3 in browser
    const byteCharacters = atob(result.audio_data);
    const byteNumbers = new Array(byteCharacters.length);
    for (let i = 0; i < byteCharacters.length; i++) {
      byteNumbers[i] = byteCharacters.charCodeAt(i);
    }
    const byteArray = new Uint8Array(byteNumbers);
    const blob = new Blob([byteArray], { type: 'audio/mpeg' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'output.mp3';
    document.body.appendChild(a);
    a.click();
    URL.revokeObjectURL(url);
    console.log('Downloaded audio as output.mp3 from Base64 data');
  } else {
    console.log('No audio content returned.');
  }
} else {
  console.error('Error:', result.error);
}

Python (Requests)

python

import requests, base64

url = "https://luvvoice.com/api/v1/text-to-speech"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "text": "Hello, world! This is a test of the LuvVoice API.",
    "voice_id": "voice-001",
    "rate": 0,
    "pitch": 0,
    "volume": 0
}

response = requests.post(url, json=data, headers=headers)

if response.status_code == 200:
    result = response.json()
    if result.get("audio_url"):
        print("Audio URL:", result.get("audio_url"))
    elif result.get("audio_data"):
        with open("output.mp3", "wb") as f:
            f.write(base64.b64decode(result["audio_data"]))
        print("Saved audio to output.mp3 from Base64 data")
    else:
        print("No audio content returned")
else:
    print("Error:", response.json())

Rate Limiting

LuvVoice API implements multiple layers of rate limiting to ensure fair usage and prevent abuse:

Current Rate Limits:

• Per-minute limit: 10 requests per minute
• Per-second limit: 5 requests per second (burst protection)
• Per-10-seconds limit: 20 requests per 10 seconds (burst protection)
• Text limit: Maximum 20,000 characters per request

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 10

X-RateLimit-Remaining: 7

X-RateLimit-Reset: 45

X-RateLimit-Limit - Your rate limit per minute
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Seconds until rate limit resets

Burst Protection

To prevent abuse and ensure service stability, we implement burst protection:

• If you exceed 5 requests per second, you'll receive a 429 error immediately
• If you make more than 20 requests in 10 seconds, additional requests will be blocked
• These limits reset automatically and don't affect your minute-based quota
• Implement proper request spacing in your applications to avoid hitting these limits

Error Handling

HTTP Status Codes

Code	Status	Description
200	OK	Request successful
400	Bad Request	Invalid request parameters or text exceeds 20,000 characters
401	Unauthorized	Invalid or missing API token
402	Payment Required	Insufficient credits
403	Forbidden	API access denied (not Pro user)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error, try again later

Best Practices

• Always check the HTTP status code before processing the response
• Implement exponential backoff for 429 (rate limit) errors
• Space out your requests - Don't send more than 5 requests per second
• Add delays between requests - Use at least 200ms delay between consecutive calls
• Monitor rate limit headers to track your usage and avoid hitting limits
• Handle 402 errors by directing users to purchase more credits
• Store API tokens securely and rotate them regularly
• For batch processing, implement a queue system with proper throttling

Need Help?

Our team is here to help you build amazing voice applications with the LuvVoice API.

Get Your API Token Contact Support

LuvVoice API Documentation

Introduction

Base URL

Authentication

⚠️ Pro Plan Required

Getting Your API Token

Authorization Header Format:

Getting Available Voices

Request Example

Response Format

Voice Object Fields:

API Endpoint

Request Parameters

Available Voices

Get Voice List:

API Responses

Success Response (200 OK)

Response Fields:

Error Response

Code Examples

cURL

JavaScript (Fetch API)

Python (Requests)

Rate Limiting

Current Rate Limits:

Rate Limit Headers

Burst Protection

Error Handling

HTTP Status Codes

Best Practices

Need Help?