Qwen3-TTS-streaming/API_QUICK_REFERENCE.md

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

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

Stream TTS

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

Validate Text

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

Upload Voice

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

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

Get Usage

curl http://localhost:8000/v1/usage
curl http://localhost:8000/v1/quota

Convert Audio

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

---

Python Client Pattern

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):

{
  "id": "req_xxx",
  "status": "success",
  "data": {...}
}

Error:

{
  "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

# Install
pip install -e .

# Run
python start_api.py

# Test
python api/examples.py

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