# Voices AI Live API Control the real-time voice changer from your own scripts, bots and apps. Start and stop it, switch voices, create custom voices and follow every change as it happens, through a small REST API that runs on your computer. - Base URL: `http://127.0.0.1:19470` (only reachable from the same computer, while the app is open) - Authentication: `Authorization: Bearer `, key from Settings > Developer - Format: JSON, plus a Server-Sent Events stream at `GET /v1/events` - Describes Voices AI Live 2.11.0 and later ## Guides - [Quickstart](https://docs.getvoices.ai/guides/quickstart.md): Turn on the local API, copy your key and switch voices from a script in a few minutes. - [Authentication](https://docs.getvoices.ai/guides/authentication.md): Every request carries your API key as a Bearer token. Where to find it, how to send it and how to rotate it. - [Errors](https://docs.getvoices.ai/guides/errors.md): Status codes the API returns, what each one means and how to recover. ## Endpoints ### Status - `GET /v1/status`: [Get voice changer status](https://docs.getvoices.ai/reference/get-status.md) ### Events - `GET /v1/events`: [Stream realtime events](https://docs.getvoices.ai/reference/stream-events.md) ### Control - `POST /v1/start`: [Start the voice changer](https://docs.getvoices.ai/reference/start.md) - `POST /v1/stop`: [Stop the voice changer](https://docs.getvoices.ai/reference/stop.md) ### Voice - `GET /v1/voices`: [List available voices](https://docs.getvoices.ai/reference/list-voices.md) - `POST /v1/voice`: [Select a voice](https://docs.getvoices.ai/reference/set-voice.md) ### Custom voices - `GET /v1/custom-voices`: [List custom voices](https://docs.getvoices.ai/reference/list-custom-voices.md) - `POST /v1/custom-voices`: [Create a custom voice](https://docs.getvoices.ai/reference/create-custom-voice.md) - `DELETE /v1/custom-voices/{id}`: [Delete a custom voice](https://docs.getvoices.ai/reference/delete-custom-voice.md) ### Sounds - `GET /v1/sounds`: [List the sounds on your boards](https://docs.getvoices.ai/reference/list-sounds.md) - `POST /v1/sounds/{padId}/play`: [Play a sound](https://docs.getvoices.ai/reference/play-sound.md) - `POST /v1/sounds/stop`: [Stop all sounds](https://docs.getvoices.ai/reference/stop-sounds.md) ### Quality - `PUT /v1/quality`: [Set voice quality mode](https://docs.getvoices.ai/reference/set-quality.md) ### Monitor - `PUT /v1/monitor`: [Toggle audio monitoring](https://docs.getvoices.ai/reference/set-monitor.md) --- # 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). --- # Authentication Every request carries your API key as a Bearer token. Where to find it, how to send it and how to rotate it. The API only listens on `127.0.0.1`, so nothing outside your computer can reach it. On top of that, every request needs your API key, so other apps and websites on the same machine can't control the voice changer without it. ## Find your key Open **Settings** in Voices AI Live. With **Stream Deck and other apps** turned on, the **Developer** section shows the endpoint and your API key, masked. Use the eye button to show it or the copy button to copy it. ## Send it with every request Pass the key as a Bearer token in the `Authorization` header: ```bash curl http://127.0.0.1:19470/v1/status \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` The same works from code: ```javascript const res = await fetch('http://127.0.0.1:19470/v1/status', { headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}` }, }); ``` The events stream needs the header too. A browser's built-in `EventSource` can't set headers, so read the stream with `fetch` instead, as shown in [Stream realtime events](/reference/stream-events). ## Missing or wrong key Requests without a valid key get a `401`: ```json { "error": "Invalid or missing API key" } ``` ## Rotate the key If a key ends up somewhere it shouldn't, click **Regenerate** next to it in **Settings > Developer**. The old key stops working right away, so update your integrations with the new one. ## Browser apps The API allows requests from any web page (CORS), so tools that run in a browser can call it directly. The key is what keeps them out: only send it from pages you trust, and never put it in code you publish. --- # 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`. ```json { "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 ` 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](/reference/set-voice). - `Open the desktop app and sign in before using the local API.`: the app is open but signed out. - `Invalid JSON body` or `Missing required field: …`: the request body doesn't match the reference for that endpoint. --- # Get voice changer status `GET http://127.0.0.1:19470/v1/status` Returns the current state of the voice changer, the selected voice and, while it runs, the voice changer's delay (`latencyMs`). Call it again, or follow `GET /v1/events`, to see the latency change. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: Current status - `state` (string, required): Current state of the voice changer One of: `idle`, `starting`, `running`, `stopping`, `error`. - `message` (string, required) - `voiceId` (string or null, required): Currently selected voice ID, or null if none selected - `latencyMs` (integer or null, required): 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. ```json { "state": "running", "message": "Voice changer is running.", "voiceId": "voice_james", "latencyMs": 190 } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ## Examples ```bash curl http://127.0.0.1:19470/v1/status \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/status', { headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, }, }); const data = await res.json(); ``` ```python import os import requests res = requests.get( "http://127.0.0.1:19470/v1/status", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # Stream realtime events `GET http://127.0.0.1:19470/v1/events` Opens a Server-Sent Events stream. The first event is always a `status` snapshot. Subsequent events are sent whenever voice changer status, selected voice, quality mode, monitoring, or the sounds playing change. Event names and payloads: - `status`: the voice changer status, including `latencyMs`; sent when the state changes or the latency moves by 20 ms or more. The initial snapshot also includes selected voice, quality mode, and monitoring state - `voice`: `{ "voiceId": "hazel" }` - `quality`: `{ "mode": "adaptive" }` - `monitoring`: `{ "enabled": true }` - `sounds`: `{ "playing": ["pad_3f2a"] }`, the pad IDs playing now, whoever pressed them (an empty list when the last one ends) A keepalive comment is sent every 15 seconds while no events occur, and SSE clients are instructed to reconnect after two seconds if disconnected. Browser clients should use streaming `fetch` so the Bearer authorization header can be included; native `EventSource` cannot set that header. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: Realtime Server-Sent Events stream ```text event: status data: {"state":"running","message":"Voice changer is running.","startedAt":1793750400000,"updatedAt":1793750401000,"latencyMs":190,"voiceId":"hazel","qualityMode":"adaptive","monitorEnabled":false} event: monitoring data: {"enabled":true} ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ## Examples ```bash curl -N http://127.0.0.1:19470/v1/events \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/events', { headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, }, }); // Server-Sent Events: read the stream as it arrives. const reader = res.body.pipeThrough(new TextDecoderStream()).getReader(); for (;;) { const { value, done } = await reader.read(); if (done) break; console.log(value); } ``` ```python import os import requests res = requests.get( "http://127.0.0.1:19470/v1/events", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, stream=True, ) for line in res.iter_lines(decode_unicode=True): print(line) ``` --- # 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 ` (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()) ``` --- # Stop the voice changer `POST http://127.0.0.1:19470/v1/stop` Stops the voice changer. If it is already stopped, returns the current status. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: Voice changer stopped 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": "idle", "message": "Voice changer is stopped.", "startedAt": null, "updatedAt": 1793750460000 }, "error": null } ``` ### 400: Failed to stop - `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` ### 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/stop \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/stop', { 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/stop", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # List available voices `GET http://127.0.0.1:19470/v1/voices` Returns every voice in your voice library: the catalog (effects such as Clean Mic and Robot included), your custom voices and the Community voices you added to your voices. Clean Mic comes first. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: List of available voices - `voices` (array of Voice, required) - `id` (string, required): Unique voice identifier - `name` (string, required): Display name - `imageUrl` (string or null, required): URL to the voice avatar image; custom voices may have none - `isPro` (boolean, required): Whether this voice needs a Live subscription. Only a few voices are free; custom and Community voices always need one. - `isCustom` (boolean, required): Whether this is one of your custom voices - `isCommunity` (boolean): Whether this is a Community voice you added to your voices ```json { "voices": [ { "id": "fx_clean_mic", "name": "Clean Mic", "imageUrl": "https://cdn.getvoices.ai/voice_images/fx_clean_mic.webp", "isPro": false, "isCustom": false, "isCommunity": false }, { "id": "voice_hannah", "name": "Hannah", "imageUrl": "https://cdn.getvoices.ai/voice_images/voice_hannah.webp", "isPro": false, "isCustom": false, "isCommunity": false }, { "id": "hazel", "name": "Hazel", "imageUrl": "https://cdn.getvoices.ai/voice_images/hazel.webp", "isPro": true, "isCustom": false, "isCommunity": false }, { "id": "7b1e4d2a-5c3f-4e8a-9d6b-1a2c3e4f5a6b", "name": "Night Narrator", "imageUrl": null, "isPro": true, "isCustom": false, "isCommunity": true } ] } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ## Examples ```bash curl http://127.0.0.1:19470/v1/voices \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/voices', { headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, }, }); const data = await res.json(); ``` ```python import os import requests res = requests.get( "http://127.0.0.1:19470/v1/voices", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # 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 ` (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()) ``` --- # List custom voices `GET http://127.0.0.1:19470/v1/custom-voices` Returns the signed-in account's custom voices, so you can find a voice ID by name. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: Custom voices in the voice library - `voices` (array of 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 { "voices": [ { "id": "3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10", "name": "My voice", "imageUrl": null } ] } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ## Examples ```bash curl http://127.0.0.1:19470/v1/custom-voices \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/custom-voices', { headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, }, }); const data = await res.json(); ``` ```python import os import requests res = requests.get( "http://127.0.0.1:19470/v1/custom-voices", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # 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 ` (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()) ``` --- # Delete a custom voice `DELETE http://127.0.0.1:19470/v1/custom-voices/{id}` Permanently deletes one of your custom voices. A voice published to Community with more than 100 likes can only be removed through support (request it in the app). Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Path parameters - `id` (path · string, required) ## Responses ### 200: Custom voice deleted - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ```json { "ok": true } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ### 404: No custom voice with this ID - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ### 409: A popular Community voice that only support can remove - `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 DELETE http://127.0.0.1:19470/v1/custom-voices/3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10 \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/custom-voices/3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, }, }); const data = await res.json(); ``` ```python import os import requests res = requests.delete( "http://127.0.0.1:19470/v1/custom-voices/3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # List the sounds on your boards `GET http://127.0.0.1:19470/v1/sounds` Returns your boards from the Sounds page with the pads on them: names, pictures and pad IDs to play with `POST /v1/sounds/{padId}/play`. Only the sounds on your boards are listed, and never their audio. A pad can also be a voice: playing it switches to that voice. `isLocked` boards need a Live subscription; on a free plan only the Starter board plays. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: Your boards and their pads - `boards` (array of SoundBoard, required) - `id` (string, required) - `name` (string, required) - `isLocked` (boolean, required): Needs a Live subscription to play - `pads` (array of SoundPad, required) - `id` (string, required): Pad ID for `POST /v1/sounds/{padId}/play` - `name` (string, required) - `imageUrl` (string or null, required): The sound's picture; your own sounds may have none - `loop` (boolean, required): Whether it loops until played again or stopped - `slot` (integer, required): Its place on the board's 5 × 3 grid, row by row ```json { "boards": [ { "id": "starter", "name": "Starter", "isLocked": false, "pads": [ { "id": "pad_3f2a", "name": "Air horn", "imageUrl": "https://cdn.getvoices.ai/live-sounds/images/air-horn.webp", "loop": false, "slot": 0 } ] } ] } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ### 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 http://127.0.0.1:19470/v1/sounds \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/sounds', { headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, }, }); const data = await res.json(); ``` ```python import os import requests res = requests.get( "http://127.0.0.1:19470/v1/sounds", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # Play a sound `POST http://127.0.0.1:19470/v1/sounds/{padId}/play` Plays a pad into the microphone, exactly like its shortcut in the app: a loop starts or stops, any other sound starts again from the beginning. Works with the voice changer on or off. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Path parameters - `padId` (path · string, required) ## Responses ### 200: Playing - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ```json { "ok": true } ``` ### 400: The sound could not be played - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ```json { "ok": false, "error": "Choose a microphone output in the desktop app first." } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ### 403: The pad is on a board that needs a Live subscription - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ### 404: No pad with this ID on your boards - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ### 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/sounds/pad_3f2a/play \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/sounds/pad_3f2a/play', { 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/sounds/pad_3f2a/play", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # Stop all sounds `POST http://127.0.0.1:19470/v1/sounds/stop` Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Responses ### 200: Every sound stopped - `ok` (boolean, required) - `error` (string): Present only when `ok` is `false` ```json { "ok": true } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ### 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/sounds/stop \ -H "Authorization: Bearer $VOICES_AI_API_KEY" ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/sounds/stop', { 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/sounds/stop", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, ) print(res.json()) ``` --- # Set voice quality mode `PUT http://127.0.0.1:19470/v1/quality` Sets the quality and latency profile used by the voice changer. If the voice changer is running, its audio engine restarts briefly to apply the new mode. If it is stopped, the mode is used on the next start. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Request body (application/json) - `mode` (string, required): `adaptive` balances quality and latency automatically. `high-quality` prioritizes detail. `low-latency` prioritizes responsiveness. One of: `adaptive`, `high-quality`, `low-latency`. ```json { "mode": "adaptive" } ``` ## Responses ### 200: Quality mode updated - `ok` (boolean, required) - `qualityMode` (string, required): `adaptive` balances quality and latency automatically. `high-quality` prioritizes detail. `low-latency` prioritizes responsiveness. One of: `adaptive`, `high-quality`, `low-latency`. - `error` (string or null): Error message when `ok` is false ```json { "ok": true, "qualityMode": "adaptive" } ``` ### 400: Invalid mode or engine restart failed - `ok` (boolean, required) - `qualityMode` (string, required): `adaptive` balances quality and latency automatically. `high-quality` prioritizes detail. `low-latency` prioritizes responsiveness. One of: `adaptive`, `high-quality`, `low-latency`. - `error` (string or null): Error message when `ok` is false ```json { "ok": false, "qualityMode": "high-quality", "error": "The voice engine could not restart." } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ## Examples ```bash curl -X PUT http://127.0.0.1:19470/v1/quality \ -H "Authorization: Bearer $VOICES_AI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"mode":"adaptive"}' ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/quality', { method: 'PUT', headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ mode: 'adaptive' }), }); const data = await res.json(); ``` ```python import os import requests res = requests.put( "http://127.0.0.1:19470/v1/quality", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, json={"mode":"adaptive"}, ) print(res.json()) ``` --- # Toggle audio monitoring `PUT http://127.0.0.1:19470/v1/monitor` Enables or disables audio monitoring (hear yourself) and saves the setting. Uses the monitor device chosen in the desktop app. While the voice changer is running the change applies right away, otherwise on the next start. Authenticate with `Authorization: Bearer ` (key from Settings > Developer in Voices AI Live). ## Request body (application/json) - `enabled` (boolean, required): Whether to enable audio monitoring ```json { "enabled": true } ``` ## Responses ### 200: Monitor setting updated - `ok` (boolean, required) - `enabled` (boolean, required): The saved monitoring setting - `monitorDevice` (string or null): The device you hear yourself on, or null when monitoring is off - `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. - `error` (string or null): Why the running engine could not switch; null when `ok` is `true` ```json { "ok": true, "enabled": true, "monitorDevice": "MacBook Pro Speakers", "status": { "state": "running", "message": "Voice changer is running.", "startedAt": 1793750400000, "updatedAt": 1793750430000 }, "error": null } ``` ### 400: Invalid request body, or the running engine could not switch monitoring - `error` (string, required): Error message ```json { "error": "Missing required field: enabled (boolean)" } ``` ### 401: Invalid or missing API key - `error` (string, required): Error message ```json { "error": "Invalid or missing API key" } ``` ## Examples ```bash curl -X PUT http://127.0.0.1:19470/v1/monitor \ -H "Authorization: Bearer $VOICES_AI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":true}' ``` ```javascript const res = await fetch('http://127.0.0.1:19470/v1/monitor', { method: 'PUT', headers: { Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ enabled: true }), }); const data = await res.json(); ``` ```python import os import requests res = requests.put( "http://127.0.0.1:19470/v1/monitor", headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"}, json={"enabled":True}, ) print(res.json()) ```