Skip to content

create.md

Latest commit

 

History

History
1440 lines (759 loc) · 41.3 KB

create.md

File metadata and controls

1440 lines (759 loc) · 41.3 KB
Raw

Create session

post /live/sessions

Create a Live WebRTC session or place an outbound SIP call. Start with the Live prompting guide for session configuration and Telephony and SIP 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. 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

Content type: application/json

  • 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

        minLength: 1

      • "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

              minLength: 1, maxLength: 128

    • 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

            maxItems: 256

        • 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

            maxItems: 256

            • type: string

              The outer Live server event type. Use 'response.event' for Responses events.

              minLength: 1, maxLength: 256

            • response_event: optional string

              The nested Responses event type. Required when type is 'response.event'; forbidden for other event types.

              minLength: 1, maxLength: 256

    • 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" (default: "client")

          The delegation owner. Always client for tasks handled by your application.

          • "client"

        • acknowledgement_delay_ms: optional integer

          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.

          minimum: 0, maximum: 800

      • 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.

          • max_output_tokens: optional integer or null

            Maximum number of output tokens for each delegated response.

            minimum: 16

          • 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" (default: "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" (default: "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" (default: "file_search")

                The tool to call. Always file_search.

                • "file_search"

            • WebSearch object { type }

              • type: "web_search" (default: "web_search")

                The tool to call. Always web_search.

                • "web_search"

            • WebSearchPreview object { type }

              • type: "web_search_preview" (default: "web_search_preview")

                The tool to call. Always web_search_preview.

                • "web_search_preview"

            • ImageGeneration object { type }

              • type: "image_generation" (default: "image_generation")

                The tool to call. Always image_generation.

                • "image_generation"

            • Computer object { type }

              • type: "computer" (default: "computer")

                The tool to call. Always computer.

                • "computer"

            • CodeInterpreter object { type }

              • type: "code_interpreter" (default: "code_interpreter")

                The tool to call. Always code_interpreter.

                • "code_interpreter"

            • ProgrammaticToolCalling object { type }

              • type: "programmatic_tool_calling" (default: "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" (default: "shell")

                The tool to call. Always shell.

                • "shell"

            • Custom object { name, type }

              • name: string

                The name of the custom tool to call.

              • type: "custom" (default: "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" (default: "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.

                minItems: 1, maxItems: 128

                • Function object { name, type }

                  • name: string

                    The name of the function tool to call.

                  • type: "function" (default: "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" (default: "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" (default: "file_search")

                    The tool to call. Always file_search.

                    • "file_search"

                • WebSearch object { type }

                  • type: "web_search" (default: "web_search")

                    The tool to call. Always web_search.

                    • "web_search"

                • WebSearchPreview object { type }

                  • type: "web_search_preview" (default: "web_search_preview")

                    The tool to call. Always web_search_preview.

                    • "web_search_preview"

                • ImageGeneration object { type }

                  • type: "image_generation" (default: "image_generation")

                    The tool to call. Always image_generation.

                    • "image_generation"

                • Computer object { type }

                  • type: "computer" (default: "computer")

                    The tool to call. Always computer.

                    • "computer"

                • CodeInterpreter object { type }

                  • type: "code_interpreter" (default: "code_interpreter")

                    The tool to call. Always code_interpreter.

                    • "code_interpreter"

                • ProgrammaticToolCalling object { type }

                  • type: "programmatic_tool_calling" (default: "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" (default: "shell")

                    The tool to call. Always shell.

                    • "shell"

                • Custom object { name, type }

                  • name: string

                    The name of the custom tool to call.

                  • type: "custom" (default: "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" (default: "apply_patch")

                    The tool to call. Always apply_patch.

                    • "apply_patch"

              • type: "allowed_tools" (default: "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" (default: "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" (default: "web_search")

                The tool type. Always web_search.

                • "web_search"

            • FileSearch object { type }

              • type: "file_search" (default: "file_search")

                • "file_search"

            • CodeInterpreter object { type }

              • type: "code_interpreter" (default: "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" (default: "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" (default: "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.

                    maxItems: 50

                  • 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" (default: "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.

                      minItems: 1

                    • type: "allowlist" (default: "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.

                    maxItems: 200

                    • SkillReference object { skill_id, type, version }

                    • skill_id: string

                      The ID of the referenced skill.

                      minLength: 1, maxLength: 64

                    • type: "skill_reference" (default: "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.

                      minLength: 1, maxLength: 70254592

                    • media_type: "application/zip" (default: "application/zip")

                      The media type of the inline skill payload. Must be application/zip.

                    • "application/zip"

                    • type: "base64" (default: "base64")

                      The type of the inline skill source. Must be base64.

                    • "base64"

                    • type: "inline" (default: "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" (default: "container_reference")

                    References a container created with the /v1/containers endpoint

                    • "container_reference"

                • Local object { type, skills }

                  • type: "local" (default: "local")

                    Use a local computer environment.

                    • "local"

                  • skills: optional array of object { description, name, path } or null

                    An optional list of skills.

                    maxItems: 200

                    • 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" (default: "image_generation")

                • "image_generation"

            • Mcp object { type }

              • type: "mcp" (default: "mcp")

                • "mcp"

            • Custom object { type }

              • type: "custom" (default: "custom")

                • "custom"

            • Namespace object { type }

              • type: "namespace" (default: "namespace")

                • "namespace"

            • ToolSearch object { type }

              • type: "tool_search" (default: "tool_search")

                • "tool_search"

            • ProgrammaticToolCalling object { type }

              • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

                • "programmatic_tool_calling"

            • Computer object { type }

              • type: "computer" (default: "computer")

                • "computer"

            • ApplyPatch object { type }

              • type: "apply_patch" (default: "apply_patch")

                • "apply_patch"

        • type: "responses" (default: "responses")

          The delegation owner. Always responses for tasks handled by the Responses API.

          • "responses"

        • acknowledgement_delay_ms: optional integer

          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.

          minimum: 0, maximum: 800

      • Decisions object { decisions, type, acknowledgement_delay_ms }

        • decisions: DecisionsDelegationConfig

          • model: string

            minLength: 1

          • questions: array of DecisionQuestion

            Native Decision API questions evaluated together, in order.

            minItems: 1, maxItems: 64

            • Choice object { choices, instructions, type, name }

              • choices: array of DecisionChoiceOption

                minItems: 2, maxItems: 255

                • value: string or boolean

                  • string

                  • boolean

                • description: optional string

              • instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

                • string

                • array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

                  minItems: 1

                  • DecisionInputText object { text, type }

                    • text: string

                      The text input to the model.

                      maxLength: 10485760

                    • type: "input_text" (default: "input_text")

                    • "input_text"

                  • InputImage object { image_url, type, detail }

                    • image_url: string

                      A base64-encoded image data URL or a publicly accessible HTTP(S) image URL.

                      pattern: ^(data:|https?://), maxLength: 20971520

                    • type: "input_image" (default: "input_image")

                    • "input_image"

                    • detail: optional "low" or "high" or "auto" or "original" or null

                      The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

                    • "low"

                    • "high"

                    • "auto"

                    • "original"

                  • InputJSON object { data, type }

                    • data: map[unknown] or array of map[unknown]

                    • LiveDecisionJSONObject = map[unknown]

                    • array of map[unknown]

                    • type: "input_json" (default: "input_json")

                    • "input_json"

              • type: "choice" (default: "choice")

                • "choice"

              • name: optional string

            • Predicate object { instructions, type, name }

              • instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

                • string

                • array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

                  minItems: 1

                  • DecisionInputText object { text, type }

                  • InputImage object { image_url, type, detail }

                    • image_url: string

                      A base64-encoded image data URL or a publicly accessible HTTP(S) image URL.

                      pattern: ^(data:|https?://), maxLength: 20971520

                    • type: "input_image" (default: "input_image")

                    • "input_image"

                    • detail: optional "low" or "high" or "auto" or "original" or null

                      The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

                    • "low"

                    • "high"

                    • "auto"

                    • "original"

                  • InputJSON object { data, type }

                    • data: map[unknown] or array of map[unknown]

                    • LiveDecisionJSONObject = map[unknown]

                    • array of map[unknown]

                    • type: "input_json" (default: "input_json")

                    • "input_json"

              • type: "predicate" (default: "predicate")

                • "predicate"

              • name: optional string

            • Score object { instructions, levels, type, name }

              • instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

                • string

                • array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

                  minItems: 1

                  • DecisionInputText object { text, type }

                  • InputImage object { image_url, type, detail }

                    • image_url: string

                      A base64-encoded image data URL or a publicly accessible HTTP(S) image URL.

                      pattern: ^(data:|https?://), maxLength: 20971520

                    • type: "input_image" (default: "input_image")

                    • "input_image"

                    • detail: optional "low" or "high" or "auto" or "original" or null

                      The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

                    • "low"

                    • "high"

                    • "auto"

                    • "original"

                  • InputJSON object { data, type }

                    • data: map[unknown] or array of map[unknown]

                    • LiveDecisionJSONObject = map[unknown]

                    • array of map[unknown]

                    • type: "input_json" (default: "input_json")

                    • "input_json"

              • levels: array of object { label, description }

                minItems: 2, maxItems: 10

                • label: string

                • description: optional string

              • type: "score" (default: "score")

                • "score"

              • name: optional string

        • type: "decisions" (default: "decisions")

          • "decisions"

        • acknowledgement_delay_ms: optional integer

          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.

          minimum: 0, maximum: 800

    • 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).

      maxItems: 128

      • 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.

          minItems: 1, maxItems: 1

          • text: string

            The message text to include in the Live session’s initial conversation history.

          • type: optional "input_text" (default: "input_text")

            The text content type. Always input_text.

            • "input_text"

        • role: "developer" (default: "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" (default: "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.

          minItems: 1, maxItems: 1

          • text: string

            The message text to include in the Live session’s initial conversation history.

          • type: optional "input_text" (default: "input_text")

            The text content type. Always input_text.

            • "input_text"

        • role: "user" (default: "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" (default: "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.

          minItems: 1, maxItems: 1

          • 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" (default: "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" (default: "output_text")

              The text content type. Always output_text.

              • "output_text"

        • role: "assistant" (default: "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" (default: "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; put business rules and tool workflows in a separate 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.

      maxItems: 2

      • decisions: object { questions }

        Questions evaluated using the current transcript and the session's shared Decision items.

        • questions: array of DecisionQuestion

          Native Decision API questions evaluated together, in order.

          minItems: 1, maxItems: 64

          • Choice object { choices, instructions, type, name }

          • Predicate object { instructions, type, name }

          • Score object { instructions, levels, type, name }

      • event_type: "session.input_transcript.delta" or "session.output_transcript.delta"

        • "session.input_transcript.delta"

        • "session.output_transcript.delta"

      • type: "decisions" (default: "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.

        minLength: 1

      • 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. The trunk must support TLS signaling, Opus audio, and SDES-SRTP media. See Telephony and SIP.

      • destination: string

        Phone number to call in E.164 format. SIP URI destinations are not supported.

        pattern: ^\+[1-9][0-9]{1,14}$

      • 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.

            minLength: 1

          • 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.

            minLength: 1

        • caller_number: string

          Caller phone number in E.164 format to use in the SIP From header.

          pattern: ^\+[1-9][0-9]{1,14}$

        • 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.

        minLength: 1

      • 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

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"
          }
        }'

201 — WebRTC session created (201 Created)

{
  "session": {
    "id": "live_123"
  },
  "transport": {
    "type": "webrtc",
    "sdp": "<SDP answer>"
  }
}

201 — Outbound SIP session initialized (201 Created)

{
  "session": {
    "id": "live_123"
  },
  "transport": {
    "type": "sip"
  }
}

Create a WebRTC session

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":"<SDP offer>"}}'

Response example

{"session":{"id":"live_123"},"transport":{"type":"webrtc","sdp":"<SDP answer>"}}

Place an outbound SIP call

# 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 example

{"session":{"id":"live_123"},"transport":{"type":"sip"}}