# Quickstart

Turn on the local API, copy your key and switch voices from a script in a few minutes.

Voices AI Live runs a small REST API on your computer while the app is open. Anything on the same machine can use it: a script, a Stream Deck or Streamer.bot action, a chat bot or your own app. This guide takes you from a fresh install to starting the voice changer from the command line.

## Turn on the API

1. Open **Settings** in Voices AI Live.
2. Under **General**, make sure **Stream Deck and other apps** is on. It's on by default.
3. The **Developer** section below now shows the endpoint, `http://127.0.0.1:19470`, and your API key. Click the copy button next to the key.

Keep the key in an environment variable, so it stays out of your scripts:

```bash
export VOICES_AI_API_KEY="paste-your-key-here"
```

## Check the connection

Ask for the current status. Every request sends the key as a Bearer token:

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

```json
{
  "state": "idle",
  "message": "Voice changer is stopped.",
  "voiceId": "voice_hannah"
}
```

A `401` means the key is missing or wrong. If the connection is refused, the app isn't open or the switch is off.

## Pick a voice

List the voices in your library and note the `id` of the one you want:

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

Then select it. The first time you pick a voice, the app downloads its model, which can take a few seconds:

```bash
curl -X POST http://127.0.0.1:19470/v1/voice \
  -H "Authorization: Bearer $VOICES_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"voice_hannah"}'
```

## Start and stop

Start the voice changer with your current microphone and output settings:

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

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

Stop it again with `POST /v1/stop`. Both calls are safe to repeat: starting a running voice changer just returns its status.

## Next steps

- Follow changes as they happen with [Stream realtime events](/reference/stream-events), so your integration stays in sync when someone uses the app itself.
- Trade quality for latency with [Set voice quality mode](/reference/set-quality).
- Create a voice from a recording with [Create a custom voice](/reference/create-custom-voice).
