docs: add README with API documentation

2026-04-08 01:36:25 +02:00
parent 879f770927
commit ad844e986a
1 changed files with 132 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,132 @@
+# TTS-VC API
+
+Flask REST API for Text-to-Speech with Voice Conversion using Edge-TTS and Seed-VC.
+
+## Features
+
+- **Text-to-Speech**: Convert text to speech using Edge-TTS (Russian female voice)
+- **Voice Conversion**: Apply voice cloning using Seed-VC model
+- **Reference Voices**: Upload and manage reference voice samples
+- **OpenAPI/Swagger**: Interactive API documentation
+- **Token-based Auth**: Secure API access
+
+## API Endpoints
+
+| Endpoint | Method | Description | Auth |
+|----------|--------|-------------|------|
+| `/health` | GET | Health check | No |
+| `/voices` | GET | List all voices | Yes |
+| `/voices/upload` | POST | Upload new voice | Yes |
+| `/tts` | POST | Convert text to speech | Yes |
+
+## Quick Start
+
+### 1. Clone and Setup
+
+```bash
+git clone https://git.azimkin.dev/Azimkin/tts-vc-api.git
+cd tts-vc-api
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 2. Configure
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+```
+API_TOKENS=your-secret-token
+VOICES_DIR=./voices
+OUTPUT_DIR=./output
+EDGE_TTS_VOICE=ru-RU-SvetlanaNeural
+FLASK_PORT=5000
+```
+
+### 3. Run
+
+```bash
+python run.py
+```
+
+API will be available at `http://localhost:5000`
+Swagger UI: `http://localhost:5000/swagger-ui`
+
+## Usage Examples
+
+### Health Check
+
+```bash
+curl http://localhost:5000/health
+```
+
+### Upload Reference Voice
+
+```bash
+curl -X POST http://localhost:5000/voices/upload \
+  -H "Authorization: Bearer your-token" \
+  -F "file=@reference.wav" \
+  -F "name=My Voice"
+```
+
+### List Voices
+
+```bash
+curl http://localhost:5000/voices \
+  -H "Authorization: Bearer your-token"
+```
+
+### Text-to-Speech
+
+```bash
+curl -X POST http://localhost:5000/tts \
+  -H "Authorization: Bearer your-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Привет, мир!",
+    "voice_id": "voice-id-from-upload",
+    "speed": 1.0
+  }' \
+  --output output.wav
+```
+
+## Architecture
+
+```
+project/
+├── app/
+│   ├── api/           # API endpoints (Flask-RESTX)
+│   ├── services/      # Business logic (TTS, VC)
+│   ├── models/        # Data models
+│   └── config.py      # Configuration
+├── voices/            # Reference voices storage
+├── output/            # Generated audio temp storage
+└── run.py             # Entry point
+```
+
+## Tech Stack
+
+- **Framework**: Flask + Flask-RESTX
+- **TTS**: edge-tts
+- **Voice Conversion**: Seed-VC (seed-uvit-whisper-small-wavenet)
+- **Auth**: Token-based from .env
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_TOKENS` | Comma-separated valid tokens | - |
+| `VOICES_DIR` | Reference voices directory | `./voices` |
+| `OUTPUT_DIR` | Output audio directory | `./output` |
+| `EDGE_TTS_VOICE` | Edge-TTS voice | `ru-RU-SvetlanaNeural` |
+| `FLASK_PORT` | Server port | `5000` |
+| `FLASK_DEBUG` | Debug mode | `false` |
+
+## License
+
+MIT