# 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"
```

> **Note:** 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

1. 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>"
   }
   ```
2. The server streams binary audio chunks (PCM16 at 24kHz mono).
3. 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](/guides/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.