ScriptCast TTS API

A production-ready, self-hosted Text-to-Speech API powered by Coqui XTTS-v2 with voice cloning, multi-language support, and a beautiful admin dashboard. Deploy for free on HuggingFace Spaces!

---

Features

• High-Quality TTS - XTTS-v2 model for natural-sounding speech
• 17 Languages - English, Hindi, Spanish, French, German, Japanese, Chinese, and more
• Voice Cloning - Clone any voice from 6-30 second audio samples
• Admin Dashboard - Beautiful UI to manage API keys and view usage analytics
• Multi-Tier Auth - Owner + Friends access system with rate limiting
• Async Processing - Queue long texts for background processing
• Audio Caching - Automatic caching for repeated requests
• Usage Analytics - Track requests, characters, audio minutes, languages, and voices
• 100% Free - Deploy on HuggingFace Spaces at no cost

---

Quick Deploy to HuggingFace Spaces

Step 1: Create a HuggingFace Space

1. Go to HuggingFace Spaces
2. Click "Create new Space"
3. Configure:
   • Space name: scriptcast (or any name you prefer)
   • SDK: Docker
   • Visibility: Public (recommended) or Private
4. Click "Create Space"

Step 2: Generate Your Secure Tokens

Run this Python script locally to generate secure tokens:

import secrets

print("=" * 60)
print("YOUR SCRIPTCAST API TOKENS - SAVE THESE SECURELY!")
print("=" * 60)
print(f"\nOWNER_TOKEN={secrets.token_urlsafe(32)}")
print(f"OWNER_NAME=YourName")
print()
for i in range(1, 6):
    print(f"FRIEND_{i}_TOKEN={secrets.token_urlsafe(32)}")
    print(f"FRIEND_{i}_NAME=Friend{i}")
print("\n" + "=" * 60)

Important: Save these tokens securely! You'll need them to access your API.

Step 3: Configure Space Secrets

In your HuggingFace Space:

1. Go to Settings > Repository secrets
2. Add these secrets:

Secret Name	Description
OWNER_TOKEN	Your master access token (unlimited access)
OWNER_NAME	Your display name
FRIEND_1_TOKEN	Friend 1's access token
FRIEND_1_NAME	Friend 1's display name
FRIEND_2_TOKEN	Friend 2's access token (optional)
...	Add up to 5 friends

Step 4: Clone and Push Code

# Clone this repository
git clone https://github.com/arnav-144p/scriptcast.git
cd scriptcast

# Clone your HuggingFace Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME hf-space
cd hf-space

# Copy all files
cp -r ../scriptcast/* .

# Push to HuggingFace
git add -A
git commit -m "Initial deployment"
git push origin main

Step 5: Wait & Access

• Build time: 5-10 minutes
• First TTS request: Model downloads (~2GB), takes 2-3 minutes
• Dashboard: https://YOUR_USERNAME-YOUR_SPACE.hf.space/static/index.html

---

Local Development

Prerequisites

• Python 3.10 or higher
• FFmpeg installed on your system
• CUDA-capable GPU (optional, for faster inference)

Installation

# Clone the repository
git clone https://github.com/arnav-144p/scriptcast.git
cd scriptcast

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/Mac:
source venv/bin/activate
# Windows:
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
# Linux/Mac:
export OWNER_TOKEN="your_secure_token_here"
export OWNER_NAME="YourName"
export DATA_DIR="./data"

# Windows PowerShell:
$env:OWNER_TOKEN="your_secure_token_here"
$env:OWNER_NAME="YourName"
$env:DATA_DIR="./data"

# Run the server
uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload

Docker

# Build the image
docker build -t scriptcast .

# Run the container
docker run -p 7860:7860 \
  -e OWNER_TOKEN="your_token_here" \
  -e OWNER_NAME="YourName" \
  -v $(pwd)/data:/data \
  scriptcast

---

API Reference

Authentication

All endpoints (except /health) require authentication. Pass your token in the key header:

curl -H "key: YOUR_API_KEY" https://your-space.hf.space/voices

Core Endpoints

POST /tts - Generate Speech

Convert text to speech audio.

curl -X POST "https://your-space.hf.space/tts" \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test!",
    "voice": "default",
    "language": "en",
    "format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

Parameters:

Parameter	Type	Default	Description
text	string	required	Text to synthesize (max 5000 chars)
voice	string	"default"	Voice ID
language	string	"en"	Language code
format	string	"mp3"	Output format: "mp3" or "wav"
speed	float	1.0	Speech speed (0.5-2.0)
async_mode	bool	false	Return job_id for async processing

GET /voices - List Available Voices

curl -H "key: YOUR_API_KEY" "https://your-space.hf.space/voices"

Response:

{
  "voices": [
    {"voice_id": "default", "description": "Built-in default voice", "type": "built-in"},
    {"voice_id": "female_1", "description": "Built-in female voice 1", "type": "built-in"},
    {"voice_id": "my_clone", "description": "Cloned voice: my_clone", "type": "cloned"}
  ],
  "total": 3
}

POST /clone - Clone a Voice

Upload audio to create a custom voice.

curl -X POST "https://your-space.hf.space/clone" \
  -H "key: YOUR_API_KEY" \
  -F "audio=@sample.wav" \
  -F "name=my_voice" \
  -F "description=My custom cloned voice"

Requirements:

• Audio: WAV or MP3 format
• Duration: 6-30 seconds (ideal), 3-60 seconds (allowed)
• Quality: Clear speech, minimal background noise

GET /languages - List Supported Languages

curl -H "key: YOUR_API_KEY" "https://your-space.hf.space/languages"

API Key Management

POST /keys - Create API Key

Create a new API key (requires master token).

curl -X POST "https://your-space.hf.space/keys" \
  -H "key: YOUR_MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'

GET /keys - List Your API Keys

curl -H "key: YOUR_MASTER_TOKEN" "https://your-space.hf.space/keys"

DELETE /keys/{key_id} - Revoke API Key

curl -X DELETE "https://your-space.hf.space/keys/123" \
  -H "key: YOUR_MASTER_TOKEN"

Analytics

GET /stats - Usage Statistics

curl -H "key: YOUR_API_KEY" "https://your-space.hf.space/stats"

Response:

{
  "total_requests": 150,
  "total_audio_seconds": 3600.5,
  "total_characters": 50000,
  "language_usage": {"en": 100, "hi": 30, "es": 20},
  "voice_usage": {"default": 120, "my_clone": 30}
}

GET /usage - Recent Usage History

curl -H "key: YOUR_API_KEY" "https://your-space.hf.space/usage?limit=10"

Full API Documentation

Interactive Swagger docs available at: https://your-space.hf.space/docs

---

Supported Languages

Code	Language	Code	Language
en	English	ko	Korean
es	Spanish	ja	Japanese
fr	French	zh-cn	Chinese (Simplified)
de	German	ar	Arabic
it	Italian	hi	Hindi
pt	Portuguese	pl	Polish
ru	Russian	tr	Turkish
nl	Dutch	cs	Czech
hu	Hungarian