Create Realtime Client Secret

POST 
https://api.knox.chat/v1/realtime/client_secrets

Mint a Knox ephemeral secret for a browser Realtime client. The response is not an OpenAI ek_ key. Use value immediately to open /v1/realtime or /v1/realtime/calls on Knox, not api.openai.com.

TTL is 60 seconds. Secrets live in memory on the Knox process that minted them: a different replica, a restart, or waiting too long invalidates the key.

Request

This endpoint requires a JSON object. An empty body is accepted and uses Knox defaults.

Request Headers

Name	Type	Required	Description
Authorization	String	Yes	Bearer authentication in the form Bearer sk-….
Content-Type	String	Yes	Must be application/json.

Request Body

Name	Type	Required	Description
session	Object	No	Realtime session config to attach to the secret. If omitted, Knox applies the default session (type realtime, model gpt-realtime-2.1, audio PCM 24 kHz, voice marin, reasoning.effort low).
session.type	String	No	Must be realtime when set. Knox fills this in if missing.
session.model	String	No	gpt-realtime-2.1 or gpt-realtime-2.1-mini. Defaults to gpt-realtime-2.1.
session.audio	Object	No	Input/output audio format, VAD, voice.
session.reasoning	Object	No	Defaults to { "effort": "low" } when omitted.

You can also pass ?model= on the URL. The same routes are mounted under /api/v1.

cURL Example

curl -s https://api.knox.chat/v1/realtime/client_secrets \
     -H "Authorization: Bearer $KNOXCHAT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1",
    "audio": { "output": { "voice": "marin" } }
  }
}'

Response

Success Response (200)

{
  "value": "ek_knox_…",
  "expires_at": 1750000000,
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1"
  }
}

Response Schema

Name	Type	Description
value	string	Knox ephemeral key (ek_knox_…). Send it as Authorization: Bearer ek_knox_… on the next Realtime connect.
expires_at	integer	Unix timestamp when the secret expires (~60 seconds from mint).
session	object	Session config stored with the secret, including Knox defaults and hosted web_search injection when enabled.

Error Responses

Status	When
400	Invalid JSON body.
401	Missing or invalid Knox API key.
402	Account balance is not greater than $0.01.
403	The token's model allow-list does not include the requested realtime model (gpt-realtime-2.1 or gpt-realtime-2.1-mini).
502	No OpenAI-compatible Realtime channel is available.