references/api-reference.md
Azure AI Voice Live SDK - API Reference
Table of Contents
- connect() Function
- VoiceLiveConnection
- SessionResource
- ResponseResource
- InputAudioBufferResource
- OutputAudioBufferResource
- ConversationResource
- TranscriptionSessionResource
- WebsocketConnectionOptions
- Exceptions
connect() Function
Creates an async context manager for WebSocket connections.
from azure.ai.voicelive.aio import connect
async with connect(
credential: Union[AzureKeyCredential, AsyncTokenCredential],
endpoint: str,
api_version: str = "2025-10-01",
model: Optional[str] = None,
query: Optional[Mapping[str, Any]] = None,
headers: Optional[Mapping[str, Any]] = None,
connection_options: Optional[WebsocketConnectionOptions] = None,
credential_scopes: Optional[List[str]] = None,
**kwargs
) -> VoiceLiveConnection:
...
Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| credential | AzureKeyCredential or AsyncTokenCredential | Yes | Authentication credential |
| endpoint | str | Yes | Service endpoint URL |
| api_version | str | No | API version (default: "2025-10-01") |
| model | str | Sometimes | Model identifier (required unless using Agent scenario) |
| query | Mapping[str, Any] | No | Additional URL query parameters |
| headers | Mapping[str, Any] | No | Additional HTTP headers |
| connection_options | WebsocketConnectionOptions | No | WebSocket transport options |
| credential_scopes | List[str] | No | OAuth scopes (default: ["https://ai.azure.com/.default"]) |
VoiceLiveConnection
Main connection class with resource accessors.
Properties
| Property | Type | Description |
|----------|------|-------------|
| session | SessionResource | Session configuration |
| response | ResponseResource | Response management |
| input_audio_buffer | InputAudioBufferResource | Audio input buffer |
| output_audio_buffer | OutputAudioBufferResource | Audio output buffer |
| conversation | ConversationResource | Conversation items |
| transcription_session | TranscriptionSessionResource | Transcription config |
Methods
async def recv() -> ServerEvent:
"""Receive and parse the next typed server event."""
async def recv_bytes() -> bytes:
"""Receive raw bytes from the connection."""
async def send(event: Union[Mapping[str, Any], ClientEvent]) -> None:
"""Send an event to the server."""
async def close(*, code: int = 1000, reason: str = "") -> None:
"""Close the WebSocket connection."""
async def __aiter__() -> AsyncIterator[ServerEvent]:
"""Iterate over server events until connection closes."""
SessionResource
Manage session configuration.
Methods
async def update(
*,
session: Union[Mapping[str, Any], RequestSession],
event_id: Optional[str] = None
) -> None:
"""Update session configuration."""
RequestSession Fields
| Field | Type | Description |
|-------|------|-------------|
| instructions | str | System prompt for the model |
| modalities | List[Modality] | ["text"], ["audio"], or ["text", "audio"] |
| voice | Voice | Voice for audio output |
| input_audio_format | InputAudioFormat | Audio input format |
| output_audio_format | OutputAudioFormat | Audio output format |
| turn_detection | TurnDetection | VAD configuration or None for manual |
| tools | List[Tool] | Function tools |
| tool_choice | ToolChoice | "auto", "none", "required", or specific function |
| temperature | float | Model temperature (0.6-1.2) |
| max_response_output_tokens | int or "inf" | Max tokens per response |
| input_audio_transcription | AudioInputTranscriptionOptions | Transcription settings |
ResponseResource
Manage model responses.
Methods
async def create(
*,
response: Optional[Union[ResponseCreateParams, Mapping[str, Any]]] = None,
event_id: Optional[str] = None,
additional_instructions: Optional[str] = None
) -> None:
"""Create a response (trigger inference)."""
async def cancel(
*,
response_id: Optional[str] = None,
event_id: Optional[str] = None
) -> None:
"""Cancel an in-progress response."""
ResponseCreateParams Fields
| Field | Type | Description |
|-------|------|-------------|
| modalities | List[Modality] | Override session modalities |
| instructions | str | Override session instructions |
| voice | Voice | Override session voice |
| temperature | float | Override temperature |
| max_response_output_tokens | int | Override max tokens |
| conversation | str | "auto" or "none" |
InputAudioBufferResource
Manage audio input buffer.
Methods
async def append(
*,
audio: str, # Base64-encoded audio
event_id: Optional[str] = None
) -> None:
"""Append audio data to the input buffer."""
async def commit(
*,
event_id: Optional[str] = None
) -> None:
"""Commit the buffer as a user message."""
async def clear(
*,
event_id: Optional[str] = None
) -> None:
"""Clear the input buffer without committing."""
OutputAudioBufferResource
Manage audio output buffer.
Methods
async def clear(
*,
event_id: Optional[str] = None
) -> None:
"""Clear pending audio output (for interrupts)."""
ConversationResource
Manage conversation state.
Properties
| Property | Type | Description |
|----------|------|-------------|
| item | ConversationItemResource | Item operations |
ConversationItemResource
CRUD operations on conversation items.
Methods
async def create(
*,
item: Union[ConversationRequestItem, Mapping[str, Any]],
previous_item_id: Optional[str] = None,
event_id: Optional[str] = None
) -> None:
"""Create a new conversation item."""
async def delete(
*,
item_id: str,
event_id: Optional[str] = None
) -> None:
"""Delete a conversation item."""
async def retrieve(
*,
item_id: str,
event_id: Optional[str] = None
) -> None:
"""Retrieve item details (server responds with event)."""
async def truncate(
*,
item_id: str,
audio_end_ms: int,
content_index: int,
event_id: Optional[str] = None
) -> None:
"""Truncate audio at specified time."""
ConversationRequestItem Types
# User/Assistant/System message
{
"type": "message",
"role": "user" | "assistant" | "system",
"content": [
{"type": "input_text", "text": "..."},
{"type": "input_audio", "audio": "base64..."},
{"type": "text", "text": "..."},
{"type": "audio", "audio": "base64...", "transcript": "..."}
]
}
# Function call (from model)
{
"type": "function_call",
"call_id": "...",
"name": "function_name",
"arguments": "{...}"
}
# Function output (from client)
{
"type": "function_call_output",
"call_id": "...",
"output": "{...}"
}
TranscriptionSessionResource
Configure input transcription.
Methods
async def update(
*,
session: Mapping[str, Any],
event_id: Optional[str] = None
) -> None:
"""Update transcription session configuration."""
WebsocketConnectionOptions
Transport configuration for the WebSocket connection.
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| compression | bool or int | None | Enable per-message compression |
| max_msg_size | int | 4MB | Maximum message size |
| heartbeat | float | 30 | Keep-alive ping interval (seconds) |
| autoclose | bool | True | Auto-close on close frame |
| autoping | bool | True | Auto-respond to pings |
| receive_timeout | float | None | Message receive timeout |
| close_timeout | float | None | Close handshake timeout |
| handshake_timeout | float | None | Connection establishment timeout |
| vendor_options | Mapping | None | Implementation-specific options |
Exceptions
from azure.ai.voicelive.aio import ConnectionError, ConnectionClosed
class ConnectionError(AzureError):
"""Base WebSocket connection error."""
class ConnectionClosed(ConnectionError):
"""WebSocket connection was closed."""
code: int # Close code
reason: str # Close reason
Common Close Codes
| Code | Meaning | |------|---------| | 1000 | Normal closure | | 1001 | Going away | | 1006 | Abnormal closure | | 1008 | Policy violation | | 1011 | Server error |