Endpoints

Voice agent

Mint a voice agent session token, then run a speech-in, speech-out conversation over a WebSocket.

The voice agent endpoints run a full conversational loop in one WebSocket session: the caller speaks, the agent listens, reasons, optionally calls your tools, and answers with audio. Like realtime transcription, access is a two-step flow: mint a short-lived token server-side, then connect with the token from the client.

Mint a voice agent token

POST/v2/voice-agent/tokenCreate a short-lived token for one voice agent session

Request body

Field	Type	Default	Description
model	string	whisper-voicekit-agent	Voice agent model id. Currently `whisper-voicekit-agent`; any other family returns `400 bad_model`.
expires_in	integer, 60 to 600	300	Token lifetime in seconds. Redeem it on the WebSocket within this window.
max_session_duration_sec	integer, 60 to 10800	3300	Requested session cap in seconds. The server enforces its own ceiling (currently 3300 seconds, 55 minutes) and returns the effective value.
estimated_duration_sec	integer or null	null	Estimated session length for the pre-flight credit check; may fail early with `402 v2_billing_required`.

Response

Field	Type	Description
token	string	Session token for the `token` query parameter on the WebSocket.
websocket_url	string	The WebSocket endpoint, `wss://api.realtimevoicekit.com/v2/voice-agent/ws`.
expires_at	string	ISO 8601 expiry of the token.
model	string	The resolved model id.
max_session_duration_sec	integer	The effective session cap after server limits are applied.

Errors

Status	Code	When
400	unknown_model	`model` is not a catalog id.
400	bad_model	`model` is valid but not a voice agent model.
402	v2_billing_required	Credit exhausted or the estimate exceeds the balance.

Mint a voice agent token (server-side)

curl -X POST https://api.realtimevoicekit.com/v2/voice-agent/token \
  -H "Authorization: Bearer rtvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "whisper-voicekit-agent", "max_session_duration_sec": 1800}'

Voice agent WebSocket

WSS/v2/voice-agent/wsRun one realtime voice agent conversation

Query parameters

Parameter	Type	Default	Description
token	string	required	Session token from `POST /v2/voice-agent/token`.
model	string	whisper-voicekit-agent	Voice agent model id.
max_session_duration_sec	integer, 60 to 10800	server default	Optional per-connection cap; the server ceiling still applies.

Message protocol

The protocol is JSON text frames in both directions; binary frames are ignored. The typical session looks like this:

Send a session.update message first to configure the agent: system prompt and instructions, an optional opening greeting, tool definitions, and audio input and output settings.
Stream microphone audio as JSON messages carrying base64-encoded PCM16 chunks.
Receive events as they happen: user and agent transcripts, base64 agent audio to play back, tool call requests to fulfil, and lifecycle events.
Send session.end to finalize immediately. The server drains its final events (ending with session.ended) and closes.

If the session cap is reached or the client disconnects, the server finalizes the session on your behalf and emits the closing events before disconnecting. A session.error event is sent when the session cannot start or fails mid-way.

Close codes

Code	Meaning
4401	The token is missing, expired, or not a voice agent session token.
4400	The `model` query parameter is not a valid voice agent model.

Billing: the session is metered per elapsed second at the agent model's hourly session rate, from accept to close. See Models and pricing. For a guided walkthrough of agent configuration and tool calling, see the Voice Agent API tab.