# Start the voice changer

`POST http://127.0.0.1:19470/v1/start`

Starts the voice changer using the currently configured audio devices and voice model.
If it is already running, this is a no-op that returns the current status.

Authenticate with `Authorization: Bearer <API key>` (key from Settings > Developer in Voices AI Live).

## Responses

### 200: Voice changer started successfully

- `ok` (boolean, required)
- `status` (EngineStatus): The voice changer status after an action
  - `state` (string, required): Current state of the voice changer One of: `idle`, `starting`, `running`, `stopping`, `error`.
  - `message` (string, required)
  - `startedAt` (integer or null): When the current run started, in milliseconds since the Unix epoch
  - `updatedAt` (integer): When this status was set, in milliseconds since the Unix epoch
  - `latencyMs` (integer or null): How far the changed voice lags behind your microphone, in milliseconds: the measured end-to-end delay, smoothed and rounded to 10 ms. Null while the voice changer isn't running. Delay your camera by this much (for example with a video delay filter in OBS) to keep it in sync with your voice.
- `state` (string): Only when Start is refused because no voice is selected One of: `idle`, `starting`, `running`, `stopping`, `error`.
- `error` (string or null): Why the action failed; null or absent when `ok` is `true`

```json
{
  "ok": true,
  "status": {
    "state": "running",
    "message": "Voice changer is running.",
    "startedAt": 1793750400000,
    "updatedAt": 1793750400000
  }
}
```

### 400: Failed to start, e.g. no voice selected yet or the engine could not start

- `ok` (boolean, required)
- `status` (EngineStatus): The voice changer status after an action
  - `state` (string, required): Current state of the voice changer One of: `idle`, `starting`, `running`, `stopping`, `error`.
  - `message` (string, required)
  - `startedAt` (integer or null): When the current run started, in milliseconds since the Unix epoch
  - `updatedAt` (integer): When this status was set, in milliseconds since the Unix epoch
  - `latencyMs` (integer or null): How far the changed voice lags behind your microphone, in milliseconds: the measured end-to-end delay, smoothed and rounded to 10 ms. Null while the voice changer isn't running. Delay your camera by this much (for example with a video delay filter in OBS) to keep it in sync with your voice.
- `state` (string): Only when Start is refused because no voice is selected One of: `idle`, `starting`, `running`, `stopping`, `error`.
- `error` (string or null): Why the action failed; null or absent when `ok` is `true`

```json
{
  "ok": false,
  "state": "idle",
  "error": "No voice selected. Use POST /v1/voice first."
}
```

### 401: Invalid or missing API key

- `error` (string, required): Error message

```json
{
  "error": "Invalid or missing API key"
}
```

## Examples

```bash
curl -X POST http://127.0.0.1:19470/v1/start \
  -H "Authorization: Bearer $VOICES_AI_API_KEY"
```

```javascript
const res = await fetch('http://127.0.0.1:19470/v1/start', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`,
  },
});
const data = await res.json();
```

```python
import os
import requests

res = requests.post(
    "http://127.0.0.1:19470/v1/start",
    headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"},
)
print(res.json())
```
