# API Endpoints Quick Reference

## Core Endpoints

### Health & Status
```
GET  /v1/health              → {status, model, device, ready}
GET  /                       → API info + all endpoints
```

### Models
```
GET  /v1/models              → List available models
GET  /v1/models/{id}/config  → Model configuration
GET  /v1/models/{id}/languages → Supported languages
```

### Text-to-Speech
```
POST /v1/audio/speech        → Generate audio (standard)
POST /v1/audio/speech/stream → Stream audio chunks
POST /v1/audio/convert       → Convert format/sample rate
```

## Extended Endpoints

### Voice Management
```
POST /v1/voices/upload       → Upload custom voice
GET  /v1/voices              → List all voices
DEL  /v1/voices/{id}         → Delete voice
```

### Text Processing
```
POST /v1/text/validate       → Validate text + duration estimate
```

### Batch Processing
```
POST /v1/batch/create        → Create batch job (async)
GET  /v1/batch/{id}          → Check batch status
GET  /v1/batch/{id}/results  → Get batch results
```

### Usage & Quotas
```
GET  /v1/usage               → Usage statistics
GET  /v1/quota               → Rate limits & remaining
```

---

## Common Request/Response Examples

### Basic TTS
```bash
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "language": "English"}'
```

### Stream TTS
```bash
curl -X POST http://localhost:8000/v1/audio/speech/stream \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}'
```

### Validate Text
```bash
curl -X POST http://localhost:8000/v1/text/validate \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "language": "English"}'
```

### Upload Voice
```bash
curl -X POST http://localhost:8000/v1/voices/upload \
  -F "name=Alice" \
  -F "language=English" \
  -F "ref_text=Reference text here" \
  -F "audio=@voice.wav"
```

### Create Batch
```bash
curl -X POST http://localhost:8000/v1/batch/create \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"text": "Item 1"},
      {"text": "Item 2"}
    ]
  }'
```

### Get Usage
```bash
curl http://localhost:8000/v1/usage
curl http://localhost:8000/v1/quota
```

### Convert Audio
```bash
curl -X POST http://localhost:8000/v1/audio/convert \
  -H "Content-Type: application/json" \
  -d '{
    "audio_base64": "...",
    "target_sample_rate": 16000
  }'
```

---

## Python Client Pattern

```python
import requests

API_URL = "http://localhost:8000"

# Health check
r = requests.get(f"{API_URL}/v1/health")
print(r.json())

# Generate
r = requests.post(f"{API_URL}/v1/audio/speech", 
    json={"text": "Hello"})
audio_b64 = r.json()["audio_base64"]

# Validate
r = requests.post(f"{API_URL}/v1/text/validate",
    json={"text": "Hello"})
print(r.json()["estimated_duration"])

# Usage
r = requests.get(f"{API_URL}/v1/usage")
print(r.json()["requests_made"])
```

---

## Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 400 | Bad request (validation) |
| 404 | Not found |
| 409 | Conflict (can't process) |
| 503 | Service unavailable |
| 500 | Server error |

---

## Limits

| Metric | Value |
|--------|-------|
| Requests/minute | 60 |
| Max text length | 10,000 chars |
| Max batch size | 100 items |
| Concurrent requests | 4 |
| Voice audio duration | 5-30s (recommended) |

---

## Response Format

**Success (200):**
```json
{
  "id": "req_xxx",
  "status": "success",
  "data": {...}
}
```

**Error:**
```json
{
  "error": "Description",
  "code": "error_code",
  "details": {...}
}
```

---

## Storage Locations

| Item | Location |
|------|----------|
| Custom voices | `assets/custom_voices/{voice_id}/` |
| Batch jobs | `assets/batch_jobs/{job_id}/` |
| Voice cloning ref | `assets/voice_cloning/` |

---

## Documentation Links

- **Interactive API Docs**: http://localhost:8000/docs
- **Extended Endpoints**: `api/EXTENDED_ENDPOINTS.md`
- **Code Examples**: `api/examples.py`
- **Implementation Details**: `api/IMPLEMENTATION_SUMMARY.md`

---

## Quick Start

```bash
# Install
pip install -e .

# Run
python start_api.py

# Test
python api/examples.py

# Browse
open http://localhost:8000/docs
```