Implementation:Openai Openai node Realtime ClientSecrets

Knowledge Sources	Openai_Openai_node
Domains	SDK, Realtime, Authentication
Last Updated	2026-02-15 12:00 GMT

Overview

The ClientSecrets resource class creates ephemeral client secrets for authenticating browser-side connections to the OpenAI Realtime API.

Description

The ClientSecrets class extends APIResource and provides a single create method that calls the /realtime/client_secrets endpoint. This endpoint generates short-lived ephemeral tokens that can be safely used in client-side environments (such as web browsers) to authenticate WebSocket connections to the Realtime API, without exposing the server-side API key.

The response includes the generated secret value, its expiration timestamp, and the associated session configuration. The session can be either a realtime session (for conversational AI with audio/text) or a transcription session (for audio transcription). The expiration is configurable through the expires_after parameter, accepting values between 10 and 7200 seconds (2 hours), with a default of 600 seconds (10 minutes). A single client secret can be used to create multiple sessions until it expires.

The module defines comprehensive TypeScript types for both session types. The RealtimeSessionCreateResponse type covers conversational sessions with extensive configuration including audio formats, voice selection, turn detection (Server VAD and Semantic VAD), noise reduction, tool definitions (function tools and MCP tools), truncation behavior, and tracing configuration. The RealtimeTranscriptionSessionCreateResponse type covers transcription-only sessions with audio input configuration and turn detection settings.

Usage

Use this resource in server-side code to generate ephemeral tokens that are then passed to client-side applications for establishing Realtime API WebSocket connections. This is the recommended pattern for browser-based applications that need to connect to the Realtime API without exposing API keys.

Code Reference

Source Location

• Repository: openai-node
• File: src/resources/realtime/client-secrets.ts

Signature

export class ClientSecrets extends APIResource {
  create(body: ClientSecretCreateParams, options?: RequestOptions): APIPromise<ClientSecretCreateResponse>;
}

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
session	RealtimeTranscriptionSessionCreateRequest	No	Session configuration for either a realtime or transcription session
expires_after	ClientSecretCreateParams.ExpiresAfter	No	Expiration configuration with anchor ('created_at') and seconds (10-7200, default 600)

Outputs

Name	Type	Description
value	string	The generated client secret value for authentication
expires_at	number	Expiration timestamp in seconds since epoch
session	RealtimeTranscriptionSessionCreateResponse	The associated session configuration

Session Configuration

RealtimeSessionCreateResponse

Property	Type	Description
client_secret	RealtimeSessionClientSecret	Ephemeral key with value and expires_at
type	'realtime'	Always 'realtime' for conversational sessions
model	string	Realtime model (e.g., gpt-realtime, gpt-4o-realtime-preview)
instructions	string	System instructions prepended to model calls
output_modalities	'audio'>	Response modalities (defaults to ['audio'])
audio	Audio	Audio I/O configuration (format, voice, speed, transcription, VAD)
tools	McpTool>	Available tools for the model
max_output_tokens	'inf'	Maximum output tokens per response
tracing	TracingConfiguration | null	Trace configuration for the Traces Dashboard
truncation	RealtimeTruncation	Context window truncation behavior

Turn Detection Options

Type	Description
Server VAD	Simple voice activity detection based on audio volume with configurable threshold, silence duration, and prefix padding
Semantic VAD	Advanced turn detection using a model to estimate when user has finished speaking, with eagerness levels (low, medium, high)

Usage Examples

import OpenAI from 'openai';

const client = new OpenAI();

// Create a basic client secret for a realtime session
const clientSecret = await client.realtime.clientSecrets.create({});

console.log('Secret:', clientSecret.value);
console.log('Expires at:', new Date(clientSecret.expires_at * 1000));

// Create a client secret with session configuration
const configuredSecret = await client.realtime.clientSecrets.create({
  session: {
    type: 'realtime',
    model: 'gpt-4o-realtime-preview',
    instructions: 'You are a helpful assistant. Speak concisely.',
    output_modalities: ['audio'],
    audio: {
      output: {
        voice: 'coral',
      },
      input: {
        turn_detection: {
          type: 'semantic_vad',
          eagerness: 'medium',
        },
      },
    },
  },
  expires_after: {
    anchor: 'created_at',
    seconds: 3600,
  },
});

// Create a client secret for a transcription session
const transcriptionSecret = await client.realtime.clientSecrets.create({
  session: {
    type: 'transcription',
    audio: {
      input: {
        transcription: {
          model: 'gpt-4o-transcribe',
          language: 'en',
        },
      },
    },
  },
});

Key Types

RealtimeSessionClientSecret

interface RealtimeSessionClientSecret {
  expires_at: number;
  value: string;
}

RealtimeTranscriptionSessionTurnDetection

interface RealtimeTranscriptionSessionTurnDetection {
  prefix_padding_ms?: number;
  silence_duration_ms?: number;
  threshold?: number;
  type?: string;
}

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime