SpyBara
Go Premium

resources/live/methods/create/index.md 2026-09-09 16:02 UTC to 2026-09-10 18:01 UTC

This page contains 533 additions and 0 deletions.

2026
Thu 10 18:01 Fri 18 22:59

Create session

post /live/sessions

Create a Live WebRTC session. Start with the Live prompting guide.

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

            • "cedar"

            • "cinder"

            • "coral"

            • "delta"

            • "echo"

            • "gleam"

            • "marin"

            • "meridian"

            • "quartz"

            • "ripple"

            • "sage"

            • "shimmer"

            • "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 object { responses, type } or null

      Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.

      • ClientDelegation object { type }

        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"

      • Responses object { responses, type }

        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 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 object { name, type } or object { name, server_label, type }

            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"

            • LiveFunctionToolChoiceParam object { name, type }

              • name: string

              • type: "function"

                • "function"

            • LiveMCPToolChoiceParam object { name, server_label, type }

              • name: string

              • server_label: string

              • type: "mcp"

                • "mcp"

          • tools: optional array of FunctionTool or object { type }

            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"

        • type: "responses"

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

          • "responses"

    • 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 8,192 rendered tokens in total.

      • 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 object { text, type } or object { 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; 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.

  • transport: object { sdp, type }

    WebRTC transport with the browser's SDP offer.

    • sdp: string

      Session Description Protocol message for the WebRTC connection.

    • type: "webrtc"

      The transport used for the Live session. Always webrtc.

      • "webrtc"

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: object { sdp, type }

    WebRTC transport with the SDP answer.

    • sdp: string

      Session Description Protocol message for the WebRTC connection.

    • type: "webrtc"

      The transport used for the Live session. Always webrtc.

      • "webrtc"

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

Response

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

Example

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