API Documentation

Authentication

All API requests require authentication using an API key. You can create API keys in the Developers dashboard.

Using your API key

Include your API key in the request header:

Option 1: X-API-Key header (recommended)

X-API-Key: sk_live_your_api_key_here

Option 2: Authorization header

Authorization: Bearer sk_live_your_api_key_here

Endpoints

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "audio_url": "https://storage.example.com/audio.wav",
  "audio_duration": 5.2,
  "char_count": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:15Z"
}

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Rachel",
    "description": "American female, warm and friendly",
    "voice_type": "preset",
    "category": "American",
    "preview_url": "https://storage.example.com/preview.wav"
  }
]

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Rachel",
  "description": "American female, warm and friendly",
  "voice_type": "preset",
  "category": "American",
  "preview_url": "https://storage.example.com/preview.wav"
}

{
  "chars_used_this_month": 500,
  "monthly_char_limit": 10000,
  "percentage_used": 50.0,
  "subscription_tier": "free"
}

Code Examples

cURL

# Generate speech
curl -X POST https://your-api-url/v1/tts \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world! This is a test.",
    "voice_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

# Check generation status
curl https://your-api-url/v1/generations/GENERATION_ID \
  -H "X-API-Key: sk_live_your_api_key"

# List voices
curl https://your-api-url/v1/voices \
  -H "X-API-Key: sk_live_your_api_key"

Python

import requests
import time

API_KEY = "sk_live_your_api_key"
BASE_URL = "https://your-api-url/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# List available voices
voices = requests.get(f"{BASE_URL}/voices", headers=headers).json()
print(f"Found {len(voices)} voices")

# Generate speech
response = requests.post(
    f"{BASE_URL}/tts",
    headers=headers,
    json={
        "text": "Hello, world! This is a test.",
        "voice_id": voices[0]["id"]
    }
)
generation = response.json()
print(f"Generation started: {generation['id']}")

# Poll for completion
while True:
    status = requests.get(
        f"{BASE_URL}/generations/{generation['id']}",
        headers=headers
    ).json()

    if status["status"] == "completed":
        print(f"Audio URL: {status['audio_url']}")
        break
    elif status["status"] == "failed":
        print(f"Error: {status.get('error_message')}")
        break

    time.sleep(2)

JavaScript / TypeScript

const API_KEY = "sk_live_your_api_key";
const BASE_URL = "https://your-api-url/v1";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json"
};

// List available voices
async function listVoices() {
  const response = await fetch(`${BASE_URL}/voices`, { headers });
  return response.json();
}

// Generate speech
async function generateSpeech(text: string, voiceId: string) {
  const response = await fetch(`${BASE_URL}/tts`, {
    method: "POST",
    headers,
    body: JSON.stringify({ text, voice_id: voiceId })
  });
  return response.json();
}

// Check generation status
async function getGeneration(id: string) {
  const response = await fetch(`${BASE_URL}/generations/${id}`, { headers });
  return response.json();
}

// Example usage
async function main() {
  const voices = await listVoices();
  console.log(`Found ${voices.length} voices`);

  const generation = await generateSpeech(
    "Hello, world! This is a test.",
    voices[0].id
  );
  console.log(`Generation started: ${generation.id}`);

  // Poll for completion
  let status;
  do {
    await new Promise(r => setTimeout(r, 2000));
    status = await getGeneration(generation.id);
  } while (status.status === "processing");

  if (status.status === "completed") {
    console.log(`Audio URL: ${status.audio_url}`);
  }
}

main();

Rate Limits

API requests are rate limited based on your subscription tier. Rate limits are applied per API key.

Rate Limit Headers

All API responses include headers indicating your current rate limit status:

• X-RateLimit-Limit: Maximum requests per minute
• X-RateLimit-Remaining: Requests remaining in the current window
• X-RateLimit-Reset: Seconds until the rate limit resets

If you exceed the rate limit, you'll receive a 429 response with a Retry-After header.

Error Codes

The API uses standard HTTP status codes and returns detailed error information in the response body.

Error Response Format

{
  "error": "voice_not_found",
  "message": "Voice with ID '550e8400-e29b-41d4-a716-446655440000' not found."
}