## Create session **post** `/live/sessions` Create a Live WebRTC session or place an outbound SIP call. Start with the [Live prompting guide](/api/docs/guides/live-prompting) for session configuration and [Telephony and SIP](/api/docs/guides/voice-sip?api=live#place-an-outbound-call) for trunk setup and call monitoring. Set transport.type to `webrtc` and supply an SDP offer, or set it to `sip` and supply an E.164 destination and trunk credentials. Outbound SIP calling must be enabled for your organization. Ringing is limited to 3 minutes and connected calls to 2 hours; these limits are not configurable in the request. Returns `201 Created` after session initialization. WebRTC responses include an SDP answer. SIP responses do not wait for the callee to answer. Attach a sideband connection using session.id to monitor SIP call progress. Each SIP request creates a new call. If a request times out or the connection fails, retry with caution: the original request may have succeeded, and a retry can place another call. ### Body Parameters - `session: MediaSessionConfig` Startup configuration for the Live session. - `model: string or "gpt-live-1"` The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter. - `string` - `"gpt-live-1"` The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter. - `"gpt-live-1"` - `audio: optional object { output }` Startup audio configuration. WebRTC and SIP negotiate their audio format on the media transport. - `output: optional object { voice }` Settings for speech generated by the Live model. Choose the voice before starting the session. - `voice: optional string or "alloy" or "ash" or "ballad" or 28 more or CustomVoice` 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. - `string` - `"alloy" or "ash" or "ballad" or 28 more` 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. - `"alloy"` - `"ash"` - `"ballad"` - `"beacon"` - `"bossa"` - `"brise"` - `"cedar"` - `"cinder"` - `"coral"` - `"delta"` - `"echo"` - `"flitz"` - `"gleam"` - `"harema"` - `"juni"` - `"marin"` - `"meridian"` - `"nira"` - `"noeul"` - `"nuri"` - `"quartz"` - `"ripple"` - `"sage"` - `"shida"` - `"shimmer"` - `"sillage"` - `"stone"` - `"tempo"` - `"verse"` - `"vesper"` - `"willow"` - `CustomVoice object { id }` - `id: string` - `client: optional ClientConfig` Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - `data_channel: DataChannelConfig` Client and server event permissions for the WebRTC frontend data channel. - `allowed_client_events: optional "all" or array of string` 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. - `"all"` - `"all"` - `array of string` - `allowed_server_events: optional "all" or array of ServerEventSelector` 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. - `"all"` - `"all"` - `array of ServerEventSelector` - `type: string` The outer Live server event type. Use 'response.event' for Responses events. - `response_event: optional string` The nested Responses event type. Required when type is 'response.event'; forbidden for other event types. - `delegation: optional ClientDelegation or Responses { responses, type, acknowledgement_delay_ms } or Decisions { decisions, type, acknowledgement_delay_ms } or null` Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` or `decisions` to delegate to the corresponding API. - `ClientDelegation object { type, acknowledgement_delay_ms }` Delegate tasks to your application. The Live session emits delegation events that your backend handles. - `type: "client"` The delegation owner. Always `client` for tasks handled by your application. - `"client"` - `acknowledgement_delay_ms: optional number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. - `Responses object { responses, type, acknowledgement_delay_ms }` Delegate tasks to a Responses model managed by the Live session. - `responses: ResponsesDelegationConfig` Backend model, prompt, and tools used when the Live session delegates a task to Responses. - `model: string` The model used for server-owned Responses delegations. - `instructions: optional string or null` Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). - `max_output_tokens: optional number or null` Maximum number of output tokens for each delegated response. - `parallel_tool_calls: optional boolean or null` Whether the delegated Responses model may request multiple tool calls in a single response. - `reasoning: optional object { effort, summary } or null` Reasoning settings passed to each delegated Responses request. - `effort: optional "none" or "minimal" or "low" or 3 more or null` How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `summary: optional "concise" or "detailed" or "auto" or null` The reasoning summary to request from the delegated Responses model, when supported. - `"concise"` - `"detailed"` - `"auto"` - `service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null` Service tier for delegated Responses requests. - `"auto"` - `"default"` - `"fast_tier_temp_pilot"` - `"flex"` - `"priority"` - `"ultrafast"` - `text: optional object { verbosity } or null` Text generation settings passed to each delegated Responses request. - `verbosity: optional "low" or "medium" or "high" or null` The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery. - `"low"` - `"medium"` - `"high"` - `tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more` Controls which tool the Responses backend uses when handling a task delegated by the Live model. - `LiveToolChoiceEnum = "auto" or "none" or "required"` - `"auto"` - `"none"` - `"required"` - `Function object { name, type }` - `name: string` The name of the function tool to call. - `type: "function"` The tool to call. Always `function`. - `"function"` - `Mcp object { server_label, type, name }` - `server_label: string` The label of the MCP server to call. - `type: "mcp"` The tool to call. Always `mcp`. - `"mcp"` - `name: optional string or null` The name of the MCP tool to call. If omitted, the server may choose a default. - `FileSearch object { type }` - `type: "file_search"` The tool to call. Always `file_search`. - `"file_search"` - `WebSearch object { type }` - `type: "web_search"` The tool to call. Always `web_search`. - `"web_search"` - `WebSearchPreview object { type }` - `type: "web_search_preview"` The tool to call. Always `web_search_preview`. - `"web_search_preview"` - `ImageGeneration object { type }` - `type: "image_generation"` The tool to call. Always `image_generation`. - `"image_generation"` - `Computer object { type }` - `type: "computer"` The tool to call. Always `computer`. - `"computer"` - `CodeInterpreter object { type }` - `type: "code_interpreter"` The tool to call. Always `code_interpreter`. - `"code_interpreter"` - `ProgrammaticToolCalling object { type }` - `type: "programmatic_tool_calling"` The tool to call. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Shell object { type }` Forces the model to call the shell tool when a tool call is required. - `type: "shell"` The tool to call. Always `shell`. - `"shell"` - `Custom object { name, type }` - `name: string` The name of the custom tool to call. - `type: "custom"` The tool to call. Always `custom`. - `"custom"` - `ApplyPatch object { type }` Forces the model to call the apply_patch tool when executing a tool call. - `type: "apply_patch"` The tool to call. Always `apply_patch`. - `"apply_patch"` - `LiveAllowedToolsChoiceParam object { tools, type, mode }` - `tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more` The tools that the delegated Responses model may call. - `Function object { name, type }` - `name: string` The name of the function tool to call. - `type: "function"` The tool to call. Always `function`. - `"function"` - `Mcp object { server_label, type, name }` - `server_label: string` The label of the MCP server to call. - `type: "mcp"` The tool to call. Always `mcp`. - `"mcp"` - `name: optional string or null` The name of the MCP tool to call. If omitted, the server may choose a default. - `FileSearch object { type }` - `type: "file_search"` The tool to call. Always `file_search`. - `"file_search"` - `WebSearch object { type }` - `type: "web_search"` The tool to call. Always `web_search`. - `"web_search"` - `WebSearchPreview object { type }` - `type: "web_search_preview"` The tool to call. Always `web_search_preview`. - `"web_search_preview"` - `ImageGeneration object { type }` - `type: "image_generation"` The tool to call. Always `image_generation`. - `"image_generation"` - `Computer object { type }` - `type: "computer"` The tool to call. Always `computer`. - `"computer"` - `CodeInterpreter object { type }` - `type: "code_interpreter"` The tool to call. Always `code_interpreter`. - `"code_interpreter"` - `ProgrammaticToolCalling object { type }` - `type: "programmatic_tool_calling"` The tool to call. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Shell object { type }` Forces the model to call the shell tool when a tool call is required. - `type: "shell"` The tool to call. Always `shell`. - `"shell"` - `Custom object { name, type }` - `name: string` The name of the custom tool to call. - `type: "custom"` The tool to call. Always `custom`. - `"custom"` - `ApplyPatch object { type }` Forces the model to call the apply_patch tool when executing a tool call. - `type: "apply_patch"` The tool to call. Always `apply_patch`. - `"apply_patch"` - `type: "allowed_tools"` The tool choice type. Always `allowed_tools`. - `"allowed_tools"` - `mode: optional "none" or "auto" or "required" or null` How to select a tool from the allowed set. - `"none"` - `"auto"` - `"required"` - `tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more` Tools available to the Responses backend while it handles tasks delegated by the Live model. - `FunctionTool object { name, type, description, 2 more }` A function tool available to the Responses backend when the Live model delegates a task. - `name: string` The name the delegated Responses model uses when calling this function. - `type: "function"` The tool type. Always `function`. - `"function"` - `description: optional string or null` What the function does and when the delegated Responses model should call it. - `parameters: optional map[unknown] or null` A JSON Schema object describing the arguments accepted by the function. - `strict: optional boolean or null` Whether the delegated Responses model must follow the function’s parameter schema exactly. - `WebSearch object { type }` A web search tool available to the Live session’s Responses backend. - `type: "web_search"` The tool type. Always `web_search`. - `"web_search"` - `FileSearch object { type }` - `type: "file_search"` - `"file_search"` - `CodeInterpreter object { type }` - `type: "code_interpreter"` - `"code_interpreter"` - `Shell object { type, environment }` A Responses shell tool. Use a hosted container or return local shell results with response.item.create. Domain secrets are not supported. - `type: "shell"` - `"shell"` - `environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - `type: "container_auto"` Automatically creates a container for this request - `"container_auto"` - `file_ids: optional array of string or null` An optional list of uploaded files to make available to your code. - `memory_limit: optional "1g" or "4g" or "16g" or "64g" or null` The memory limit for the container. - `"1g"` - `"4g"` - `"16g"` - `"64g"` - `network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null` Network access policy for the container. - `Disabled object { type }` - `type: "disabled"` Disable outbound network access. Always `disabled`. - `"disabled"` - `Allowlist object { allowed_domains, type }` - `allowed_domains: array of string` A list of allowed domains when type is `allowlist`. - `type: "allowlist"` Allow outbound network access only to specified domains. Always `allowlist`. - `"allowlist"` - `skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null` An optional list of skills referenced by id or inline data. - `SkillReference object { skill_id, type, version }` - `skill_id: string` The ID of the referenced skill. - `type: "skill_reference"` References a skill created with the /v1/skills endpoint. - `"skill_reference"` - `version: optional string or null` Optional skill version. Use a positive integer or 'latest'. Omit for default. - `Inline object { description, name, source, type }` - `description: string` The description of the skill. - `name: string` The name of the skill. - `source: object { data, media_type, type }` Inline skill payload - `data: string` Base64-encoded skill zip bundle. - `media_type: "application/zip"` The media type of the inline skill payload. Must be `application/zip`. - `"application/zip"` - `type: "base64"` The type of the inline skill source. Must be `base64`. - `"base64"` - `type: "inline"` Defines an inline skill for this request. - `"inline"` - `ContainerReference object { container_id, type }` - `container_id: string` The ID of the referenced container. - `type: "container_reference"` References a container created with the /v1/containers endpoint - `"container_reference"` - `Local object { type, skills }` - `type: "local"` Use a local computer environment. - `"local"` - `skills: optional array of object { description, name, path } or null` An optional list of skills. - `description: string` The description of the skill. - `name: string` The name of the skill. - `path: string` The path to the directory containing the skill. - `ImageGeneration object { type }` - `type: "image_generation"` - `"image_generation"` - `Mcp object { type }` - `type: "mcp"` - `"mcp"` - `Custom object { type }` - `type: "custom"` - `"custom"` - `Namespace object { type }` - `type: "namespace"` - `"namespace"` - `ToolSearch object { type }` - `type: "tool_search"` - `"tool_search"` - `ProgrammaticToolCalling object { type }` - `type: "programmatic_tool_calling"` - `"programmatic_tool_calling"` - `Computer object { type }` - `type: "computer"` - `"computer"` - `ApplyPatch object { type }` - `type: "apply_patch"` - `"apply_patch"` - `type: "responses"` The delegation owner. Always `responses` for tasks handled by the Responses API. - `"responses"` - `acknowledgement_delay_ms: optional number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. - `Decisions object { decisions, type, acknowledgement_delay_ms }` - `decisions: DecisionsDelegationConfig` - `model: string` - `questions: array of Choice { choices, instructions, type, name } or Predicate { instructions, type, name } or Score { instructions, levels, type, name }` Native Decision API questions evaluated together, in order. - `Choice object { choices, instructions, type, name }` - `choices: array of object { value, description }` - `value: string or boolean` - `string` - `boolean` - `description: optional string` - `instructions: string` - `type: "choice"` - `"choice"` - `name: optional string` - `Predicate object { instructions, type, name }` - `instructions: string` - `type: "predicate"` - `"predicate"` - `name: optional string` - `Score object { instructions, levels, type, name }` - `instructions: string` - `levels: array of object { label, description }` - `label: string` - `description: optional string` - `type: "score"` - `"score"` - `name: optional string` - `type: "decisions"` - `"decisions"` - `acknowledgement_delay_ms: optional number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400. Updates apply to subsequent delegations. - `input: optional array of InitialItem` Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and a configured rendered-token limit (8,192 by default). - `Developer object { content, role, id, 2 more }` A developer message included in the initial text history of a Live session. - `content: array of object { text, type }` The message content. Supply exactly one text part for the initial Live conversation history. - `text: string` The message text to include in the Live session’s initial conversation history. - `type: optional "input_text"` The text content type. Always `input_text`. - `"input_text"` - `role: "developer"` The author of this history message. Always `developer`. - `"developer"` - `id: optional string or null` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status: optional "incomplete" or "completed" or null` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type: optional "message"` The history item type. Always `message`. - `"message"` - `User object { content, role, id, 2 more }` A user message included in the initial text history of a Live session. - `content: array of object { text, type }` The message content. Supply exactly one text part for the initial Live conversation history. - `text: string` The message text to include in the Live session’s initial conversation history. - `type: optional "input_text"` The text content type. Always `input_text`. - `"input_text"` - `role: "user"` The author of this history message. Always `user`. - `"user"` - `id: optional string or null` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status: optional "incomplete" or "completed" or null` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type: optional "message"` The history item type. Always `message`. - `"message"` - `Assistant object { content, role, id, 2 more }` An assistant message included in the initial text history of a Live session. - `content: array of Text { text, type } or OutputText { text, type }` The message content. Supply exactly one text part for the initial Live conversation history. - `Text object { text, type }` Assistant text supplied as conversation history when starting a Live session. - `text: string` The message text to include in the Live session’s initial conversation history. - `type: optional "text"` The text content type. Always `text`. - `"text"` - `OutputText object { text, type }` Assistant output text supplied as conversation history when starting a Live session. - `text: string` The message text to include in the Live session’s initial conversation history. - `type: "output_text"` The text content type. Always `output_text`. - `"output_text"` - `role: "assistant"` The author of this history message. Always `assistant`. - `"assistant"` - `id: optional string or null` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status: optional "incomplete" or "completed" or null` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type: optional "message"` The history item type. Always `message`. - `"message"` - `instructions: optional string or null` 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. - `store: optional boolean` Whether to store the session for later forking and recording download. Defaults to false for new sessions. - `triggers: optional array of DecisionTrigger` At most one Decisions trigger per transcript event type. Triggers run independently of delegation. On update, omit triggers to keep the current configuration, send a list to replace it, or send an empty list to disable triggers. - `decisions: object { questions }` Questions evaluated using the current transcript and the session's shared Decision items. - `questions: array of Choice { choices, instructions, type, name } or Predicate { instructions, type, name } or Score { instructions, levels, type, name }` Native Decision API questions evaluated together, in order. - `Choice object { choices, instructions, type, name }` - `choices: array of object { value, description }` - `value: string or boolean` - `string` - `boolean` - `description: optional string` - `instructions: string` - `type: "choice"` - `"choice"` - `name: optional string` - `Predicate object { instructions, type, name }` - `instructions: string` - `type: "predicate"` - `"predicate"` - `name: optional string` - `Score object { instructions, levels, type, name }` - `instructions: string` - `levels: array of object { label, description }` - `label: string` - `description: optional string` - `type: "score"` - `"score"` - `name: optional string` - `event_type: "session.input_transcript.delta" or "session.output_transcript.delta"` - `"session.input_transcript.delta"` - `"session.output_transcript.delta"` - `type: "decisions"` - `"decisions"` - `transport: Webrtc { sdp, type } or Sip { destination, trunk, type }` WebRTC transport with an SDP offer, or SIP transport with a destination and per-call trunk credentials. - `Webrtc object { sdp, type }` WebRTC transport carrying the offer SDP in a creation request or answer SDP in its response. - `sdp: string` Session Description Protocol message for the WebRTC connection. - `type: "webrtc"` The transport used for the Live session. Always `webrtc`. - `"webrtc"` - `Sip object { destination, trunk, type }` Place an outbound SIP call using your provider's trunk. Outbound SIP calling must be enabled for your organization. The trunk must support TLS signaling, Opus audio, and SDES-SRTP media. See [Telephony and SIP](/api/docs/guides/voice-sip?api=live#place-an-outbound-call). - `destination: string` Phone number to call in E.164 format. SIP URI destinations are not supported. - `trunk: object { auth, caller_number, provider_url }` SIP trunk configuration supplied for this call. Keep trunk credentials on your server. The creation response does not return this configuration. - `auth: object { password, type, username }` Credentials for SIP Digest authentication with your trunk provider. - `password: string` Provider password. Must be at most 4096 bytes and contain no CR, LF, or NUL. - `type: "digest"` Use `digest` for SIP Digest authentication. Handles 401 and 407 challenges. - `"digest"` - `username: string` Provider username. Must contain a non-whitespace character, be at most 256 bytes, and contain no CR, LF, or NUL. - `caller_number: string` Caller phone number in E.164 format to use in the SIP From header. - `provider_url: string` Provider endpoint in the form `sips:host[:port][;transport=tcp]`. The default port is 5061. IPv6 addresses must be bracketed. TLS signaling is required; plaintext SIP is not supported. Do not include userinfo, a path, URI headers, or other URI parameters. Local hostnames and literal private, loopback, link-local, unspecified, multicast, and broadcast IP addresses are rejected. - `type: "sip"` The transport used for the Live session. Always `sip`. - `"sip"` ### Returns - `session: object { id }` The newly created Live session. Use its ID for session controls and sideband connections. - `id: string` Opaque session identifier. Preserve the returned value unchanged, including its prefix. - `transport: Webrtc { sdp, type } or Sip { type }` WebRTC transport with an SDP answer, or SIP transport without SDP or trunk credentials. For SIP, attach a sideband using session.id to receive transport.ringing, transport.answered, and transport.failed notifications. - `Webrtc object { sdp, type }` WebRTC transport carrying the offer SDP in a creation request or answer SDP in its response. - `sdp: string` Session Description Protocol message for the WebRTC connection. - `type: "webrtc"` The transport used for the Live session. Always `webrtc`. - `"webrtc"` - `Sip object { type }` The SIP transport. Trunk credentials and SDP are not returned. - `type: "sip"` The transport used for the Live session. Always `sip`. - `"sip"` ### Example ```http curl https://api.openai.com/v1/live/sessions \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "session": { "model": "gpt-live-1" }, "transport": { "sdp": "x", "type": "webrtc" } }' ``` #### Response ```json { "session": { "id": "live_123" }, "transport": { "type": "webrtc", "sdp": "" } } ``` ### Create a WebRTC session ```http curl https://api.openai.com/v1/live/sessions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"session":{"model":"gpt-live-1","instructions":"Be concise. Ask for clarification when needed."},"transport":{"type":"webrtc","sdp":""}}' ``` #### Response ```json {"session":{"id":"live_123"},"transport":{"type":"webrtc","sdp":""}} ``` ### Place an outbound SIP call ```http # Export SIP_USERNAME and SIP_PASSWORD in your environment first. jq -n '{ "session": { "model": "gpt-live-1", "instructions": "Help the user schedule an appointment.", "audio": { "output": { "voice": "marin" } }, "delegation": { "type": "client" } }, "transport": { "type": "sip", "destination": "+14155550123", "trunk": { "provider_url": "sips:sip.example.com:5061", "auth": { "type": "digest", "username": env.SIP_USERNAME, "password": env.SIP_PASSWORD }, "caller_number": "+14155550100" } } }' | curl https://api.openai.com/v1/live/sessions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- ``` #### Response ```json {"session":{"id":"live_123"},"transport":{"type":"sip"}} ```