# Select a voice

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

Sets the active voice by its ID. Use `GET /v1/voices` to list available voice IDs,
or `GET /v1/custom-voices` for your custom voices.

If the voice model is not yet downloaded locally, it will be downloaded
automatically. This may take a few seconds on the first call for a given voice.

Effects such as Clean Mic and Robot have nothing to download. While the voice
changer runs, switching between an effect and an AI voice restarts it; within
one kind it switches live.

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

## Request body (application/json)

- `id` (string, required): Voice ID from the voice library

```json
{
  "id": "voice_james"
}
```

## Responses

### 200: Voice set successfully

- `ok` (boolean, required)
- `error` (string): Present only when `ok` is `false`

```json
{
  "ok": true
}
```

### 400: Invalid body, or the voice model could not be downloaded or applied

- `ok` (boolean, required)
- `error` (string): Present only when `ok` is `false`

```json
{
  "ok": false,
  "error": "Voice integrity metadata is unavailable."
}
```

### 401: Invalid or missing API key

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

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

### 404: Voice ID not found in the library

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

```json
{
  "error": "Voice \"unknown_id\" not found."
}
```

### 503: The desktop app is not signed in

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

```json
{
  "error": "Open the desktop app and sign in before using the local API."
}
```

## Examples

```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_james"}'
```

```javascript
const res = await fetch('http://127.0.0.1:19470/v1/voice', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id: 'voice_james'
  }),
});
const data = await res.json();
```

```python
import os
import requests

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