Overview The createRealtimeClientSecret function creates a temporary client secret from OpenAI’s Realtime API that can be safely used in frontend applications. This allows frontend clients to connect directly to OpenAI’s Realtime API without exposing your API key.
Function Signature async function createRealtimeClientSecret ( opts : NavaiVoiceBackendOptions , req ?: CreateClientSecretRequest ) : Promise < OpenAIRealtimeClientSecretResponse >
Parameters opts
NavaiVoiceBackendOptions
required
Backend configuration options. Show NavaiVoiceBackendOptions properties
Your OpenAI API key. Can be omitted if allowApiKeyFromRequest is true and the request includes an API key.
defaultModel
string
default: "gpt-realtime"
Default model to use for Realtime API sessions.
Default voice for the assistant. Options: alloy, echo, shimmer, marin.
defaultInstructions
string
default: "You are a helpful assistant."
Default system instructions for the assistant.
Default language for responses. When set, adds “Always reply in .” to instructions.
Default voice accent. When set, adds “Use a accent while speaking.” to instructions.
Default voice tone. When set, adds “Use a tone while speaking.” to instructions.
Time-to-live for client secrets in seconds. Must be between 10 and 7200 (2 hours).
Whether to allow API keys to be provided in requests. Set to true for frontend-provided keys.
req
CreateClientSecretRequest
Request-specific overrides for the client secret. Show CreateClientSecretRequest properties
Override the default model.
Override the default voice.
Override the default instructions.
Override the default language.
Override the default voice accent.
Override the default voice tone.
OpenAI API key for this request. Only used if allowApiKeyFromRequest is true and openaiApiKey is not set in options.
Return Type OpenAIRealtimeClientSecretResponse
The response from OpenAI containing the client secret. The temporary client secret value to use for authentication.
Unix timestamp (seconds) when the client secret expires.
Optional session configuration returned by OpenAI.
Example Usage Basic Usage
With Request Overrides
Environment-Based Config
import { createRealtimeClientSecret } from '@navai/voice-backend' ; const opts = { openaiApiKey: process . env . OPENAI_API_KEY , defaultModel: 'gpt-realtime' , defaultVoice: 'marin' , clientSecretTtlSeconds: 600 }; const secret = await createRealtimeClientSecret ( opts ); console . log ( 'Client secret:' , secret . value ); console . log ( 'Expires at:' , new Date ( secret . expires_at * 1000 ));
Environment Variables When using getNavaiVoiceBackendOptionsFromEnv(), the following environment variables are read:
OPENAI_API_KEY - Your OpenAI API keyOPENAI_REALTIME_MODEL - Default modelOPENAI_REALTIME_VOICE - Default voiceOPENAI_REALTIME_INSTRUCTIONS - Default instructionsOPENAI_REALTIME_LANGUAGE - Default languageOPENAI_REALTIME_VOICE_ACCENT - Default voice accentOPENAI_REALTIME_VOICE_TONE - Default voice toneOPENAI_REALTIME_CLIENT_SECRET_TTL - TTL in seconds (default: 600)NAVAI_ALLOW_FRONTEND_API_KEY - Set to “true” to allow frontend API keys
Error Handling The function throws errors in the following cases:
Missing API key (no openaiApiKey and allowApiKeyFromRequest is false)
Invalid clientSecretTtlSeconds (must be between 10 and 7200)
OpenAI API request failure (non-200 response)
Request API key provided but allowApiKeyFromRequest is false
Always validate the expires_at timestamp on the client side and request a new secret before expiration.
Source Reference Defined in: packages/voice-backend/src/index.ts:160 