# VoiceStudio API Endpoints: Complete FastAPI Backend Reference

> Explore the complete VoiceStudio API reference. Discover over 50 FastAPI endpoints for engine management, audio generation, speech processing, batch jobs, and OpenAI integrations.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: api-reference
- Published: 2026-09-11

---

**The VoiceStudio backend exposes over 50 RESTful endpoints organized into specialized FastAPI routers covering engine management, audio generation, speech processing, batch jobs, and OpenAI-compatible interfaces.**

VoiceStudio is an open-source voice synthesis and processing platform built on FastAPI. This comprehensive guide maps every available **VoiceStudio API endpoint** across the backend router modules, providing exact file paths, HTTP methods, and integration patterns for building applications with the speech pipeline.

## Engine Management and Health Checks

The **Engine Management** routes in [`backend/api/routers/engines.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/engines.py) serve as the central hub for discovering and configuring speech backends. These endpoints handle **TTS** (Text-to-Speech), **ASR** (Automatic Speech Recognition), **LLM**, and translation engines.

Key endpoints include:

- **List engines**: `GET /engines` returns all available engine families, while `GET /engines/tts`, `GET /engines/asr`, and `GET /engines/llm` filter by category.
- **Select backend**: `POST /engines/select` persists a backend choice for subsequent operations.
- **Health monitoring**: `GET /engines/{engine_id}/health` performs a liveness check on a specific backend instance.
- **Translation management**: `GET /engines/translation` lists available translation engines, with `POST /engines/translation/{engine_id}/install` and `DELETE /engines/translation/{engine_id}` managing their lifecycle.

```python
import requests

# Check TTS engine availability

response = requests.get("http://localhost:8000/engines/tts")
available_engines = response.json()

# Verify engine health

health = requests.get(f"http://localhost:8000/engines/{engine_id}/health")
print(health.json()["status"])

```

## Worker Orchestration

In [`backend/api/routers/workers.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/workers.py), the **Worker Control** endpoints manage the distributed processing pool. Workers handle compute-intensive tasks like model inference and audio rendering.

- `GET /workers` – Lists active workers and their current load.
- `POST /workers` – Spawns a new worker process.
- `GET /workers/{worker_id}` – Retrieves detailed status for a specific worker.
- `POST /workers/{worker_id}/join` – Joins a worker to the control plane.
- `POST /workers/{worker_id}/shutdown` – Gracefully stops a worker.

These routes include dependencies like `Depends(require_admin)` to protect administrative actions.

```python

# Spawn a new worker

new_worker = requests.post("http://localhost:8000/workers")
worker_id = new_worker.json()["worker_id"]

# Shutdown worker when complete

requests.post(f"http://localhost:8000/workers/{worker_id}/shutdown")

```

## Audio Generation and Streaming

The **Audio Generation** router in [`backend/api/routers/generation.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/generation.py) handles asynchronous TTS job submission, while [`backend/api/routers/tts_stream.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/tts_stream.py) provides **Server-Sent Events (SSE)** for real-time audio delivery.

**Generation endpoints**:
- `POST /generation` – Submits a TTS generation job and returns a `job_id`.
- `GET /generation/{job_id}/status` – Polls job progress.
- `GET /generation/{job_id}/result` – Retrieves the final audio file.
- `POST /generation/{job_id}/cancel` – Aborts a running job.

**Streaming endpoints**:
- `GET /tts_stream/{task_id}` – Opens an SSE connection that streams progressive audio chunks as they are generated.

```python
import requests

# Submit generation job

job = requests.post("http://localhost:8000/generation", json={
    "text": "Hello world",
    "voice_id": "en-US-Aria"
})
job_id = job.json()["job_id"]

# Stream chunks via SSE

url = f"http://localhost:8000/tts_stream/{job_id}"
with requests.get(url, stream=True) as r:
    for line in r.iter_lines():
        if line:
            process_audio_chunk(line)

```

## Speech-to-Text and Text-to-Speech

The **Speech Platform** router in [`backend/api/routers/speech_platform.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/speech_platform.py) provides a unified service layer for synchronous speech operations:

- `POST /speech_platform/tts` – Synthesizes speech immediately (blocking).
- `POST /speech_platform/stt` – Transcribes uploaded audio.

For **Capture and Acoustic Echo Cancellation (AEC)**, [`backend/api/routers/capture.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/capture.py) and [`backend/api/routers/capture_ws.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/capture_ws.py) offer:

- `POST /capture` – Records audio capture.
- `GET /capture_ws` – WebSocket endpoint for live audio streaming with AEC processing.

```python

# Synchronous TTS

response = requests.post("http://localhost:8000/speech_platform/tts", 
    json={"text": "Processing complete"})
audio_data = response.content

```

## OpenAI Compatibility Layer

VoiceStudio provides drop-in compatibility with OpenAI clients through [`backend/api/routers/openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/openai_compat.py). This router maps standard OpenAI audio endpoints to VoiceStudio's internal pipeline:

- `POST /v1/audio/tts` – OpenAI-compatible TTS endpoint accepting `model`, `voice`, and `input` parameters.
- `POST /v1/audio/transcriptions` – OpenAI-compatible STT endpoint for transcription requests.

