resources/realtime/subresources/sessions/index.md +0 −1068 deleted
File Deleted View Diff
1# Sessions
2
3## Create session
4
5**post** `/realtime/sessions`
6
7Create an ephemeral API token for use in client-side applications with the
8Realtime API. Can be configured with the same session parameters as the
9`session.update` client event.
10
11It responds with a session object, plus a `client_secret` key which contains
12a usable ephemeral API token that can be used to authenticate browser clients
13for the Realtime API.
14
15Returns the created Realtime session object, plus an ephemeral key.
16
17### Body Parameters
18
19- `client_secret: object { expires_at, value }`
20
21 Ephemeral key returned by the API.
22
23 - `expires_at: number`
24
25 Timestamp for when the token expires. Currently, all tokens expire
26 after one minute.
27
28 - `value: string`
29
30 Ephemeral key usable in client environments to authenticate connections
31 to the Realtime API. Use this in client-side environments rather than
32 a standard API token, which should only be used server-side.
33
34- `input_audio_format: optional string`
35
36 The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
37
38- `input_audio_transcription: optional object { model }`
39
40 Configuration for input audio transcription, defaults to off and can be
41 set to `null` to turn off once on. Input audio transcription is not native
42 to the model, since the model consumes audio directly. Transcription runs
43 asynchronously and should be treated as rough guidance
44 rather than the representation understood by the model.
45
46 - `model: optional string`
47
48 The model to use for transcription.
49
50- `instructions: optional string`
51
52 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.
53 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.
54
55- `max_response_output_tokens: optional number or "inf"`
56
57 Maximum number of output tokens for a single assistant response,
58 inclusive of tool calls. Provide an integer between 1 and 4096 to
59 limit output tokens, or `inf` for the maximum available tokens for a
60 given model. Defaults to `inf`.
61
62 - `number`
63
64 - `"inf"`
65
66 - `"inf"`
67
68- `modalities: optional array of "text" or "audio"`
69
70 The set of modalities the model can respond with. To disable audio,
71 set this to ["text"].
72
73 - `"text"`
74
75 - `"audio"`
76
77- `output_audio_format: optional string`
78
79 The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
80
81- `prompt: optional ResponsePrompt`
82
83 Reference to a prompt template and its variables.
84 [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts).
85
86 - `id: string`
87
88 The unique identifier of the prompt template to use.
89
90 - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]`
91
92 Optional map of values to substitute in for variables in your
93 prompt. The substitution values can either be strings, or other
94 Response input types like images or files.
95
96 - `string`
97
98 - `ResponseInputText object { text, type }`
99
100 A text input to the model.
101
102 - `text: string`
103
104 The text input to the model.
105
106 - `type: "input_text"`
107
108 The type of the input item. Always `input_text`.
109
110 - `"input_text"`
111
112 - `ResponseInputImage object { detail, type, file_id, image_url }`
113
114 An image input to the model. Learn about [image inputs](/docs/guides/vision).
115
116 - `detail: "low" or "high" or "auto" or "original"`
117
118 The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.
119
120 - `"low"`
121
122 - `"high"`
123
124 - `"auto"`
125
126 - `"original"`
127
128 - `type: "input_image"`
129
130 The type of the input item. Always `input_image`.
131
132 - `"input_image"`
133
134 - `file_id: optional string`
135
136 The ID of the file to be sent to the model.
137
138 - `image_url: optional string`
139
140 The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
141
142 - `ResponseInputFile object { type, detail, file_data, 3 more }`
143
144 A file input to the model.
145
146 - `type: "input_file"`
147
148 The type of the input item. Always `input_file`.
149
150 - `"input_file"`
151
152 - `detail: optional "low" or "high"`
153
154 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.
155
156 - `"low"`
157
158 - `"high"`
159
160 - `file_data: optional string`
161
162 The content of the file to be sent to the model.
163
164 - `file_id: optional string`
165
166 The ID of the file to be sent to the model.
167
168 - `file_url: optional string`
169
170 The URL of the file to be sent to the model.
171
172 - `filename: optional string`
173
174 The name of the file to be sent to the model.
175
176 - `version: optional string`
177
178 Optional version of the prompt template.
179
180- `speed: optional number`
181
182 The speed of the model's spoken response. 1.0 is the default speed. 0.25 is
183 the minimum speed. 1.5 is the maximum speed. This value can only be changed
184 in between model turns, not while a response is in progress.
185
186- `temperature: optional number`
187
188 Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8.
189
190- `tool_choice: optional string`
191
192 How the model chooses tools. Options are `auto`, `none`, `required`, or
193 specify a function.
194
195- `tools: optional array of object { description, name, parameters, type }`
196
197 Tools (functions) available to the model.
198
199 - `description: optional string`
200
201 The description of the function, including guidance on when and how
202 to call it, and guidance about what to tell the user when calling
203 (if anything).
204
205 - `name: optional string`
206
207 The name of the function.
208
209 - `parameters: optional unknown`
210
211 Parameters of the function in JSON Schema.
212
213 - `type: optional "function"`
214
215 The type of the tool, i.e. `function`.
216
217 - `"function"`
218
219- `tracing: optional "auto" or object { group_id, metadata, workflow_name }`
220
221 Configuration options for tracing. Set to null to disable tracing. Once
222 tracing is enabled for a session, the configuration cannot be modified.
223
224 `auto` will create a trace for the session with default values for the
225 workflow name, group id, and metadata.
226
227 - `"auto"`
228
229 Default tracing mode for the session.
230
231 - `"auto"`
232
233 - `TracingConfiguration object { group_id, metadata, workflow_name }`
234
235 Granular configuration for tracing.
236
237 - `group_id: optional string`
238
239 The group id to attach to this trace to enable filtering and
240 grouping in the traces dashboard.
241
242 - `metadata: optional unknown`
243
244 The arbitrary metadata to attach to this trace to enable
245 filtering in the traces dashboard.
246
247 - `workflow_name: optional string`
248
249 The name of the workflow to attach to this trace. This is used to
250 name the trace in the traces dashboard.
251
252- `truncation: optional RealtimeTruncation`
253
254 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.
255
256 Clients can configure truncation behavior to truncate with a lower max token limit, which is an effective way to control token usage and cost.
257
258 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.
259
260 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.
261
262 - `"auto" or "disabled"`
263
264 The truncation strategy to use for the session. `auto` is the default truncation strategy. `disabled` will disable truncation and emit errors when the conversation exceeds the input token limit.
265
266 - `"auto"`
267
268 - `"disabled"`
269
270 - `RetentionRatioTruncation object { retention_ratio, type, token_limits }`
271
272 Retain a fraction of the conversation tokens when the conversation exceeds the input token limit. This allows you to amortize truncations across multiple turns, which can help improve cached token usage.
273
274 - `retention_ratio: number`
275
276 Fraction of post-instruction conversation tokens to retain (`0.0` - `1.0`) when the conversation exceeds the input token limit. Setting this to `0.8` means that messages will be dropped until 80% of the maximum allowed tokens are used. This helps reduce the frequency of truncations and improve cache rates.
277
278 - `type: "retention_ratio"`
279
280 Use retention ratio truncation.
281
282 - `"retention_ratio"`
283
284 - `token_limits: optional object { post_instructions }`
285
286 Optional custom token limits for this truncation strategy. If not provided, the model's default token limits will be used.
287
288 - `post_instructions: optional number`
289
290 Maximum tokens allowed in the conversation after instructions (which including tool definitions). For example, setting this to 5,000 would mean that truncation would occur when the conversation exceeds 5,000 tokens after instructions. This cannot be higher than the model's context window size minus the maximum output tokens.
291
292- `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
293
294 Configuration for turn detection. Can be set to `null` to turn off. Server
295 VAD means that the model will detect the start and end of speech based on
296 audio volume and respond at the end of user speech.
297
298 - `prefix_padding_ms: optional number`
299
300 Amount of audio to include before the VAD detected speech (in
301 milliseconds). Defaults to 300ms.
302
303 - `silence_duration_ms: optional number`
304
305 Duration of silence to detect speech stop (in milliseconds). Defaults
306 to 500ms. With shorter values the model will respond more quickly,
307 but may jump in on short pauses from the user.
308
309 - `threshold: optional number`
310
311 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A
312 higher threshold will require louder audio to activate the model, and
313 thus might perform better in noisy environments.
314
315 - `type: optional string`
316
317 Type of turn detection, only `server_vad` is currently supported.
318
319- `voice: optional string or "alloy" or "ash" or "ballad" or 7 more or object { id }`
320
321 The voice the model uses to respond. Supported built-in voices are
322 `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`,
323 `marin`, and `cedar`. You may also provide a custom voice object with an
324 `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed during
325 the session once the model has responded with audio at least once.
326
327 - `string`
328
329 - `"alloy" or "ash" or "ballad" or 7 more`
330
331 - `"alloy"`
332
333 - `"ash"`
334
335 - `"ballad"`
336
337 - `"coral"`
338
339 - `"echo"`
340
341 - `"sage"`
342
343 - `"shimmer"`
344
345 - `"verse"`
346
347 - `"marin"`
348
349 - `"cedar"`
350
351 - `ID object { id }`
352
353 Custom voice reference.
354
355 - `id: string`
356
357 The custom voice ID, e.g. `voice_1234`.
358
359### Returns
360
361- `id: optional string`
362
363 Unique identifier for the session that looks like `sess_1234567890abcdef`.
364
365- `audio: optional object { input, output }`
366
367 Configuration for input and output audio for the session.
368
369 - `input: optional object { format, noise_reduction, transcription, turn_detection }`
370
371 - `format: optional RealtimeAudioFormats`
372
373 The PCM audio format. Only a 24kHz sample rate is supported.
374
375 - `PCMAudioFormat object { rate, type }`
376
377 The PCM audio format. Only a 24kHz sample rate is supported.
378
379 - `rate: optional 24000`
380
381 The sample rate of the audio. Always `24000`.
382
383 - `24000`
384
385 - `type: optional "audio/pcm"`
386
387 The audio format. Always `audio/pcm`.
388
389 - `"audio/pcm"`
390
391 - `PCMUAudioFormat object { type }`
392
393 The G.711 μ-law format.
394
395 - `type: optional "audio/pcmu"`
396
397 The audio format. Always `audio/pcmu`.
398
399 - `"audio/pcmu"`
400
401 - `PCMAAudioFormat object { type }`
402
403 The G.711 A-law format.
404
405 - `type: optional "audio/pcma"`
406
407 The audio format. Always `audio/pcma`.
408
409 - `"audio/pcma"`
410
411 - `noise_reduction: optional object { type }`
412
413 Configuration for input audio noise reduction.
414
415 - `type: optional NoiseReductionType`
416
417 Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones.
418
419 - `"near_field"`
420
421 - `"far_field"`
422
423 - `transcription: optional object { language, model, prompt }`
424
425 Configuration for input audio transcription.
426
427 - `language: optional string`
428
429 The language of the input audio.
430
431 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
432
433 The model used for transcription. Current options are `whisper-1`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`, and `gpt-realtime-whisper`.
434
435 - `string`
436
437 - `"whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
438
439 The model used for transcription. Current options are `whisper-1`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`, and `gpt-realtime-whisper`.
440
441 - `"whisper-1"`
442
443 - `"gpt-4o-mini-transcribe"`
444
445 - `"gpt-4o-mini-transcribe-2025-12-15"`
446
447 - `"gpt-4o-transcribe"`
448
449 - `"gpt-4o-transcribe-diarize"`
450
451 - `"gpt-realtime-whisper"`
452
453 - `prompt: optional string`
454
455 The prompt configured for input audio transcription, when present.
456
457 - `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
458
459 Configuration for turn detection.
460
461 - `prefix_padding_ms: optional number`
462
463 - `silence_duration_ms: optional number`
464
465 - `threshold: optional number`
466
467 - `type: optional string`
468
469 Type of turn detection, only `server_vad` is currently supported.
470
471 - `output: optional object { format, speed, voice }`
472
473 - `format: optional RealtimeAudioFormats`
474
475 The PCM audio format. Only a 24kHz sample rate is supported.
476
477 - `speed: optional number`
478
479 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more`
480
481 - `string`
482
483 - `"alloy" or "ash" or "ballad" or 7 more`
484
485 - `"alloy"`
486
487 - `"ash"`
488
489 - `"ballad"`
490
491 - `"coral"`
492
493 - `"echo"`
494
495 - `"sage"`
496
497 - `"shimmer"`
498
499 - `"verse"`
500
501 - `"marin"`
502
503 - `"cedar"`
504
505- `expires_at: optional number`
506
507 Expiration timestamp for the session, in seconds since epoch.
508
509- `include: optional array of "item.input_audio_transcription.logprobs"`
510
511 Additional fields to include in server outputs.
512
513 - `item.input_audio_transcription.logprobs`: Include logprobs for input audio transcription.
514
515 - `"item.input_audio_transcription.logprobs"`
516
517- `instructions: optional string`
518
519 The default system instructions (i.e. system message) prepended to model
520 calls. This field allows the client to guide the model on desired
521 responses. The model can be instructed on response content and format,
522 (e.g. "be extremely succinct", "act friendly", "here are examples of good
523 responses") and on audio behavior (e.g. "talk quickly", "inject emotion
524 into your voice", "laugh frequently"). The instructions are not guaranteed
525 to be followed by the model, but they provide guidance to the model on the
526 desired behavior.
527
528 Note that the server sets default instructions which will be used if this
529 field is not set and are visible in the `session.created` event at the
530 start of the session.
531
532- `max_output_tokens: optional number or "inf"`
533
534 Maximum number of output tokens for a single assistant response,
535 inclusive of tool calls. Provide an integer between 1 and 4096 to
536 limit output tokens, or `inf` for the maximum available tokens for a
537 given model. Defaults to `inf`.
538
539 - `number`
540
541 - `"inf"`
542
543 - `"inf"`
544
545- `model: optional string`
546
547 The Realtime model used for this session.
548
549- `object: optional string`
550
551 The object type. Always `realtime.session`.
552
553- `output_modalities: optional array of "text" or "audio"`
554
555 The set of modalities the model can respond with. To disable audio,
556 set this to ["text"].
557
558 - `"text"`
559
560 - `"audio"`
561
562- `tool_choice: optional string`
563
564 How the model chooses tools. Options are `auto`, `none`, `required`, or
565 specify a function.
566
567- `tools: optional array of RealtimeFunctionTool`
568
569 Tools (functions) available to the model.
570
571 - `description: optional string`
572
573 The description of the function, including guidance on when and how
574 to call it, and guidance about what to tell the user when calling
575 (if anything).
576
577 - `name: optional string`
578
579 The name of the function.
580
581 - `parameters: optional unknown`
582
583 Parameters of the function in JSON Schema.
584
585 - `type: optional "function"`
586
587 The type of the tool, i.e. `function`.
588
589 - `"function"`
590
591- `tracing: optional "auto" or object { group_id, metadata, workflow_name }`
592
593 Configuration options for tracing. Set to null to disable tracing. Once
594 tracing is enabled for a session, the configuration cannot be modified.
595
596 `auto` will create a trace for the session with default values for the
597 workflow name, group id, and metadata.
598
599 - `"auto"`
600
601 Default tracing mode for the session.
602
603 - `"auto"`
604
605 - `TracingConfiguration object { group_id, metadata, workflow_name }`
606
607 Granular configuration for tracing.
608
609 - `group_id: optional string`
610
611 The group id to attach to this trace to enable filtering and
612 grouping in the traces dashboard.
613
614 - `metadata: optional unknown`
615
616 The arbitrary metadata to attach to this trace to enable
617 filtering in the traces dashboard.
618
619 - `workflow_name: optional string`
620
621 The name of the workflow to attach to this trace. This is used to
622 name the trace in the traces dashboard.
623
624- `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
625
626 Configuration for turn detection. Can be set to `null` to turn off. Server
627 VAD means that the model will detect the start and end of speech based on
628 audio volume and respond at the end of user speech.
629
630 - `prefix_padding_ms: optional number`
631
632 Amount of audio to include before the VAD detected speech (in
633 milliseconds). Defaults to 300ms.
634
635 - `silence_duration_ms: optional number`
636
637 Duration of silence to detect speech stop (in milliseconds). Defaults
638 to 500ms. With shorter values the model will respond more quickly,
639 but may jump in on short pauses from the user.
640
641 - `threshold: optional number`
642
643 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A
644 higher threshold will require louder audio to activate the model, and
645 thus might perform better in noisy environments.
646
647 - `type: optional string`
648
649 Type of turn detection, only `server_vad` is currently supported.
650
651### Example
652
653```http
654curl https://api.openai.com/v1/realtime/sessions \
655 -H 'Content-Type: application/json' \
656 -H "Authorization: Bearer $OPENAI_API_KEY" \
657 -d '{
658 "client_secret": {
659 "expires_at": 0,
660 "value": "value"
661 }
662 }'
663```
664
665#### Response
666
667```json
668{
669 "id": "id",
670 "audio": {
671 "input": {
672 "format": {
673 "rate": 24000,
674 "type": "audio/pcm"
675 },
676 "noise_reduction": {
677 "type": "near_field"
678 },
679 "transcription": {
680 "language": "language",
681 "model": "string",
682 "prompt": "prompt"
683 },
684 "turn_detection": {
685 "prefix_padding_ms": 0,
686 "silence_duration_ms": 0,
687 "threshold": 0,
688 "type": "type"
689 }
690 },
691 "output": {
692 "format": {
693 "rate": 24000,
694 "type": "audio/pcm"
695 },
696 "speed": 0,
697 "voice": "ash"
698 }
699 },
700 "expires_at": 0,
701 "include": [
702 "item.input_audio_transcription.logprobs"
703 ],
704 "instructions": "instructions",
705 "max_output_tokens": 0,
706 "model": "model",
707 "object": "object",
708 "output_modalities": [
709 "text"
710 ],
711 "tool_choice": "tool_choice",
712 "tools": [
713 {
714 "description": "description",
715 "name": "name",
716 "parameters": {},
717 "type": "function"
718 }
719 ],
720 "tracing": "auto",
721 "turn_detection": {
722 "prefix_padding_ms": 0,
723 "silence_duration_ms": 0,
724 "threshold": 0,
725 "type": "type"
726 }
727}
728```
729
730### Example
731
732```http
733curl -X POST https://api.openai.com/v1/realtime/sessions \
734 -H "Authorization: Bearer $OPENAI_API_KEY" \
735 -H "Content-Type: application/json" \
736 -d '{
737 "model": "gpt-realtime",
738 "modalities": ["audio", "text"],
739 "instructions": "You are a friendly assistant."
740 }'
741```
742
743#### Response
744
745```json
746{
747 "id": "sess_001",
748 "object": "realtime.session",
749 "model": "gpt-realtime-2025-08-25",
750 "modalities": ["audio", "text"],
751 "instructions": "You are a friendly assistant.",
752 "voice": "alloy",
753 "input_audio_format": "pcm16",
754 "output_audio_format": "pcm16",
755 "input_audio_transcription": {
756 "model": "whisper-1"
757 },
758 "turn_detection": null,
759 "tools": [],
760 "tool_choice": "none",
761 "temperature": 0.7,
762 "max_response_output_tokens": 200,
763 "speed": 1.1,
764 "tracing": "auto",
765 "client_secret": {
766 "value": "ek_abc123",
767 "expires_at": 1234567890
768 }
769}
770```
771
772## Domain Types
773
774### Session Create Response
775
776- `SessionCreateResponse object { id, audio, expires_at, 10 more }`
777
778 A Realtime session configuration object.
779
780 - `id: optional string`
781
782 Unique identifier for the session that looks like `sess_1234567890abcdef`.
783
784 - `audio: optional object { input, output }`
785
786 Configuration for input and output audio for the session.
787
788 - `input: optional object { format, noise_reduction, transcription, turn_detection }`
789
790 - `format: optional RealtimeAudioFormats`
791
792 The PCM audio format. Only a 24kHz sample rate is supported.
793
794 - `PCMAudioFormat object { rate, type }`
795
796 The PCM audio format. Only a 24kHz sample rate is supported.
797
798 - `rate: optional 24000`
799
800 The sample rate of the audio. Always `24000`.
801
802 - `24000`
803
804 - `type: optional "audio/pcm"`
805
806 The audio format. Always `audio/pcm`.
807
808 - `"audio/pcm"`
809
810 - `PCMUAudioFormat object { type }`
811
812 The G.711 μ-law format.
813
814 - `type: optional "audio/pcmu"`
815
816 The audio format. Always `audio/pcmu`.
817
818 - `"audio/pcmu"`
819
820 - `PCMAAudioFormat object { type }`
821
822 The G.711 A-law format.
823
824 - `type: optional "audio/pcma"`
825
826 The audio format. Always `audio/pcma`.
827
828 - `"audio/pcma"`
829
830 - `noise_reduction: optional object { type }`
831
832 Configuration for input audio noise reduction.
833
834 - `type: optional NoiseReductionType`
835
836 Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones.
837
838 - `"near_field"`
839
840 - `"far_field"`
841
842 - `transcription: optional object { language, model, prompt }`
843
844 Configuration for input audio transcription.
845
846 - `language: optional string`
847
848 The language of the input audio.
849
850 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
851
852 The model used for transcription. Current options are `whisper-1`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`, and `gpt-realtime-whisper`.
853
854 - `string`
855
856 - `"whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
857
858 The model used for transcription. Current options are `whisper-1`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`, and `gpt-realtime-whisper`.
859
860 - `"whisper-1"`
861
862 - `"gpt-4o-mini-transcribe"`
863
864 - `"gpt-4o-mini-transcribe-2025-12-15"`
865
866 - `"gpt-4o-transcribe"`
867
868 - `"gpt-4o-transcribe-diarize"`
869
870 - `"gpt-realtime-whisper"`
871
872 - `prompt: optional string`
873
874 The prompt configured for input audio transcription, when present.
875
876 - `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
877
878 Configuration for turn detection.
879
880 - `prefix_padding_ms: optional number`
881
882 - `silence_duration_ms: optional number`
883
884 - `threshold: optional number`
885
886 - `type: optional string`
887
888 Type of turn detection, only `server_vad` is currently supported.
889
890 - `output: optional object { format, speed, voice }`
891
892 - `format: optional RealtimeAudioFormats`
893
894 The PCM audio format. Only a 24kHz sample rate is supported.
895
896 - `speed: optional number`
897
898 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more`
899
900 - `string`
901
902 - `"alloy" or "ash" or "ballad" or 7 more`
903
904 - `"alloy"`
905
906 - `"ash"`
907
908 - `"ballad"`
909
910 - `"coral"`
911
912 - `"echo"`
913
914 - `"sage"`
915
916 - `"shimmer"`
917
918 - `"verse"`
919
920 - `"marin"`
921
922 - `"cedar"`
923
924 - `expires_at: optional number`
925
926 Expiration timestamp for the session, in seconds since epoch.
927
928 - `include: optional array of "item.input_audio_transcription.logprobs"`
929
930 Additional fields to include in server outputs.
931
932 - `item.input_audio_transcription.logprobs`: Include logprobs for input audio transcription.
933
934 - `"item.input_audio_transcription.logprobs"`
935
936 - `instructions: optional string`
937
938 The default system instructions (i.e. system message) prepended to model
939 calls. This field allows the client to guide the model on desired
940 responses. The model can be instructed on response content and format,
941 (e.g. "be extremely succinct", "act friendly", "here are examples of good
942 responses") and on audio behavior (e.g. "talk quickly", "inject emotion
943 into your voice", "laugh frequently"). The instructions are not guaranteed
944 to be followed by the model, but they provide guidance to the model on the
945 desired behavior.
946
947 Note that the server sets default instructions which will be used if this
948 field is not set and are visible in the `session.created` event at the
949 start of the session.
950
951 - `max_output_tokens: optional number or "inf"`
952
953 Maximum number of output tokens for a single assistant response,
954 inclusive of tool calls. Provide an integer between 1 and 4096 to
955 limit output tokens, or `inf` for the maximum available tokens for a
956 given model. Defaults to `inf`.
957
958 - `number`
959
960 - `"inf"`
961
962 - `"inf"`
963
964 - `model: optional string`
965
966 The Realtime model used for this session.
967
968 - `object: optional string`
969
970 The object type. Always `realtime.session`.
971
972 - `output_modalities: optional array of "text" or "audio"`
973
974 The set of modalities the model can respond with. To disable audio,
975 set this to ["text"].
976
977 - `"text"`
978
979 - `"audio"`
980
981 - `tool_choice: optional string`
982
983 How the model chooses tools. Options are `auto`, `none`, `required`, or
984 specify a function.
985
986 - `tools: optional array of RealtimeFunctionTool`
987
988 Tools (functions) available to the model.
989
990 - `description: optional string`
991
992 The description of the function, including guidance on when and how
993 to call it, and guidance about what to tell the user when calling
994 (if anything).
995
996 - `name: optional string`
997
998 The name of the function.
999
1000 - `parameters: optional unknown`
1001
1002 Parameters of the function in JSON Schema.
1003
1004 - `type: optional "function"`
1005
1006 The type of the tool, i.e. `function`.
1007
1008 - `"function"`
1009
1010 - `tracing: optional "auto" or object { group_id, metadata, workflow_name }`
1011
1012 Configuration options for tracing. Set to null to disable tracing. Once
1013 tracing is enabled for a session, the configuration cannot be modified.
1014
1015 `auto` will create a trace for the session with default values for the
1016 workflow name, group id, and metadata.
1017
1018 - `"auto"`
1019
1020 Default tracing mode for the session.
1021
1022 - `"auto"`
1023
1024 - `TracingConfiguration object { group_id, metadata, workflow_name }`
1025
1026 Granular configuration for tracing.
1027
1028 - `group_id: optional string`
1029
1030 The group id to attach to this trace to enable filtering and
1031 grouping in the traces dashboard.
1032
1033 - `metadata: optional unknown`
1034
1035 The arbitrary metadata to attach to this trace to enable
1036 filtering in the traces dashboard.
1037
1038 - `workflow_name: optional string`
1039
1040 The name of the workflow to attach to this trace. This is used to
1041 name the trace in the traces dashboard.
1042
1043 - `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
1044
1045 Configuration for turn detection. Can be set to `null` to turn off. Server
1046 VAD means that the model will detect the start and end of speech based on
1047 audio volume and respond at the end of user speech.
1048
1049 - `prefix_padding_ms: optional number`
1050
1051 Amount of audio to include before the VAD detected speech (in
1052 milliseconds). Defaults to 300ms.
1053
1054 - `silence_duration_ms: optional number`
1055
1056 Duration of silence to detect speech stop (in milliseconds). Defaults
1057 to 500ms. With shorter values the model will respond more quickly,
1058 but may jump in on short pauses from the user.
1059
1060 - `threshold: optional number`
1061
1062 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A
1063 higher threshold will require louder audio to activate the model, and
1064 thus might perform better in noisy environments.
1065
1066 - `type: optional string`
1067
1068 Type of turn detection, only `server_vad` is currently supported.