resources/live/methods/create/index.md +0 −533 deleted
File Deleted View Diff
1## Create session
2
3**post** `/live/sessions`
4
5Create a Live WebRTC session. Start with the [Live prompting guide](/api/docs/guides/live-prompting).
6
7### Body Parameters
8
9- `session: MediaSessionConfig`
10
11 Startup configuration for the Live session.
12
13 - `model: string or "gpt-live-1"`
14
15 The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
16
17 - `string`
18
19 - `"gpt-live-1"`
20
21 The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
22
23 - `"gpt-live-1"`
24
25 - `audio: optional object { output }`
26
27 Startup audio configuration. WebRTC and SIP negotiate their audio format on the media transport.
28
29 - `output: optional object { voice }`
30
31 Settings for speech generated by the Live model. Choose the voice before starting the session.
32
33 - `voice: optional string or "alloy" or "ash" or "ballad" or 19 more or CustomVoice`
34
35 The voice used for Live speech, as a built-in voice name or a custom voice object containing its ID. Defaults to `marin` and cannot change after startup.
36
37 - `string`
38
39 - `"alloy" or "ash" or "ballad" or 19 more`
40
41 The voice used for Live speech, as a built-in voice name or a custom voice object containing its ID. Defaults to `marin` and cannot change after startup.
42
43 - `"alloy"`
44
45 - `"ash"`
46
47 - `"ballad"`
48
49 - `"beacon"`
50
51 - `"bossa"`
52
53 - `"cedar"`
54
55 - `"cinder"`
56
57 - `"coral"`
58
59 - `"delta"`
60
61 - `"echo"`
62
63 - `"gleam"`
64
65 - `"marin"`
66
67 - `"meridian"`
68
69 - `"quartz"`
70
71 - `"ripple"`
72
73 - `"sage"`
74
75 - `"shimmer"`
76
77 - `"stone"`
78
79 - `"tempo"`
80
81 - `"verse"`
82
83 - `"vesper"`
84
85 - `"willow"`
86
87 - `CustomVoice object { id }`
88
89 - `id: string`
90
91 - `client: optional ClientConfig`
92
93 Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.
94
95 - `data_channel: DataChannelConfig`
96
97 Client and server event permissions for the WebRTC frontend data channel.
98
99 - `allowed_client_events: optional "all" or array of string`
100
101 Client event types that the frontend data channel may send. Use 'all' to allow every client event; an empty array allows none. Omission preserves the existing allow-all behavior.
102
103 - `"all"`
104
105 - `"all"`
106
107 - `array of string`
108
109 - `allowed_server_events: optional "all" or array of ServerEventSelector`
110
111 Server events that may be sent to the frontend data channel. Use 'all' to allow every server event; an empty array allows none. Omission preserves the existing allow-all behavior. Responses events use an object with type 'response.event' and a response_event selector.
112
113 - `"all"`
114
115 - `"all"`
116
117 - `array of ServerEventSelector`
118
119 - `type: string`
120
121 The outer Live server event type. Use 'response.event' for Responses events.
122
123 - `response_event: optional string`
124
125 The nested Responses event type. Required when type is 'response.event'; forbidden for other event types.
126
127 - `delegation: optional ClientDelegation or object { responses, type } or null`
128
129 Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend.
130
131 - `ClientDelegation object { type }`
132
133 Delegate tasks to your application. The Live session emits delegation events that your backend handles.
134
135 - `type: "client"`
136
137 The delegation owner. Always `client` for tasks handled by your application.
138
139 - `"client"`
140
141 - `Responses object { responses, type }`
142
143 Delegate tasks to a Responses model managed by the Live session.
144
145 - `responses: ResponsesDelegationConfig`
146
147 Backend model, prompt, and tools used when the Live session delegates a task to Responses.
148
149 - `model: string`
150
151 The model used for server-owned Responses delegations.
152
153 - `instructions: optional string or null`
154
155 Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt).
156
157 - `max_output_tokens: optional number or null`
158
159 Maximum number of output tokens for each delegated response.
160
161 - `parallel_tool_calls: optional boolean or null`
162
163 Whether the delegated Responses model may request multiple tool calls in a single response.
164
165 - `reasoning: optional object { effort, summary } or null`
166
167 Reasoning settings passed to each delegated Responses request.
168
169 - `effort: optional "none" or "minimal" or "low" or 3 more or null`
170
171 How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model.
172
173 - `"none"`
174
175 - `"minimal"`
176
177 - `"low"`
178
179 - `"medium"`
180
181 - `"high"`
182
183 - `"xhigh"`
184
185 - `summary: optional "concise" or "detailed" or "auto" or null`
186
187 The reasoning summary to request from the delegated Responses model, when supported.
188
189 - `"concise"`
190
191 - `"detailed"`
192
193 - `"auto"`
194
195 - `service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null`
196
197 Service tier for delegated Responses requests.
198
199 - `"auto"`
200
201 - `"default"`
202
203 - `"fast_tier_temp_pilot"`
204
205 - `"flex"`
206
207 - `"priority"`
208
209 - `"ultrafast"`
210
211 - `text: optional object { verbosity } or null`
212
213 Text generation settings passed to each delegated Responses request.
214
215 - `verbosity: optional "low" or "medium" or "high" or null`
216
217 The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery.
218
219 - `"low"`
220
221 - `"medium"`
222
223 - `"high"`
224
225 - `tool_choice: optional "auto" or "none" or "required" or object { name, type } or object { name, server_label, type }`
226
227 Controls which tool the Responses backend uses when handling a task delegated by the Live model.
228
229 - `LiveToolChoiceEnum = "auto" or "none" or "required"`
230
231 - `"auto"`
232
233 - `"none"`
234
235 - `"required"`
236
237 - `LiveFunctionToolChoiceParam object { name, type }`
238
239 - `name: string`
240
241 - `type: "function"`
242
243 - `"function"`
244
245 - `LiveMCPToolChoiceParam object { name, server_label, type }`
246
247 - `name: string`
248
249 - `server_label: string`
250
251 - `type: "mcp"`
252
253 - `"mcp"`
254
255 - `tools: optional array of FunctionTool or object { type }`
256
257 Tools available to the Responses backend while it handles tasks delegated by the Live model.
258
259 - `FunctionTool object { name, type, description, 2 more }`
260
261 A function tool available to the Responses backend when the Live model delegates a task.
262
263 - `name: string`
264
265 The name the delegated Responses model uses when calling this function.
266
267 - `type: "function"`
268
269 The tool type. Always `function`.
270
271 - `"function"`
272
273 - `description: optional string or null`
274
275 What the function does and when the delegated Responses model should call it.
276
277 - `parameters: optional map[unknown] or null`
278
279 A JSON Schema object describing the arguments accepted by the function.
280
281 - `strict: optional boolean or null`
282
283 Whether the delegated Responses model must follow the function’s parameter schema exactly.
284
285 - `WebSearch object { type }`
286
287 A web search tool available to the Live session’s Responses backend.
288
289 - `type: "web_search"`
290
291 The tool type. Always `web_search`.
292
293 - `"web_search"`
294
295 - `type: "responses"`
296
297 The delegation owner. Always `responses` for tasks handled by the Responses API.
298
299 - `"responses"`
300
301 - `input: optional array of InitialItem`
302
303 Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total.
304
305 - `Developer object { content, role, id, 2 more }`
306
307 A developer message included in the initial text history of a Live session.
308
309 - `content: array of object { text, type }`
310
311 The message content. Supply exactly one text part for the initial Live conversation history.
312
313 - `text: string`
314
315 The message text to include in the Live session’s initial conversation history.
316
317 - `type: optional "input_text"`
318
319 The text content type. Always `input_text`.
320
321 - `"input_text"`
322
323 - `role: "developer"`
324
325 The author of this history message. Always `developer`.
326
327 - `"developer"`
328
329 - `id: optional string or null`
330
331 An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
332
333 - `status: optional "incomplete" or "completed" or null`
334
335 The supplied message’s status. Live uses its text as history and does not resume an incomplete message.
336
337 - `"incomplete"`
338
339 - `"completed"`
340
341 - `type: optional "message"`
342
343 The history item type. Always `message`.
344
345 - `"message"`
346
347 - `User object { content, role, id, 2 more }`
348
349 A user message included in the initial text history of a Live session.
350
351 - `content: array of object { text, type }`
352
353 The message content. Supply exactly one text part for the initial Live conversation history.
354
355 - `text: string`
356
357 The message text to include in the Live session’s initial conversation history.
358
359 - `type: optional "input_text"`
360
361 The text content type. Always `input_text`.
362
363 - `"input_text"`
364
365 - `role: "user"`
366
367 The author of this history message. Always `user`.
368
369 - `"user"`
370
371 - `id: optional string or null`
372
373 An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
374
375 - `status: optional "incomplete" or "completed" or null`
376
377 The supplied message’s status. Live uses its text as history and does not resume an incomplete message.
378
379 - `"incomplete"`
380
381 - `"completed"`
382
383 - `type: optional "message"`
384
385 The history item type. Always `message`.
386
387 - `"message"`
388
389 - `Assistant object { content, role, id, 2 more }`
390
391 An assistant message included in the initial text history of a Live session.
392
393 - `content: array of object { text, type } or object { text, type }`
394
395 The message content. Supply exactly one text part for the initial Live conversation history.
396
397 - `Text object { text, type }`
398
399 Assistant text supplied as conversation history when starting a Live session.
400
401 - `text: string`
402
403 The message text to include in the Live session’s initial conversation history.
404
405 - `type: optional "text"`
406
407 The text content type. Always `text`.
408
409 - `"text"`
410
411 - `OutputText object { text, type }`
412
413 Assistant output text supplied as conversation history when starting a Live session.
414
415 - `text: string`
416
417 The message text to include in the Live session’s initial conversation history.
418
419 - `type: "output_text"`
420
421 The text content type. Always `output_text`.
422
423 - `"output_text"`
424
425 - `role: "assistant"`
426
427 The author of this history message. Always `assistant`.
428
429 - `"assistant"`
430
431 - `id: optional string or null`
432
433 An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
434
435 - `status: optional "incomplete" or "completed" or null`
436
437 The supplied message’s status. Live uses its text as history and does not resume an incomplete message.
438
439 - `"incomplete"`
440
441 - `"completed"`
442
443 - `type: optional "message"`
444
445 The history item type. Always `message`.
446
447 - `"message"`
448
449 - `instructions: optional string or null`
450
451 Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup.
452
453 - `store: optional boolean`
454
455 Whether to store the session for later forking and recording download. Defaults to false for new sessions.
456
457- `transport: object { sdp, type }`
458
459 WebRTC transport with the browser's SDP offer.
460
461 - `sdp: string`
462
463 Session Description Protocol message for the WebRTC connection.
464
465 - `type: "webrtc"`
466
467 The transport used for the Live session. Always `webrtc`.
468
469 - `"webrtc"`
470
471### Returns
472
473- `session: object { id }`
474
475 The newly created Live session. Use its ID for session controls and sideband connections.
476
477 - `id: string`
478
479 Opaque session identifier. Preserve the returned value unchanged, including its prefix.
480
481- `transport: object { sdp, type }`
482
483 WebRTC transport with the SDP answer.
484
485 - `sdp: string`
486
487 Session Description Protocol message for the WebRTC connection.
488
489 - `type: "webrtc"`
490
491 The transport used for the Live session. Always `webrtc`.
492
493 - `"webrtc"`
494
495### Example
496
497```http
498curl https://api.openai.com/v1/live/sessions \
499 -H 'Content-Type: application/json' \
500 -H "Authorization: Bearer $OPENAI_API_KEY" \
501 -d '{
502 "session": {
503 "model": "gpt-live-1"
504 },
505 "transport": {
506 "sdp": "x",
507 "type": "webrtc"
508 }
509 }'
510```
511
512#### Response
513
514```json
515{
516 "session": {
517 "id": "live_123"
518 },
519 "transport": {
520 "type": "webrtc",
521 "sdp": "<SDP answer>"
522 }
523}
524```
525
526### Example
527
528```http
529curl https://api.openai.com/v1/live/sessions \
530 -H "Authorization: Bearer $OPENAI_API_KEY" \
531 -H "Content-Type: application/json" \
532 -d '{"session":{"model":"gpt-live-1","instructions":"Be concise. Ask for clarification when needed."},"transport":{"type":"webrtc","sdp":"<SDP offer>"}}'
533```