Reference

Local API Reference

Reference documentation for integrating with the VoiceStudio local HTTP API.

VoiceStudio provides a local HTTP and WebSocket API. Use it to integrate voice generation and dictation into your own applications.

Authentication and network security#

The backend listens on the local loopback interface by default. It requires no authentication. Applications running on the same machine call the API directly.

To access the API from another device, a reverse proxy, or a Docker container, configure authentication. Set the OMNIVOICE_API_KEY environment variable to a secure random string.

Send the key in your requests using the Authorization header:

Bash

curl http://<host>:3900/v1/audio/speech \
  -H "Authorization: Bearer $OMNIVOICE_API_KEY"

Admin routes and model management are separated from consumption routes. Admin actions always require the API key or local loopback access.

Add your frontend's exact origin to OMNIVOICE_ALLOWED_ORIGINS to pass CORS checks if you call the API from a browser frontend hosted on a different origin.

OpenAI-compatible endpoints#

VoiceStudio provides drop-in replacement endpoints for OpenAI's audio APIs. Use standard SDKs by pointing the base URL to your VoiceStudio instance.

Text-to-speech#

POST /v1/audio/speech

Generates audio from text using the active TTS engine.

JSON

{
  "model": "<tts-engine-id>",
  "voice": "alloy",
  "input": "Hello from VoiceStudio.",
  "response_format": "wav"
}

Transcription#

POST /v1/audio/transcriptions

Transcribes an uploaded audio file using the active dictation model. Pass the file via multipart/form-data.

Bash

curl http://localhost:3900/v1/audio/transcriptions \
  -H "Authorization: Bearer $OMNIVOICE_API_KEY" \
  -F "file=@audio.wav" \
  -F "model=<asr-engine-id>"

Real-time TTS WebSocket#

Use the streaming WebSocket API for ultra-low-latency applications. This endpoint streams audio chunks as soon as the first sentence generates.

Endpoint: ws://<host>:3900/ws/tts

Protocol#

The client sends a JSON request:

JSON

{
  "text": "The text to synthesize.",
  "voice": "<profile_id_or_preset>",
  "speed": 1.0,
  "language": "en",
  "engine": "<optional_engine_override>"
}

The server streams binary audio chunks (PCM16 at 24kHz mono).

The server sends a JSON status message when generation finishes:

JSON

{
  "type": "done",
  "duration_s": 4.2,
  "gen_time_s": 1.1
}

Errors or CPU fallback notices arrive as JSON messages before the audio streams.

System diagnostics#

GET /system/info: Returns application configuration, data directories, active models, and overall host specifications.
GET /sysinfo: Returns real-time resource utilization, including CPU usage, RAM, VRAM, and GPU load.
POST /system/flush-memory: Unloads inactive models to free RAM and VRAM.
GET /system/logs: Retrieves recent backend application logs.
GET /engines/effects/presets: Lists available DSP effect presets.

Models and setup#

Manage active dependencies and models directly through the API.

GET /models: Lists available models, their installation status, and disk size.
POST /models/install: Downloads and installs a model. Send {"repo_id": "<model_id>"}. Wait for /setup/download-stream to finish.
DELETE /models/{repo_id}: Uninstalls a model and frees disk space.
GET /setup/preflight: Runs system checks and returns hardware capabilities, GPU routing status, and missing dependencies.

Dubbing and translation#

Integrate with video dubbing features using timed segment jobs.

Translation: Translates subtitle segments. Requests include segment timings, text, optional regional dialects, and delivery directions. Set quality="cinematic" for LLM-backed refinement.
Dubbing: Requests accept a list of segments containing text, timing, voice profile overrides, and DSP effect presets. Specify a timing_strategy (like concise, smart_fit, or stretch_video) to control how audio fits within the available video slots.