API Reference

Complete reference for the ItanniX Realtime API endpoints. All endpoints are compatible with OpenAI's Realtime API protocol.

Base URL

https://api.itannix.com

Endpoints

PurposePath
Create Session/v1/realtime/sessions
WebRTC SDP Exchange/v1/realtime

Authentication

All requests require a X-Client-Id header identifying your device/client, and a X-Client-Secret header for secure authentication.

Required Headers

X-Client-Id required
Your device/client identifier (UUID format)
X-Client-Secret recommended
Device-generated secret for authentication (32+ chars)

Trust On First Use (TOFU): The first time a device connects with a secret, it is enrolled. Subsequent connections must use the same secret. Generate a random secret on your device and store it securely.

Optional Headers

X-Demo-Mode Set to "true" for demo/testing (bypasses client validation)
X-Assistant-Id Override the assistant assigned to the client (for testing specific assistants)
POST /v1/realtime/sessions

Creates a new WebRTC session. Returns session info and ICE servers for establishing the WebRTC connection.

Headers

X-Client-Id required
Your device/client identifier
X-Client-Secret required
Your device-generated secret
Content-Type required
application/json
X-Demo-Mode
Set to 'true' for demo mode (optional)
X-Assistant-Id
Override assistant ID (optional)

Request Body

{
  "modalities": ["text", "audio"]
}

Response

{
  "id": "session_abc123",
  "iceServers": [
    {
      "urls": ["turn:relay.itannix.com:3478"],
      "username": "turn_user",
      "credential": "turn_password"
    }
  ]
}

Response Fields

  • id - Session identifier
  • iceServers - Array of STUN/TURN servers for WebRTC NAT traversal
POST /v1/realtime

Exchanges WebRTC SDP (Session Description Protocol) offer/answer. This establishes the WebRTC peer connection for bidirectional audio streaming.

Headers

X-Client-Id required
Your device/client identifier
X-Client-Secret required
Your device-generated secret
Content-Type required
application/sdp
X-Demo-Mode
Set to 'true' for demo mode (optional)
X-Assistant-Id
Override assistant ID (optional)

Request Body

v=0
o=- 1234567890 2 IN IP4 127.0.0.1
s=-
t=0 0
m=audio 9 UDP/TLS/RTP/SAVPF 111
a=rtpmap:111 opus/48000/2
...

Response

v=0
o=- 9876543210 2 IN IP4 127.0.0.1
s=-
t=0 0
m=audio 9 UDP/TLS/RTP/SAVPF 111
a=rtpmap:111 opus/48000/2
...

WebRTC Protocol

This endpoint follows the standard WebRTC SDP exchange:

  1. Client creates offer with createOffer()
  2. Client sends offer SDP to this endpoint
  3. Server responds with answer SDP
  4. Client sets remote description with answer
  5. WebRTC connection established, audio streams begin

Message Format

Once the WebRTC connection is established, communication happens via the data channel using JSON messages. The message format is identical to OpenAI's Realtime API.

Transcript Messages

User Transcript 
{
  "type": "conversation.item.input_audio_transcription.completed",
  "transcript": "Hello, how are you?"
}
Assistant Transcript (Streaming) 
{
  "type": "response.audio_transcript.delta",
  "delta": "I'm doing well, thank you"
}

Function Calls

Function Call Request 
{
  "type": "response.output_item.done",
  "item": {
    "type": "function_call",
    "id": "call_abc123",
    "call_id": "call_abc123",
    "name": "get_weather",
    "arguments": "{\"location\": \"San Francisco\"}"
  }
}
Function Call Response 
{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"temperature\": 72, \"condition\": \"sunny\"}"
  }
}

// Then trigger response generation
{
  "type": "response.create"
}

Client-Side Function Calls

Some function calls must be handled by your device. When you receive these via the data channel, execute the action locally and send the result back.

Important: These functions require hardware access and must be implemented on your device. The server cannot execute them remotely.

adjust_device_volume

Increase or decrease device volume by 10%

Parameters 
{
  "action": "increase" | "decrease"
}

set_device_volume

Set device volume to a specific level

Parameters 
{
  "volume_level": 0-100  // percentage
}

quiet_device

Mute device audio (set volume to 0%)

Parameters 
{} // No parameters

stop_audio

Stop currently playing audio/music (does not mute)

Parameters 
{} // No parameters
Handling Client-Side Functions 
dataChannel.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === 'response.output_item.done' && 
      message.item?.type === 'function_call') {
    const { name, arguments: args, call_id } = message.item;
    const params = JSON.parse(args);
    let result;
    
    switch (name) {
      case 'adjust_device_volume':
        result = adjustVolume(params.action); // Your implementation
        break;
      case 'set_device_volume':
        result = setVolume(params.volume_level); // Your implementation
        break;
      case 'quiet_device':
        result = muteDevice(); // Your implementation
        break;
      case 'stop_audio':
        result = stopAudio(); // Your implementation
        break;
      default:
        return; // Server-side function, no action needed
    }
    
    // Send result back
    dataChannel.send(JSON.stringify({
      type: 'conversation.item.create',
      item: {
        type: 'function_call_output',
        call_id: call_id,
        output: JSON.stringify({ success: true, ...result })
      }
    }));
    dataChannel.send(JSON.stringify({ type: 'response.create' }));
  }
};

Error Responses

All errors follow standard HTTP status codes with JSON error details:

Error Response Format 
{
  "error": {
    "message": "Missing X-Client-Id header",
    "type": "invalid_request_error",
    "code": "missing_header"
  }
}
400 Bad Request - Invalid request format or missing required headers
401 Unauthorized - Invalid or missing client ID
404 Not Found - Client ID not found or not activated
500 Internal Server Error - Server-side error