curl --request POST \
--url https://api.aireserve.com/v1/realtime/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "grok-voice",
"voice": "ara"
}
'import requests
url = "https://api.aireserve.com/v1/realtime/sessions"
payload = {
"model": "grok-voice",
"voice": "ara"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: 'grok-voice', voice: 'ara'})
};
fetch('https://api.aireserve.com/v1/realtime/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"session_id": "9c3f1a2b-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"model": "grok-voice",
"voice": "ara",
"wss_url": "wss://voice-relay-uat-abcdefg-ue.a.run.app/v1/realtime?model=grok-voice",
"ephemeral_key": "v1.1756946700.ABCDEFGHIJKLMNOPQRSTuvwxyz01234.signature_base64url_43chars",
"expires_at": "2026-09-03T21:05:00.000Z",
"key_ttl_seconds": 300,
"max_session_seconds": 3540,
"browser_subprotocols": [
"openai-beta.realtime-v1",
"openai-insecure-api-key.v1.1756946700.ABCDEFGHIJKLMNOPQRSTuvwxyz01234.signature_base64url_43chars"
]
}Mint realtime voice session
Mint a short-lived WebSocket credential for a realtime speech-to-speech session with xAI Grok Voice. Authenticates the caller, checks the realtimeVoiceEnabled org gate, resolves voice ownership, reserves worst-case session funds from the wallet, and returns wss_url plus an ephemeral_key. The key is an HMAC-SHA-256 signed opaque one-use relay ticket (valid 5 minutes); it encodes only expiry and a nonce — the authorized voice is stored in the session record, keyed by the ticket’s SHA-256 hash. The relay verifies the HMAC, reads the session record by hash, and injects the authorized voice server-side at WebSocket open; the client cannot change the voice mid-session. Only audio I/O events are accepted; text output, transcription, tools, and session resumption are not supported in this release.
curl --request POST \
--url https://api.aireserve.com/v1/realtime/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "grok-voice",
"voice": "ara"
}
'import requests
url = "https://api.aireserve.com/v1/realtime/sessions"
payload = {
"model": "grok-voice",
"voice": "ara"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: 'grok-voice', voice: 'ara'})
};
fetch('https://api.aireserve.com/v1/realtime/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"session_id": "9c3f1a2b-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"model": "grok-voice",
"voice": "ara",
"wss_url": "wss://voice-relay-uat-abcdefg-ue.a.run.app/v1/realtime?model=grok-voice",
"ephemeral_key": "v1.1756946700.ABCDEFGHIJKLMNOPQRSTuvwxyz01234.signature_base64url_43chars",
"expires_at": "2026-09-03T21:05:00.000Z",
"key_ttl_seconds": 300,
"max_session_seconds": 3540,
"browser_subprotocols": [
"openai-beta.realtime-v1",
"openai-insecure-api-key.v1.1756946700.ABCDEFGHIJKLMNOPQRSTuvwxyz01234.signature_base64url_43chars"
]
}Authorizations
Your AI Reserve API key (aireserve_api_…) from the API Keys page in the portal (https://portal.aireserve.com/keys).
Body
Must be grok-voice.
grok-voice Voice to use for this session. Pass a built-in voice ID (from GET /v1/voices) or one of your organization's custom voice IDs. Defaults to ara when omitted. Voice is locked at mint and cannot change mid-session.
Response
Session minted. Connect the WebSocket before expires_at.
Realtime session mint response. Use wss_url and ephemeral_key to open the WebSocket.
Unique session identifier used for billing and logging.
grok-voice Voice bound to this session (cannot change mid-session).
Environment-specific WebSocket URL returned by the session mint; use it verbatim.
"wss://voice-relay-uat-abcdefg-ue.a.run.app/v1/realtime?model=grok-voice"
HMAC-SHA-256 signed opaque one-use relay ticket. Encodes expiry and a random nonce only — voice authorization is stored in the session record keyed by this ticket's SHA-256 hash, not in the token itself. Valid until expires_at; consumed on first successful connection (replay rejected). Do not log or share.
Timestamp after which ephemeral_key is rejected. Connect promptly — key_ttl_seconds is short by design.
Seconds from mint until ephemeral_key expires (300 s / 5 min).
Hard session length ceiling enforced by the relay (3,540 s). Mint a new session to continue.
Pass this array verbatim as the WebSocket subprotocols from a browser (browsers cannot set Authorization headers). Server-side callers should use Authorization: Bearer <ephemeral_key> instead.