Technical

API Reference

Complete documentation for the Emotional TTS REST API. The backend is built with FastAPI and runs on port 8000.

Base URL: http://localhost:8080 · Swagger UI: http://localhost:8080/docs

Endpoints

GET/health

Check service status and model readiness.

Responsejson

{
  "status": "ok",
  "model_loaded": true,
  "active_jobs": 0,
  "cuda": true
}

curl http://localhost:8080/health

GET/emotions

List all supported emotions for vector-based control.

Responsejson

{
  "emotions": ["happy", "angry", "sad", "afraid", "disgusted", "melancholic", "surprised", "calm"]
}

curl http://localhost:8080/emotions

POST/stream_tts_vec

Streaming TTS with emotion vector control. Returns WAV audio stream.

Parameters (multipart/form-data)

Field	Type	Required	Description
speaker_file	File	Yes	Speaker reference audio
text	string	Yes	Text to synthesize
emotion	string	No	Emotion name (default: "calm")
emo_alpha	float	No	Emotion intensity (default: 1.0)

curl -X POST http://localhost:8080/stream_tts_vec \
  -F "speaker_file=@speaker.wav" \
  -F "text=Hello, I am very happy today!" \
  -F "emotion=happy" \
  -F "emo_alpha=1.0" \
  --output output.wav

POST/stream_tts

Streaming TTS without explicit emotion control. Uses speaker reference only.

Parameters (multipart/form-data)

Field	Type	Description
speaker_file	File	Speaker reference audio
text	string	Text to synthesize

curl -X POST http://localhost:8080/stream_tts \
  -F "speaker_file=@speaker.wav" \
  -F "text=This is a neutral synthesis test." \
  --output output.wav

POST/generate_vector

Batch TTS generation with emotion vector. Returns job ID for async processing.

Returns HTTP 202 with a job ID. Use GET /jobs/{job_id} to check status.

Parameters (multipart/form-data)

Field	Type	Description
audio_files	File[]	Speaker reference audio files
texts	string[]	Texts to synthesize
emotion	string	Emotion name (default: "calm")

Response (202)json

{ "job_id": "550e8400-e29b-41d4-a716-446655440000" }

POST/generate_ref

Batch TTS generation with emotion reference audio. Returns job ID.

Parameters (multipart/form-data)

Field	Type	Description
speaker_files	File[]	Speaker reference audio files
emotion_files	File[]	Emotion reference audio files
texts	string[]	Texts to synthesize

GET/jobs/{job_id}

Check status of an async generation job.

Responsejson

{
  "job_id": "550e8400-...",
  "status": "done",
  "total": 2,
  "completed": 2,
  "results": [
    { "index": 0, "output": "/app/outputs/..._0.wav", "status": "done" },
    { "index": 1, "output": "/app/outputs/..._1.wav", "status": "done" }
  ],
  "created_at": 1719849600.0,
  "error": null
}

GET/download/{job_id}/{index}

Download generated audio file from a completed job.

Returns a WAV audio file.

curl http://localhost:8080/download/550e8400-.../0 --output result.wav

GET/stream_result/{job_id}

Download the final saved audio from a streaming TTS session.

Returns the complete WAV file after streaming has finished.

DELETE/jobs/{job_id}

Delete a job and its output files.

Returns HTTP 204 on success.

curl -X DELETE http://localhost:8080/jobs/550e8400-...

Error Handling

Status	Meaning
400	Invalid input (missing fields, wrong format, mismatched counts)
404	Job or resource not found
410	Output file expired (auto-cleaned after 2 hours)
503	Model not yet loaded (startup in progress)