Implementation:Openai Openai python Realtime Session Update

Knowledge Sources	openai-python OpenAI Realtime API
Domains	Realtime_Communication, Configuration
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for configuring Realtime API session parameters over an active WebSocket connection provided by the OpenAI Python SDK.

Description

The RealtimeSessionResource.update() method sends a session.update event over the WebSocket, configuring modalities, voice, instructions, turn detection, tools, and audio formats. The server acknowledges with a session.updated event.

Usage

Call immediately after realtime.connect() to set initial configuration. Call again mid-session to change parameters dynamically.

Code Reference

Source Location

Repository: openai-python
File: src/openai/resources/beta/realtime/realtime.py
Lines: L600-619 (sync), L850-871 (async)

Signature

class AsyncRealtimeSessionResource:
    async def update(
        self,
        *,
        session: session_update_event_param.Session,
        event_id: str | NotGiven = NOT_GIVEN,
    ) -> None:
        """
        Sends a session.update event to configure the session.

        Args:
            session: Session configuration dict with modalities, voice, instructions, etc.
            event_id: Optional custom event ID.
        """

Import

from openai import AsyncOpenAI
# Access via connection.session.update()

I/O Contract

Inputs

Name	Type	Required	Description
session.modalities	list[str]	No	Active modalities: ["text"], ["audio"], or ["text", "audio"]
session.voice	str	No	Voice for audio output (alloy, ash, ballad, coral, echo, sage, shimmer, verse)
session.instructions	str	No	System-level instructions
session.input_audio_format	str	No	Input audio format (pcm16, g711_ulaw, g711_alaw)
session.output_audio_format	str	No	Output audio format
session.turn_detection	dict	No	VAD settings for turn-taking
session.tools	list	No	Tool definitions available in this session

Outputs

Name	Type	Description
(WebSocket event)	None	Sends session.update event; server responds with session.updated

Usage Examples

Text-Only Session

async with client.beta.realtime.connect(model="gpt-4o-realtime-preview") as connection:
    await connection.session.update(session={
        "modalities": ["text"],
        "instructions": "You are a helpful coding assistant.",
    })

Voice Session with Tools

async with client.beta.realtime.connect(model="gpt-4o-realtime-preview") as connection:
    await connection.session.update(session={
        "modalities": ["text", "audio"],
        "voice": "alloy",
        "instructions": "You are a voice assistant that can check the weather.",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "turn_detection": {"type": "server_vad"},
        "tools": [
            {
                "type": "function",
                "name": "get_weather",
                "description": "Get the current weather",
                "parameters": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
            }
        ],
    })

Related Pages

Implements Principle

Principle:Openai_Openai_python_Realtime_Session_Configuration

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment