openapi: 3.1.0
info:
  title: Voices AI Live API
  description: |
    Local REST API for programmatic control of the Voices AI Live voice changer.

    The API runs on `127.0.0.1` and is only accessible from the local machine.
    Enable it in **Settings > Developer** inside the desktop app.

    This document describes Voices AI Live 2.11.0.
  version: 2.11.0
  contact:
    name: Voices AI
    url: https://getvoices.ai

servers:
  - url: http://127.0.0.1:19470
    description: Default local server

security:
  - BearerAuth: []

tags:
  - name: Status
    description: Query the current voice changer state
  - name: Events
    description: Subscribe to realtime voice changer events
  - name: Control
    description: Start and stop the voice changer
  - name: Voice
    description: Select a voice model
  - name: Custom voices
    description: Find, create and delete your own cloned voices
  - name: Sounds
    description: Play the sounds on your boards
  - name: Quality
    description: Select the voice quality and latency profile
  - name: Monitor
    description: Control audio monitoring (hear yourself)

paths:
  /v1/events:
    get:
      operationId: streamEvents
      summary: Stream realtime events
      description: |
        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.
      tags: [ Events ]
      responses:
        "200":
          description: Realtime Server-Sent Events stream
          content:
            text/event-stream:
              schema:
                type: string
              example: |
                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":
          $ref: "#/components/responses/Unauthorized"

  /v1/status:
    get:
      operationId: getStatus
      summary: Get voice changer status
      description: |
        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.
      tags: [ Status ]
      responses:
        "200":
          description: Current status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
              example:
                state: running
                message: Voice changer is running.
                voiceId: voice_james
                latencyMs: 190
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/start:
    post:
      operationId: start
      summary: Start the voice changer
      description: |
        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.
      tags: [ Control ]
      responses:
        "200":
          description: Voice changer started successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResponse"
              example:
                ok: true
                status:
                  state: running
                  message: Voice changer is running.
                  startedAt: 1793750400000
                  updatedAt: 1793750400000
        "400":
          description: Failed to start, e.g. no voice selected yet or the engine could not start
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResponse"
              example:
                ok: false
                state: idle
                error: No voice selected. Use POST /v1/voice first.
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/stop:
    post:
      operationId: stop
      summary: Stop the voice changer
      description: Stops the voice changer. If it is already stopped, returns the
        current status.
      tags: [ Control ]
      responses:
        "200":
          description: Voice changer stopped successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResponse"
              example:
                ok: true
                status:
                  state: idle
                  message: Voice changer is stopped.
                  startedAt: null
                  updatedAt: 1793750460000
                error: null
        "400":
          description: Failed to stop
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/voices:
    get:
      operationId: listVoices
      summary: List available voices
      description: |
        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.
      tags: [ Voice ]
      responses:
        "200":
          description: List of available voices
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VoiceListResponse"
              example:
                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":
          $ref: "#/components/responses/Unauthorized"

  /v1/voice:
    post:
      operationId: setVoice
      summary: Select a voice
      description: |
        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.
      tags: [ Voice ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetVoiceRequest"
            example:
              id: voice_james
      responses:
        "200":
          description: Voice set successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: true
        "400":
          description: Invalid body, or the voice model could not be downloaded or applied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: false
                error: Voice integrity metadata is unavailable.
        "404":
          description: Voice ID not found in the library
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Voice "unknown_id" not found.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          description: The desktop app is not signed in
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Open the desktop app and sign in before using the local API.

  /v1/custom-voices:
    get:
      operationId: listCustomVoices
      summary: List custom voices
      description: Returns the signed-in account's custom voices, so you can find a voice ID by name.
      tags: [ Custom voices ]
      responses:
        "200":
          description: Custom voices in the voice library
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomVoiceListResponse"
              example:
                voices:
                  - id: 3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10
                    name: My voice
                    imageUrl: null
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: createCustomVoice
      summary: Create a custom voice
      description: |
        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`.
      tags: [ Custom voices ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCustomVoiceRequest"
            example:
              name: My voice
              audioPath: /Users/me/Desktop/sample.m4a
      responses:
        "200":
          description: Custom voice created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateCustomVoiceResponse"
              example:
                ok: true
                voice:
                  id: 3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10
                  name: My voice
                  imageUrl: null
        "400":
          description: Invalid fields, a missing or unreadable file, or audio without enough clear speech
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: false
                error: The audio needs at least 5 seconds of clear speech.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: The account needs an active subscription
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: false
                error: Custom voices need an active subscription.
        "409":
          description: The account has reached its custom voice limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "503":
          $ref: "#/components/responses/SignedOut"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/custom-voices/{id}:
    delete:
      operationId: deleteCustomVoice
      summary: Delete a custom voice
      description: |
        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).
      tags: [ Custom voices ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: 3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10
      responses:
        "200":
          description: Custom voice deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: No custom voice with this ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "409":
          description: A popular Community voice that only support can remove
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "503":
          $ref: "#/components/responses/SignedOut"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/sounds:
    get:
      operationId: listSounds
      summary: List the sounds on your boards
      description: |
        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.
      tags: [ Sounds ]
      responses:
        "200":
          description: Your boards and their pads
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SoundListResponse"
              example:
                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":
          $ref: "#/components/responses/Unauthorized"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/sounds/{padId}/play:
    post:
      operationId: playSound
      summary: Play a sound
      description: |
        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.
      tags: [ Sounds ]
      parameters:
        - name: padId
          in: path
          required: true
          schema:
            type: string
          example: pad_3f2a
      responses:
        "200":
          description: Playing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: true
        "400":
          description: The sound could not be played
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: false
                error: Choose a microphone output in the desktop app first.
        "403":
          description: The pad is on a board that needs a Live subscription
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "404":
          description: No pad with this ID on your boards
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/sounds/stop:
    post:
      operationId: stopSounds
      summary: Stop all sounds
      tags: [ Sounds ]
      responses:
        "200":
          description: Every sound stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
              example:
                ok: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/quality:
    put:
      operationId: setQuality
      summary: Set voice quality mode
      description: |
        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.
      tags: [ Quality ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetQualityRequest"
            example:
              mode: adaptive
      responses:
        "200":
          description: Quality mode updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetQualityResponse"
              example:
                ok: true
                qualityMode: adaptive
        "400":
          description: Invalid mode or engine restart failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetQualityResponse"
              example:
                ok: false
                qualityMode: high-quality
                error: The voice engine could not restart.
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/monitor:
    put:
      operationId: setMonitor
      summary: Toggle audio monitoring
      description: |
        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.
      tags: [ Monitor ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetMonitorRequest"
            example:
              enabled: true
      responses:
        "200":
          description: Monitor setting updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetMonitorResponse"
              example:
                ok: true
                enabled: true
                monitorDevice: MacBook Pro Speakers
                status:
                  state: running
                  message: Voice changer is running.
                  startedAt: 1793750400000
                  updatedAt: 1793750430000
                error: null
        "400":
          description: Invalid request body, or the running engine could not switch monitoring
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "Missing required field: enabled (boolean)"
        "401":
          $ref: "#/components/responses/Unauthorized"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key from **Settings > Developer** in the desktop app.
        Pass it as a Bearer token in the `Authorization` header.

  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Invalid or missing API key
    SignedOut:
      description: The desktop app is not signed in
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OkResponse"
          example:
            ok: false
            error: Open the desktop app and sign in before using the local API.
    Timeout:
      description: The desktop app did not finish the request in time
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OkResponse"
          example:
            ok: false
            error: The desktop app did not respond in time. Keep it open and signed in.

  schemas:
    VoiceTransformState:
      type: string
      enum: [ idle, starting, running, stopping, error ]
      description: Current state of the voice changer
      example: running

    StatusResponse:
      type: object
      properties:
        state:
          $ref: "#/components/schemas/VoiceTransformState"
          example: running
        message:
          type: string
          example: Voice changer is running.
        voiceId:
          type: [ "string", "null" ]
          description: Currently selected voice ID, or null if none selected
          example: voice_james
        latencyMs:
          type: [ "integer", "null" ]
          description: |
            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.
          example: 190
      required: [ state, message, voiceId, latencyMs ]

    EngineStatus:
      type: object
      description: The voice changer status after an action
      properties:
        state:
          $ref: "#/components/schemas/VoiceTransformState"
        message:
          type: string
          example: Voice changer is running.
        startedAt:
          type: [ "integer", "null" ]
          description: When the current run started, in milliseconds since the Unix epoch
        updatedAt:
          type: integer
          description: When this status was set, in milliseconds since the Unix epoch
        latencyMs:
          type: [ "integer", "null" ]
          description: |
            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.
          example: 190
      required: [ state, message ]

    ActionResponse:
      type: object
      description: Response for start/stop actions
      properties:
        ok:
          type: boolean
          example: true
        status:
          $ref: "#/components/schemas/EngineStatus"
        state:
          $ref: "#/components/schemas/VoiceTransformState"
          description: Only when Start is refused because no voice is selected
        error:
          type: [ "string", "null" ]
          description: Why the action failed; null or absent when `ok` is `true`
          example: No voice selected. Use POST /v1/voice first.
      required: [ ok ]

    SoundPad:
      type: object
      properties:
        id:
          type: string
          description: Pad ID for `POST /v1/sounds/{padId}/play`
          example: pad_3f2a
        name:
          type: string
          example: Air horn
        imageUrl:
          type: [ "string", "null" ]
          description: The sound's picture; your own sounds may have none
        loop:
          type: boolean
          description: Whether it loops until played again or stopped
        slot:
          type: integer
          minimum: 0
          maximum: 14
          description: Its place on the board's 5 × 3 grid, row by row
      required: [ id, name, imageUrl, loop, slot ]

    SoundBoard:
      type: object
      properties:
        id:
          type: string
          example: starter
        name:
          type: string
          example: Starter
        isLocked:
          type: boolean
          description: Needs a Live subscription to play
        pads:
          type: array
          items:
            $ref: "#/components/schemas/SoundPad"
      required: [ id, name, isLocked, pads ]

    SoundListResponse:
      type: object
      properties:
        boards:
          type: array
          items:
            $ref: "#/components/schemas/SoundBoard"
      required: [ boards ]

    OkResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        error:
          type: string
          description: Present only when `ok` is `false`
          example: Voice changer is not running.
      required: [ ok ]

    Voice:
      type: object
      properties:
        id:
          type: string
          description: Unique voice identifier
          example: voice_james
        name:
          type: string
          description: Display name
          example: James
        imageUrl:
          type: [ "string", "null" ]
          description: URL to the voice avatar image; custom voices may have none
          example: https://cdn.getvoices.ai/voice_images/voice_james.webp
        isPro:
          type: boolean
          description: |
            Whether this voice needs a Live subscription. Only a few voices are free;
            custom and Community voices always need one.
          example: false
        isCustom:
          type: boolean
          description: Whether this is one of your custom voices
          example: false
        isCommunity:
          type: boolean
          description: Whether this is a Community voice you added to your voices
          example: false
      required: [ id, name, imageUrl, isPro, isCustom ]

    VoiceListResponse:
      type: object
      properties:
        voices:
          type: array
          items:
            $ref: "#/components/schemas/Voice"
      required: [ voices ]

    CustomVoice:
      type: object
      properties:
        id:
          type: string
          description: Voice ID for `POST /v1/voice` and `DELETE /v1/custom-voices/{id}`
          example: 3f6c2a9e-8d41-4c57-9b0e-2f1d7a4c8e10
        name:
          type: string
          example: My voice
        imageUrl:
          type: [ "string", "null" ]
          description: Avatar URL, or null when the voice has no image
      required: [ id, name, imageUrl ]

    CustomVoiceListResponse:
      type: object
      properties:
        voices:
          type: array
          items:
            $ref: "#/components/schemas/CustomVoice"
      required: [ voices ]

    CreateCustomVoiceRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
          example: My voice
        audioPath:
          type: string
          description: Absolute path to an audio or video file on this machine (up to 200 MB) with at least 5 seconds of clear speech
          example: /Users/me/Desktop/sample.m4a
        imagePath:
          type: string
          description: Optional absolute path to an avatar image (up to 20 MB), cropped to a square
          example: /Users/me/Desktop/avatar.png
      required: [ name, audioPath ]

    CreateCustomVoiceResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        voice:
          $ref: "#/components/schemas/CustomVoice"
      required: [ ok, voice ]

    SetVoiceRequest:
      type: object
      properties:
        id:
          type: string
          description: Voice ID from the voice library
          example: voice_james
      required: [ id ]

    QualityMode:
      type: string
      enum: [ adaptive, high-quality, low-latency ]
      description: |
        `adaptive` balances quality and latency automatically. `high-quality`
        prioritizes detail. `low-latency` prioritizes responsiveness.
      example: adaptive

    SetQualityRequest:
      type: object
      properties:
        mode:
          $ref: "#/components/schemas/QualityMode"
      required: [ mode ]

    SetQualityResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        qualityMode:
          $ref: "#/components/schemas/QualityMode"
        error:
          type: [ "string", "null" ]
          description: Error message when `ok` is false
      required: [ ok, qualityMode ]

    SetMonitorRequest:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether to enable audio monitoring
          example: true
      required: [ enabled ]

    SetMonitorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: true
        enabled:
          type: boolean
          description: The saved monitoring setting
          example: true
        monitorDevice:
          type: [ "string", "null" ]
          description: The device you hear yourself on, or null when monitoring is off
          example: MacBook Pro Speakers
        status:
          $ref: "#/components/schemas/EngineStatus"
        error:
          type: [ "string", "null" ]
          description: Why the running engine could not switch; null when `ok` is `true`
      required: [ ok, enabled ]

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Invalid or missing API key
      required: [ error ]
