Skip to main content

Create Live Session

POST 

https://api.knox.chat/v1/live/sessions

Create a Live WebRTC session from an SDP offer, or place an outbound SIP call. Knox forwards the request to OpenAI with the channel key.

Returns 201 Created after session initialization. WebRTC responses include an SDP answer. SIP responses do not wait for the callee to answer; attach a sideband with session.id to monitor progress.

Media goes to OpenAI. Knox attaches its own sideband so voice duration and nested backend usage are billed. WebRTC/SIP create charges 15 seconds of voice up front; that amount is credited against the running duration.

Do not send session.start again on the WebRTC data channel. Do not send audio.format (the codec is negotiated on the media transport). Do not send session.type on create.

See the GPT-Live guide and OpenAI’s Create session.

Request​

Send JSON or raw SDP. multipart/form-data is not accepted.

Request Headers​

NameTypeRequiredDescription
AuthorizationStringYesBearer sk-… or Bearer ek_knox_….
Content-TypeStringYesapplication/json, or application/sdp / text/plain for a raw WebRTC offer.

The same routes are also mounted under /api/v1.

JSON body (application/json)​

NameTypeRequiredDescription
sessionObjectNoLive session config. Knox pins model to gpt-live-1.
session.modelStringNoMust be gpt-live-1 when set.
session.audio.output.voiceStringNoVoice name (default upstream is marin). Immutable after start.
session.instructionsStringNoConversation prompt. Omitted uses OpenAI server defaults.
session.delegationObject or nullNoOmitted / null = client mode. responses or decisions otherwise.
session.storeBooleanNotrue to keep the session for fork and recording download.
session.inputArrayNoPrior text messages.
transport.typeStringNowebrtc (default) or sip.
transport.sdpStringIf WebRTCWebRTC offer SDP.
transport.destinationStringIf SIPE.164 destination.
transport.trunkObjectIf SIPSIP trunk credentials (see OpenAI telephony docs).

Raw SDP body (application/sdp)​

The request body is the offer SDP text. Session config then uses Knox/OpenAI defaults (gpt-live-1, client-mode delegation).

cURL examples​

WebRTC JSON​

curl -s https://api.knox.chat/v1/live/sessions \
-H "Authorization: Bearer $KNOXCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session": {
"model": "gpt-live-1",
"audio": { "output": { "voice": "marin" } },
"delegation": {
"type": "responses",
"responses": {
"model": "gpt-6-luna",
"tools": [{ "type": "web_search" }]
}
}
},
"transport": { "type": "webrtc", "sdp": "v=0\r\n…" }
}'

Raw SDP​

curl -s https://api.knox.chat/v1/live/sessions \
-H "Authorization: Bearer $KNOXCHAT_API_KEY" \
-H "Content-Type: application/sdp" \
--data-binary @offer.sdp

Raw SDP success is 201 Created with Content-Type: application/sdp, Location: /v1/live/sessions/{id}, and X-Live-Session-Id.

Outbound SIP​

curl -s https://api.knox.chat/v1/live/sessions \
-H "Authorization: Bearer $KNOXCHAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session": { "model": "gpt-live-1" },
"transport": {
"type": "sip",
"destination": "+15555550100",
"trunk": {}
}
}'

Each SIP request creates a new call. If a request times out, retry with caution: the original request may have succeeded. Ringing is limited to 3 minutes and connected calls to 2 hours.

Response​

On JSON success, Knox returns the upstream body (session object plus transport.sdp for WebRTC). Connect the answer SDP to your RTCPeerConnection. From that point, audio is peer-to-peer with OpenAI; control events still go over the WebRTC data channel.

Error Responses​

StatusWhen
400Invalid JSON, missing SDP, unsupported transport.type, or invalid session (wrong model, bad backend model).
401Missing or invalid Knox API key.
402Account balance is not greater than $0.01.
403Token allow-list does not include gpt-live-1.
502Failed to connect to Live provider / missing session.id or SDP answer.