openvip

Open Voice Interaction Protocol (OpenVIP) HTTP API specification.

This API allows applications to send and receive voice interaction messages.

Base Path

The OpenVIP protocol defines relative paths only. The base path is implementation-defined — implementations choose where to mount these endpoints. The recommended base path is /openvip/.

Implementations SHOULD serve this OpenAPI spec at {base_path}/openapi.json for discovery (e.g. GET /openvip/openapi.json).

Quick Start

# Subscribe to messages (SSE) — this IS the registration
curl http://localhost:8770/openvip/agents/my-agent-id/messages

# Send a message to an agent
curl -X POST http://localhost:8770/openvip/agents/my-agent-id/messages \\
  -H \"Content-Type: application/json\" \\
  -d '{\"openvip\": \"1.0\", \"type\": \"transcription\", \"id\": \"uuid\", \"timestamp\": \"2026-02-06T10:30:00Z\", \"text\": \"hello\"}'

# Text-to-speech
curl -X POST http://localhost:8770/openvip/speech \\
  -H \"Content-Type: application/json\" \\
  -d '{\"openvip\": \"1.0\", \"type\": \"speech\", \"id\": \"uuid\", \"timestamp\": \"2026-02-06T10:30:05Z\", \"text\": \"hello world\", \"language\": \"en\"}'

Agent Lifecycle

Agents are ephemeral. An agent exists only while its SSE connection is open. No explicit registration is needed — connecting to the SSE endpoint registers the agent. Disconnecting automatically de-registers it.

This Python package is automatically generated by the OpenAPI Generator project:

• API version: 1.0
• Package version: 1.0.0
• Generator version: 7.21.0-SNAPSHOT
• Build package: org.openapitools.codegen.languages.PythonClientCodegen For more information, please visit https://openvip.org

Requirements.

Python 3.9+

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import openvip

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import openvip

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:

import openvip
from openvip.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost:8770/openvip
# See configuration.py for a list of all supported configuration parameters.
configuration = openvip.Configuration(
    host = "http://localhost:8770/openvip"
)



# Enter a context with an instance of the API client
with openvip.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = openvip.ControlApi(api_client)
    control_request = {"openvip":"1.0","id":"770e8400-e29b-41d4-a716-446655440000","command":"stt.stop"} # ControlRequest | 

    try:
        # Send control command
        api_response = api_instance.send_control(control_request)
        print("The response of ControlApi->send_control:\n")
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling ControlApi->send_control: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to http://localhost:8770/openvip

Documentation For Models

• ControlRequest
• Error
• Message
• MessageXAgentSwitch
• MessageXInput
• Response
• SpeechRequest
• SpeechResponse
• Status
• StatusStt
• StatusTts
• Transcription

Documentation For Authorization

Endpoints do not require authorization.

Author