This allows existing applications using OpenAI SDKs to switch to VoiceStudio by changing only the base URL.

## Dubbing, Audiobook, and Batch Processing

For complex production workflows, VoiceStudio organizes functionality across multiple specialized routers.

**Dub & Export** ([`backend/api/routers/dub_core.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/dub_core.py), [`dub_generate.py`](https://github.com/debpalash/VoiceStudio/blob/main/dub_generate.py), [`dub_export.py`](https://github.com/debpalash/VoiceStudio/blob/main/dub_export.py)):
- `POST /dub_core/submit` – Submits a dubbing request with source and target languages.
- `GET /dub_generate/{task_id}/status` – Streams generation status.
- `GET /dub_export/{task_id}/file` – Downloads the exported dubbed file.

**Long-Form Content** ([`backend/api/routers/audiobook.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/audiobook.py), [`longform_jobs.py`](https://github.com/debpalash/VoiceStudio/blob/main/longform_jobs.py)):
- `POST /audiobook` – Creates an audiobook production job.
- `GET /audiobook/{task_id}/stream` – SSE stream of completed chapters.

**Batch Processing** ([`backend/api/routers/batch.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/batch.py)):
- `POST /batch` – Submits multiple generation jobs as a single batch.
- `GET /batch/{batch_id}/status` – Monitors overall batch progress.

## System Administration and Settings

Administrative endpoints reside in [`backend/api/routers/system.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/system.py) and [`backend/api/routers/settings.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/settings.py):

- `GET /system/info` – Returns runtime information.
- `POST /system/restart` – Triggers process restart (admin-only).
- `GET /settings` – Retrieves user preferences.
- `POST /settings` – Updates configuration.

**Media Tools** ([`backend/api/routers/media_tools.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/media_tools.py)) provide utility functions:
- `POST /media_tools/convert` – Converts between audio/video formats.
- `GET /media_tools/metadata` – Probes file metadata.

## Authentication, Profiles, and Utilities

Security routes in [`backend/api/routers/auth.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/auth.py) handle session management:
- `POST /auth/login` – Authenticates users.
- `POST /auth/logout` – Terminates sessions.

The **Profiles** router ([`backend/api/routers/profiles.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/profiles.py)) manages user-specific configurations:
- `GET /profiles` – Lists profiles.
- `POST /profiles` – Creates or modifies a profile.

Additional utility endpoints include:
- `POST /watermark/apply` – Embeds watermarks into audio ([`backend/api/routers/watermark.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/watermark.py)).
- `POST /community/feedback` – Submits user feedback ([`backend/api/routers/community.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/community.py)).
- `POST /dictation` – Processes dictation text ([`backend/api/routers/dictation.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/dictation.py)).

## Summary

- VoiceStudio organizes its **FastAPI** backend into modular routers under `backend/api/routers/`, each handling specific functional domains.
- **Engine management** endpoints in [`engines.py`](https://github.com/debpalash/VoiceStudio/blob/main/engines.py) control TTS, ASR, LLM, and translation backends with health monitoring.
- **Audio generation** supports both synchronous (`/generation`) and streaming (`/tts_stream`) patterns via SSE.
- **OpenAI compatibility** is provided through [`openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/openai_compat.py), enabling drop-in replacement for OpenAI audio APIs.
- **Worker orchestration** allows dynamic scaling of inference workers through the [`workers.py`](https://github.com/debpalash/VoiceStudio/blob/main/workers.py) routes.
- **Dubbing**, **audiobook production**, and **batch processing** provide enterprise-grade workflow automation.

## Frequently Asked Questions

### How do I check if a specific TTS engine is healthy?

Send a `GET` request to `/engines/{engine_id}/health` as defined in [`backend/api/routers/engines.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/engines.py). This endpoint performs a liveness check on the backend instance and returns a status object indicating whether the engine is ready to accept generation jobs.

### What is the difference between `/generation` and `/tts_stream` endpoints?

The `/generation` endpoint in [`backend/api/routers/generation.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/generation.py) works asynchronously—you submit a job and poll for completion—while `/tts_stream` in [`backend/api/routers/tts_stream.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/tts_stream.py) uses **Server-Sent Events (SSE)** to deliver audio chunks progressively as they are synthesized, enabling real-time playback.

### Does VoiceStudio support OpenAI-compatible API clients?

Yes. The [`backend/api/routers/openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/openai_compat.py) module exposes `POST /v1/audio/tts` and `POST /v1/audio/transcriptions`, which accept the same request schemas as OpenAI's audio endpoints. You can use VoiceStudio as a backend for existing OpenAI SDK implementations by pointing the base URL to your VoiceStudio instance.

### How are batch jobs submitted and monitored?

Submit a batch by sending a `POST` request to `/batch` with a list of generation tasks. The endpoint returns a `batch_id` that you can use with `GET /batch/{batch_id}/status` to track overall progress. This functionality is implemented in [`backend/api/routers/batch.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/batch.py) and supports parallel processing of multiple audio generation tasks.