Skip to main content
POST
Python

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
agent_id
string | null

The ID of the agent to use for a direct-agent voice conversation. Ignored when voice_mode is orchestrator.

voice_mode
enum<string> | null

Controls whether the session uses the voice orchestrator, with delegation tools, or talks directly to a specific agent. Defaults to orchestrator when agent_id is omitted and direct_agent when agent_id is provided.

Available options:
orchestrator,
direct_agent
conversation_id
string | null

The ID of an existing conversation to continue. If not provided, a new conversation will be created.

config
object | null

Override the agent config for this voice session. Only prompt overrides are supported — voice sessions always use Gemini Live, so LLM model, agent model, planning prompt, and tool settings are not applicable.

file_ids
string[] | null

Array of file IDs to attach to the voice conversation.

secret_ids
string[] | null

Array of secret IDs to include in the context.

knowledge_ids
string[] | null

Array of knowledge IDs to make accessible to the agent.

page_ids
string[] | null

Array of page IDs to make accessible to the agent. The page and all knowledge under it will be accessible.

user
object | null

Override user information for this voice session.

initial_context
string | null

Optional context text for the voice session. When provided, the AI will start by briefly explaining this content before listening for user input.

Maximum string length: 2000
initial_message
string | null

Optional initial user message. When provided, the system greeting is skipped and the AI responds directly to this text (e.g. a suggested prompt). Takes precedence over initial_context.

Maximum string length: 2000
ephemeral
boolean | null
default:false

When true, the session is ephemeral and will not save messages to conversation history.

voice_config
object | null

Voice session configuration options.

Response

Voice session prepared

object
enum<string>
required

Object type discriminator.

Available options:
voice.session
url
string
required

WebSocket URL to connect to. Includes the authentication token as a query parameter.

agent_id
string
required

The resolved agent ID. If no agent was specified in the request, this is the default agent.

start_message
object
required

Ready-made JSON message to send as the first WebSocket frame after connecting. Contains type: "start" and a payload with all session parameters.