resources/realtime/subresources/transcription_sessions/index.md +0 −394 deleted
File Deleted View Diff
1# Transcription Sessions
2
3## Create transcription session
4
5**post** `/realtime/transcription_sessions`
6
7Create an ephemeral API token for use in client-side applications with the
8Realtime API specifically for realtime transcriptions.
9Can be configured with the same session parameters as the `transcription_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 transcription session object, plus an ephemeral key.
16
17### Body Parameters
18
19- `include: optional array of "item.input_audio_transcription.logprobs"`
20
21 The set of items to include in the transcription. Current available items are:
22 `item.input_audio_transcription.logprobs`
23
24 - `"item.input_audio_transcription.logprobs"`
25
26- `input_audio_format: optional "pcm16" or "g711_ulaw" or "g711_alaw"`
27
28 The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
29 For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate,
30 single channel (mono), and little-endian byte order.
31
32 - `"pcm16"`
33
34 - `"g711_ulaw"`
35
36 - `"g711_alaw"`
37
38- `input_audio_noise_reduction: optional object { type }`
39
40 Configuration for input audio noise reduction. This can be set to `null` to turn off.
41 Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model.
42 Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio.
43
44 - `type: optional NoiseReductionType`
45
46 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.
47
48 - `"near_field"`
49
50 - `"far_field"`
51
52- `input_audio_transcription: optional AudioTranscription`
53
54 Configuration for input audio transcription. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service.
55
56 - `delay: optional "minimal" or "low" or "medium" or 2 more`
57
58 Controls how long the model waits before emitting transcription text.
59 Higher values can improve transcription accuracy at the cost of latency.
60 Only supported with `gpt-realtime-whisper` in GA Realtime sessions.
61
62 - `"minimal"`
63
64 - `"low"`
65
66 - `"medium"`
67
68 - `"high"`
69
70 - `"xhigh"`
71
72 - `language: optional string`
73
74 The language of the input audio. Supplying the input language in
75 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format
76 will improve accuracy and latency.
77
78 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
79
80 The model to use 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`. Use `gpt-4o-transcribe-diarize` when you need diarization with speaker labels.
81
82 - `string`
83
84 - `"whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
85
86 The model to use 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`. Use `gpt-4o-transcribe-diarize` when you need diarization with speaker labels.
87
88 - `"whisper-1"`
89
90 - `"gpt-4o-mini-transcribe"`
91
92 - `"gpt-4o-mini-transcribe-2025-12-15"`
93
94 - `"gpt-4o-transcribe"`
95
96 - `"gpt-4o-transcribe-diarize"`
97
98 - `"gpt-realtime-whisper"`
99
100 - `prompt: optional string`
101
102 An optional text to guide the model's style or continue a previous audio
103 segment.
104 For `whisper-1`, the [prompt is a list of keywords](/docs/guides/speech-to-text#prompting).
105 For `gpt-4o-transcribe` models (excluding `gpt-4o-transcribe-diarize`), the prompt is a free text string, for example "expect words related to technology".
106 Prompt is not supported with `gpt-realtime-whisper` in GA Realtime sessions.
107
108- `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
109
110 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.
111
112 - `prefix_padding_ms: optional number`
113
114 Amount of audio to include before the VAD detected speech (in
115 milliseconds). Defaults to 300ms.
116
117 - `silence_duration_ms: optional number`
118
119 Duration of silence to detect speech stop (in milliseconds). Defaults
120 to 500ms. With shorter values the model will respond more quickly,
121 but may jump in on short pauses from the user.
122
123 - `threshold: optional number`
124
125 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A
126 higher threshold will require louder audio to activate the model, and
127 thus might perform better in noisy environments.
128
129 - `type: optional "server_vad"`
130
131 Type of turn detection. Only `server_vad` is currently supported for transcription sessions.
132
133 - `"server_vad"`
134
135### Returns
136
137- `client_secret: object { expires_at, value }`
138
139 Ephemeral key returned by the API. Only present when the session is
140 created on the server via REST API.
141
142 - `expires_at: number`
143
144 Timestamp for when the token expires. Currently, all tokens expire
145 after one minute.
146
147 - `value: string`
148
149 Ephemeral key usable in client environments to authenticate connections
150 to the Realtime API. Use this in client-side environments rather than
151 a standard API token, which should only be used server-side.
152
153- `input_audio_format: optional string`
154
155 The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
156
157- `input_audio_transcription: optional object { language, model, prompt }`
158
159 Configuration of the transcription model.
160
161 - `language: optional string`
162
163 The language of the input audio.
164
165 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
166
167 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`.
168
169 - `string`
170
171 - `"whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
172
173 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`.
174
175 - `"whisper-1"`
176
177 - `"gpt-4o-mini-transcribe"`
178
179 - `"gpt-4o-mini-transcribe-2025-12-15"`
180
181 - `"gpt-4o-transcribe"`
182
183 - `"gpt-4o-transcribe-diarize"`
184
185 - `"gpt-realtime-whisper"`
186
187 - `prompt: optional string`
188
189 The prompt configured for input audio transcription, when present.
190
191- `modalities: optional array of "text" or "audio"`
192
193 The set of modalities the model can respond with. To disable audio,
194 set this to ["text"].
195
196 - `"text"`
197
198 - `"audio"`
199
200- `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
201
202 Configuration for turn detection. Can be set to `null` to turn off. Server
203 VAD means that the model will detect the start and end of speech based on
204 audio volume and respond at the end of user speech.
205
206 - `prefix_padding_ms: optional number`
207
208 Amount of audio to include before the VAD detected speech (in
209 milliseconds). Defaults to 300ms.
210
211 - `silence_duration_ms: optional number`
212
213 Duration of silence to detect speech stop (in milliseconds). Defaults
214 to 500ms. With shorter values the model will respond more quickly,
215 but may jump in on short pauses from the user.
216
217 - `threshold: optional number`
218
219 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A
220 higher threshold will require louder audio to activate the model, and
221 thus might perform better in noisy environments.
222
223 - `type: optional string`
224
225 Type of turn detection, only `server_vad` is currently supported.
226
227### Example
228
229```http
230curl https://api.openai.com/v1/realtime/transcription_sessions \
231 -H 'Content-Type: application/json' \
232 -H "Authorization: Bearer $OPENAI_API_KEY" \
233 -d '{}'
234```
235
236#### Response
237
238```json
239{
240 "client_secret": {
241 "expires_at": 0,
242 "value": "value"
243 },
244 "input_audio_format": "input_audio_format",
245 "input_audio_transcription": {
246 "language": "language",
247 "model": "string",
248 "prompt": "prompt"
249 },
250 "modalities": [
251 "text"
252 ],
253 "turn_detection": {
254 "prefix_padding_ms": 0,
255 "silence_duration_ms": 0,
256 "threshold": 0,
257 "type": "type"
258 }
259}
260```
261
262### Example
263
264```http
265curl -X POST https://api.openai.com/v1/realtime/transcription_sessions \
266 -H "Authorization: Bearer $OPENAI_API_KEY" \
267 -H "Content-Type: application/json" \
268 -d '{}'
269```
270
271#### Response
272
273```json
274{
275 "id": "sess_BBwZc7cFV3XizEyKGDCGL",
276 "object": "realtime.transcription_session",
277 "modalities": ["audio", "text"],
278 "turn_detection": {
279 "type": "server_vad",
280 "threshold": 0.5,
281 "prefix_padding_ms": 300,
282 "silence_duration_ms": 200
283 },
284 "input_audio_format": "pcm16",
285 "input_audio_transcription": {
286 "model": "gpt-4o-transcribe",
287 "language": null,
288 "prompt": ""
289 },
290 "client_secret": null
291}
292```
293
294## Domain Types
295
296### Transcription Session Create Response
297
298- `TranscriptionSessionCreateResponse object { client_secret, input_audio_format, input_audio_transcription, 2 more }`
299
300 A new Realtime transcription session configuration.
301
302 When a session is created on the server via REST API, the session object
303 also contains an ephemeral key. Default TTL for keys is 10 minutes. This
304 property is not present when a session is updated via the WebSocket API.
305
306 - `client_secret: object { expires_at, value }`
307
308 Ephemeral key returned by the API. Only present when the session is
309 created on the server via REST API.
310
311 - `expires_at: number`
312
313 Timestamp for when the token expires. Currently, all tokens expire
314 after one minute.
315
316 - `value: string`
317
318 Ephemeral key usable in client environments to authenticate connections
319 to the Realtime API. Use this in client-side environments rather than
320 a standard API token, which should only be used server-side.
321
322 - `input_audio_format: optional string`
323
324 The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
325
326 - `input_audio_transcription: optional object { language, model, prompt }`
327
328 Configuration of the transcription model.
329
330 - `language: optional string`
331
332 The language of the input audio.
333
334 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
335
336 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`.
337
338 - `string`
339
340 - `"whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`
341
342 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`.
343
344 - `"whisper-1"`
345
346 - `"gpt-4o-mini-transcribe"`
347
348 - `"gpt-4o-mini-transcribe-2025-12-15"`
349
350 - `"gpt-4o-transcribe"`
351
352 - `"gpt-4o-transcribe-diarize"`
353
354 - `"gpt-realtime-whisper"`
355
356 - `prompt: optional string`
357
358 The prompt configured for input audio transcription, when present.
359
360 - `modalities: optional array of "text" or "audio"`
361
362 The set of modalities the model can respond with. To disable audio,
363 set this to ["text"].
364
365 - `"text"`
366
367 - `"audio"`
368
369 - `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`
370
371 Configuration for turn detection. Can be set to `null` to turn off. Server
372 VAD means that the model will detect the start and end of speech based on
373 audio volume and respond at the end of user speech.
374
375 - `prefix_padding_ms: optional number`
376
377 Amount of audio to include before the VAD detected speech (in
378 milliseconds). Defaults to 300ms.
379
380 - `silence_duration_ms: optional number`
381
382 Duration of silence to detect speech stop (in milliseconds). Defaults
383 to 500ms. With shorter values the model will respond more quickly,
384 but may jump in on short pauses from the user.
385
386 - `threshold: optional number`
387
388 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A
389 higher threshold will require louder audio to activate the model, and
390 thus might perform better in noisy environments.
391
392 - `type: optional string`
393
394 Type of turn detection, only `server_vad` is currently supported.