OpenAI Realtime

Mint short-lived OpenAI Realtime session tokens so browsers and apps connect directly — without ever seeing your API key.

This Module creates ephemeral session tokens for OpenAI's Realtime API (live, low-latency voice and transcription). Your workflow hands the token to the client; the client then talks to OpenAI directly. Audio never flows through the platform, and the workspace API key never reaches the client.

How it works

1. The Token reaches a Realtime Task; the Task asks OpenAI for an ephemeral session using the Environment's API key.
2. The Task saves the session details — including a client_secret that is valid for roughly 60 seconds.
3. Your workflow returns the secret to the client (for example via an Output Task or an API response).
4. The client uses the secret to open its own connection to the Realtime API and streams audio directly.

Configuration

Each OpenAI Module is configured separately, per Environment — this Module has its own API key, so you can reuse the key you set on the core OpenAI Module or use a dedicated one (for example to track this capability's spend on its own).

Field	Type	Required	Example	Description
OpenAI API Key	string	Yes	sk-...	Your OpenAI API key for this Module. Stored securely. Find it in OpenAI Console → API keys → Create new secret key.
OpenAI Organization	string	No	org-abc123	Your OpenAI organization ID, if your account belongs to one.

Tasks

All Tasks in this Module are Generic (all Channels) — they run the same regardless of how the Session was started.

Output fields: type a variable name without braces (for example session) and pick its type (string, number, true/false, object, date). The Task saves its result there, and any later Task can use it by writing {session}.

OpenAIRealtimeSessionTokenTask

Mints an ephemeral Realtime session token. The client uses the returned client_secret to connect directly to the Realtime API for about 60 seconds.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-realtime-preview-2024-12-17	Realtime model. Default: gpt-4o-realtime-preview-2024-12-17.
Voice	dropdown	No	alloy	Initial voice for assistant audio output. One of alloy, echo, fable, onyx, nova, shimmer, ash, ballad, coral, sage, verse. Default: empty → OpenAI's default voice.
Instructions	string	No	You are a friendly voice agent.	Optional system instructions for the realtime session. Supports {variable} placeholders.
Output Variable	object	Yes	session	Variable name (no braces). Receives an entry with client_secret.value, client_secret.expires_at, and the session id.

Example: Set Model = gpt-4o-realtime-preview-2024-12-17, Voice = alloy, Instructions = You are a friendly voice agent., Output Variable = session. The Task saves the session entry to session; the client reads {session}'s client_secret.value and connects to OpenAI directly before it expires (about 60 seconds later).

OpenAIRealtimeTranscriptionSessionTask

Mints an ephemeral Realtime transcription session token. Same client-direct pattern as OpenAIRealtimeSessionTokenTask, but for streaming transcription only.

Property	Type	Required	Example	Description
Model	string	Yes	gpt-4o-mini-transcribe	Transcription model. Default: gpt-4o-mini-transcribe.
Output Variable	object	Yes	session	Variable name (no braces). Receives the session entry with its client_secret.

Example: Set Model = gpt-4o-mini-transcribe, Output Variable = session. The Task saves the transcription session entry to session; the client uses its client_secret.value to stream audio for live transcription.

Common recipes

Hand a browser a live voice session

When the user asks to talk, mint a fresh Realtime token and return the client_secret so the browser connects to OpenAI directly. Input and Output Tasks come from the Standard Module.

1. InputTask — Output Variable = userMessage (the user asks to start a voice chat).
2. OpenAIRealtimeSessionTokenTask — Model = gpt-4o-realtime-preview-2024-12-17, Voice = alloy, Instructions = You are a friendly voice agent., Output Variable = session.
3. OutputTask — Message = {session}; the client extracts client_secret.value and opens its own Realtime connection immediately — the secret expires in about a minute.

Best practices

1. Hand the secret over immediately — the client_secret expires in about a minute; mint it as the last step before the client connects.
2. Mint per connection — request a fresh token for every client connection instead of reusing one.

warning

The returned client_secret grants direct access to the Realtime API until it expires. Send it only to the client that will use it — never log it or store it in long-lived Session data.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required property is missing or an output field is not a valid variable name — details
4001	ModuleException	OpenAI rejected the session request or the call failed — details
4008	ModuleMissingConfiguration	The OpenAI API key is not set in the OpenAI Module's Environment configuration — details
4009	ModuleInputEmpty	A required input resolved to an empty value at runtime — details
4012	ModuleInvalidData	The Session data could not be read or OpenAI's response could not be processed — details

See the Error Code Reference for the full list.

Related pages

• OpenAI Module — the family core; the API key is configured there.
• OpenAI Audio — request/response text-to-speech and transcription when you don't need a live connection.