# Create a custom voice

`POST http://127.0.0.1:19470/v1/custom-voices`

Creates a custom voice from a local audio or video file, the same way as
the in-app recorder: the app converts the file and keeps the clearest
5 to 15 seconds of speech. Needs an active subscription and a signed-in
desktop app. Long videos can take up to a minute; requests time out
after three minutes.

The new voice is in `GET /v1/voices` and `GET /v1/custom-voices` when
this returns, and can be selected with `POST /v1/voice`.

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

## Request body (application/json)

- `name` (string, required)
- `audioPath` (string, required): Absolute path to an audio or video file on this machine (up to 200 MB) with at least 5 seconds of clear speech
- `imagePath` (string): Optional absolute path to an avatar image (up to 20 MB), cropped to a square

```json
{
  "name": "My voice",
  "audioPath": "/Users/me/Desktop/sample.m4a"
}
```

## Responses

### 200: Custom voice created

- `ok` (boolean, required)
- `voice` (CustomVoice, required)
  - `id` (string, required): Voice ID for `POST /v1/voice` and `DELETE /v1/custom-voices/{id}`
  - `name` (string, required)
  - `imageUrl` (string or null, required): Avatar URL, or null when the voice has no image

```json
{
  "ok": true,
  "voice": {
    "id": "3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10",
    "name": "My voice",
    "imageUrl": null
  }
}
```

### 400: Invalid fields, a missing or unreadable file, or audio without enough clear speech

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

```json
{
  "ok": false,
  "error": "The audio needs at least 5 seconds of clear speech."
}
```

### 401: Invalid or missing API key

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

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

### 403: The account needs an active subscription

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

```json
{
  "ok": false,
  "error": "Custom voices need an active subscription."
}
```

### 409: The account has reached its custom voice limit

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

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

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

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

### 504: The desktop app did not finish the request in time

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

```json
{
  "ok": false,
  "error": "The desktop app did not respond in time. Keep it open and signed in."
}
```

## Examples

```bash
curl -X POST http://127.0.0.1:19470/v1/custom-voices \
  -H "Authorization: Bearer $VOICES_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My voice","audioPath":"/Users/me/Desktop/sample.m4a"}'
```

```javascript
const res = await fetch('http://127.0.0.1:19470/v1/custom-voices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My voice',
    audioPath: '/Users/me/Desktop/sample.m4a'
  }),
});
const data = await res.json();
```

```python
import os
import requests

res = requests.post(
    "http://127.0.0.1:19470/v1/custom-voices",
    headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"},
    json={"name":"My voice","audioPath":"/Users/me/Desktop/sample.m4a"},
)
print(res.json())
```
