Get started
Errors
Status codes the API returns, what each one means and how to recover.
The API uses standard HTTP status codes. Failed requests come back as JSON with an error message you can show or log. Actions that report a result (start, stop, quality, custom voices) also include "ok": false.
{
"ok": false,
"error": "No voice selected. Use POST /v1/voice first."
}Status codes
| Code | Meaning | What to do |
|---|---|---|
200 |
The request worked. | Read the response body. |
400 |
The body is invalid or the action failed, for example no voice is selected yet or a voice model couldn't be downloaded. | Fix the request, or follow the message. |
401 |
The API key is missing or wrong. | Send Authorization: Bearer <key> with the key from Settings > Developer. |
403 |
The account needs an active subscription for this, for example to create custom voices. | Subscribe in the app. |
404 |
Unknown path, or no voice with that ID. | Check the path, or list voice IDs with GET /v1/voices. |
409 |
Conflict, such as the custom voice limit being reached. | Delete a custom voice first, or contact support. |
503 |
The desktop app isn't signed in. | Open Voices AI Live and sign in. |
504 |
The app didn't finish in time (custom voices). | Keep the app open and signed in, then try again. |
Can't connect at all
If the request never gets a response, the API isn't listening:
- Make sure Voices AI Live is open. The API stops when you quit the app.
- Check that Stream Deck and other apps is on in Settings > General.
- Use the endpoint shown in Settings > Developer. The default is
http://127.0.0.1:19470.
Messages you may see
No voice selected. Use POST /v1/voice first.: select a voice before starting. See Select a voice.Open the desktop app and sign in before using the local API.: the app is open but signed out.Invalid JSON bodyorMissing required field: …: the request body doesn't match the reference for that endpoint.