# Voice, Audio, Vision, And Voicechat

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/voice/state` | Voice runtime status |
| `GET` | `/v1/voice/models` | List TTS voice models |
| `POST` | `/v1/voice/models/switch` | Switch active TTS model |
| `GET`/`PUT` | `/v1/voice/supertonic-settings` | Voice tuning settings |
| `GET` | `/v1/voice/asr-models` | List Whisper ASR models |
| `POST` | `/v1/voice/asr-models/switch` | Switch active ASR model |
| `POST` | `/v1/voice/tts` | Synthesize text |
| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |
| `POST` | `/v1/voice/transcribe` | Transcribe audio |
| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |
| `POST` | `/v1/voice/transcribe/stream` | Streaming transcription |
| `GET` | `/v1/voice/clone-refs` | List clone references |
| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |
| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference server-side |
| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |
| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |
| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |
| `POST` | `/v1/voice/speak` | Synthesize and broadcast to voicechat clients |
| `WS` | `/v1/voicechat/ws` | Full-duplex voicechat WebSocket |
| `POST` | `/v1/vision/describe` | Vision describe placeholder/deferred endpoint |

## TTS

`POST /v1/voice/tts` returns audio bytes. `format` can be `wav` or `pcm`. `X-Sample-Rate` reports the sample rate.

OpenAI-compatible alias:

```text
POST /v1/audio/speech
```

## ASR

`POST /v1/voice/transcribe` transcribes uploaded audio. The OpenAI-compatible alias is:

```text
POST /v1/audio/transcriptions
```

## Voicechat WebSocket

`/v1/voicechat/ws` supports full-duplex realtime voice.

Client to server:

- Binary PCM Int16 mono 16 kHz mic audio.
- JSON text frame `{ "type": "start" }`.
- JSON text frame `{ "type": "stop" }`.
- JSON text frame `{ "type": "speak", "text": "..." }`.
- JSON text frame `{ "type": "ping" }`.

Server to client:

- `hello`
- `loaded`
- `transcript`
- `agent_text`
- `tts_header`
- binary TTS PCM
- `tts_start`
- `tts_end`
- `state`
- `session_state`
- `error`
- `keepalive`
- `pong`
- `session_started`
- `session_stopped`

Each binary TTS batch is preceded by a `tts_header` frame that announces the sample rate.

## Realtime REST Plus Voice

For ASR/TTS clients that do not use `/v1/voicechat/ws`, call `/v1/chat` with `realtime: true` and send the text transcript as `message`.
