Sample - OpenAI API
POST/realtime/sessions

Create a Realtime session

Creates an ephemeral Realtime API session for client-side applications. Supply client_secret and configure modalities, audio, tools, turn detection, and response limits as needed. The response includes the created session configuration and an ephemeral client token that expires after one minute.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

16 body fields

Configuration for a new Realtime session and its ephemeral client authentication key. client_secret is required.

client_secretobjectrequired
Ephemeral key returned by the API.
modalitiesarrayoptional
The set of modalities the model can respond with. To disable audio, set this to ["text"].
instructionsstringoptional
The default system instructions (i.e. system message) prepended to model calls. This field allows the client to guide the model on desired responses. The model can be instructed on response content and format, (e.g. "be extremely succinct", "act friendly", "here are examples of good responses") and on audio behavior (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The instructions are not guaranteed to be followed by the model, but they provide guidance to the model on the desired behavior. Note that the server sets default instructions which will be used if this field is not set and are visible in the `session.created` event at the start of the session.
voicestringoptional
The voice the model uses to respond. Supported built-in voices are `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed during the session once the model has responded with audio at least once.
input_audio_formatstringoptional
The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
output_audio_formatstringoptional
The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
input_audio_transcriptionobjectoptional
Configuration for input audio transcription, defaults to off and can be set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs asynchronously and should be treated as rough guidance rather than the representation understood by the model.
speednumberoptional
The speed of the model's spoken response. 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. This value can only be changed in between model turns, not while a response is in progress.
Default:1
tracingstringoptional
Configuration options for tracing. Set to null to disable tracing. Once tracing is enabled for a session, the configuration cannot be modified. `auto` will create a trace for the session with default values for the workflow name, group id, and metadata.
Allowed:autoDefault:auto
turn_detectionobjectoptional
Configuration for turn detection. Can be set to `null` to turn off. Server VAD means that the model will detect the start and end of speech based on audio volume and respond at the end of user speech.
toolsarray<object>optional
Tools (functions) available to the model.
tool_choicestringoptional
How the model chooses tools. Options are `auto`, `none`, `required`, or specify a function.
temperaturenumberoptional
Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
max_response_output_tokensintegeroptional
Maximum number of output tokens for a single assistant response, inclusive of tool calls. Provide an integer between 1 and 4096 to limit output tokens, or `inf` for the maximum available tokens for a given model. Defaults to `inf`.
truncationstringoptional
When the number of tokens in a conversation exceeds the model's input token limit, the conversation be truncated, meaning messages (starting from the oldest) will not be included in the model's context. A 32k context model with 4,096 max output tokens can only include 28,224 tokens in the context before truncation occurs. Clients can configure truncation behavior to truncate with a lower max token limit, which is an effective way to control token usage and cost. Truncation will reduce the number of cached tokens on the next turn (busting the cache), since messages are dropped from the beginning of the context. However, clients can also configure truncation to retain messages up to a fraction of the maximum context size, which will reduce the need for future truncations and thus improve the cache rate. Truncation can be disabled entirely, which means the server will never truncate but would instead return an error if the conversation exceeds the model's input token limit.
Allowed:autodisabled
promptobjectoptional
Reference to a prompt template and its variables. [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code).

1 status code
200Returns the created Realtime session object with its session identifier, expiration timestamp, model, modality and audio configuration, tools, and ephemeral client credentials.
idstringoptional
Unique identifier for the session that looks like `sess_1234567890abcdef`.
objectstringoptional
The object type. Always `realtime.session`.
expires_atintegeroptional
Expiration timestamp for the session, in seconds since epoch.
includearray<string>optional
Additional fields to include in server outputs. - `item.input_audio_transcription.logprobs`: Include logprobs for input audio transcription.
modelstringoptional
The Realtime model used for this session.
output_modalitiesarrayoptional
The set of modalities the model can respond with. To disable audio, set this to ["text"].
instructionsstringoptional
The default system instructions (i.e. system message) prepended to model calls. This field allows the client to guide the model on desired responses. The model can be instructed on response content and format, (e.g. "be extremely succinct", "act friendly", "here are examples of good responses") and on audio behavior (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The instructions are not guaranteed to be followed by the model, but they provide guidance to the model on the desired behavior. Note that the server sets default instructions which will be used if this field is not set and are visible in the `session.created` event at the start of the session.
audioobjectoptional
Configuration for input and output audio for the session.
tracingstringoptional
Configuration options for tracing. Set to null to disable tracing. Once tracing is enabled for a session, the configuration cannot be modified. `auto` will create a trace for the session with default values for the workflow name, group id, and metadata.
Allowed:autoDefault:auto
turn_detectionobjectoptional
Configuration for turn detection. Can be set to `null` to turn off. Server VAD means that the model will detect the start and end of speech based on audio volume and respond at the end of user speech.
toolsarray<FunctionTool>optional
Tools (functions) available to the model.
tool_choicestringoptional
How the model chooses tools. Options are `auto`, `none`, `required`, or specify a function.
max_output_tokensintegeroptional
Maximum number of output tokens for a single assistant response, inclusive of tool calls. Provide an integer between 1 and 4096 to limit output tokens, or `inf` for the maximum available tokens for a given model. Defaults to `inf`.

Error handling

client_secret is required and must include both value and expires_at. Use pcm16, g711_ulaw, or g711_alaw for audio formats, text or audio for modalities, and server_vad for turn detection. speed must be between 0.25 and 1.5, temperature must be between 0.6 and 1.2, and max_response_output_tokens must be an integer from 1 to 4096 or inf.