LiveCreateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/openai/main/json-schema/openai-live-create-request-schema.json",
  "title": "LiveCreateRequest",
  "description": "Create a Live WebRTC session with JSON session configuration and an SDP offer. Follow the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) before choosing frontend and backend instructions. The request starts the session; do not send session.start on the data channel.",
  "x-generated": "2026-09-23",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openai-live-api-openapi.yml#/components/schemas/LiveCreateRequest",
  "type": "object",
  "properties": {
    "session": {
      "$ref": "#/$defs/LiveMediaSessionCreateParams",
      "description": "Startup configuration for the Live session."
    },
    "transport": {
      "$ref": "#/$defs/LiveWebRTCTransport",
      "description": "WebRTC transport with the browser's SDP offer."
    }
  },
  "required": [
    "session",
    "transport"
  ],
  "additionalProperties": false,
  "$defs": {
    "LiveAllowedServerEventParam": {
      "description": "A Live server event selector for the WebRTC frontend data channel.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The outer Live server event type. Use 'response.event' for Responses events.",
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "response_event": {
          "description": "The nested Responses event type. Required when type is 'response.event'; forbidden for other event types.",
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false,
      "x-oaiMeta": {}
    },
    "LiveClientConfigParam": {
      "description": "Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.",
      "type": "object",
      "properties": {
        "data_channel": {
          "description": "Client and server event permissions for the WebRTC frontend data channel.",
          "$ref": "#/$defs/LiveDataChannelConfigParam"
        }
      },
      "required": [
        "data_channel"
      ]
    },
    "LiveClientDelegationParam": {
      "description": "Delegate tasks to your application. The Live session emits delegation events that your backend handles.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The delegation owner. Always `client` for tasks handled by your application.",
          "default": "client",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "client"
          ]
        }
      },
      "required": [
        "type"
      ]
    },
    "LiveCustomVoiceParam": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "required": [
        "id"
      ]
    },
    "LiveDataChannelConfigParam": {
      "description": "Control which Live events an untrusted WebRTC frontend can send and receive over its data channel. These restrictions do not apply to trusted sideband connections.",
      "type": "object",
      "properties": {
        "allowed_client_events": {
          "description": "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.",
          "oneOf": [
            {
              "default": "all",
              "x-stainless-const": true,
              "type": "string",
              "enum": [
                "all"
              ]
            },
            {
              "type": "array",
              "items": {
                "description": "A Live client event type allowed on the frontend data channel, such as `session.input_audio.mute`.",
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "pattern": "^(?:error|info|[a-z][a-z0-9_-]*(?:\\.[a-z0-9_-]+)+)$"
              },
              "maxItems": 256
            }
          ]
        },
        "allowed_server_events": {
          "description": "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.",
          "oneOf": [
            {
              "default": "all",
              "x-stainless-const": true,
              "type": "string",
              "enum": [
                "all"
              ]
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/LiveAllowedServerEventParam"
              },
              "maxItems": 256
            }
          ]
        }
      },
      "required": []
    },
    "LiveDelegationReasoningInputParam": {
      "description": "Reasoning options for Responses requests made on behalf of the Live session.",
      "type": "object",
      "properties": {
        "effort": {
          "anyOf": [
            {
              "description": "How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model.",
              "$ref": "#/$defs/LiveReasoningEffort"
            },
            {
              "type": "null"
            }
          ]
        },
        "summary": {
          "anyOf": [
            {
              "description": "The reasoning summary to request from the delegated Responses model, when supported.",
              "$ref": "#/$defs/LiveReasoningSummary"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": []
    },
    "LiveDelegationTextInputParam": {
      "description": "Text generation options for the Live session’s Responses backend.",
      "type": "object",
      "properties": {
        "verbosity": {
          "anyOf": [
            {
              "description": "The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery.",
              "$ref": "#/$defs/LiveTextVerbosity"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": []
    },
    "LiveFunctionToolChoiceParam": {
      "type": "object",
      "properties": {
        "type": {
          "default": "function",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "function"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[a-zA-Z0-9_-]+$"
        }
      },
      "required": [
        "type",
        "name"
      ]
    },
    "LiveFunctionToolInputParam": {
      "description": "A function tool available to the Responses backend when the Live model delegates a task.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The tool type. Always `function`.",
          "default": "function",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "function"
          ]
        },
        "name": {
          "description": "The name the delegated Responses model uses when calling this function.",
          "type": "string"
        },
        "description": {
          "anyOf": [
            {
              "description": "What the function does and when the delegated Responses model should call it.",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "parameters": {
          "anyOf": [
            {
              "description": "A JSON Schema object describing the arguments accepted by the function.",
              "type": "object",
              "additionalProperties": {}
            },
            {
              "type": "null"
            }
          ]
        },
        "strict": {
          "anyOf": [
            {
              "description": "Whether the delegated Responses model must follow the function’s parameter schema exactly.",
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "type",
        "name"
      ]
    },
    "LiveInitialAssistantMessageItemParam": {
      "description": "An assistant message included in the initial text history of a Live session.",
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "description": "An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "type": {
          "description": "The history item type. Always `message`.",
          "default": "message",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "message"
          ]
        },
        "status": {
          "anyOf": [
            {
              "description": "The supplied message’s status. Live uses its text as history and does not resume an incomplete message.",
              "$ref": "#/$defs/LiveInitialMessageStatus"
            },
            {
              "type": "null"
            }
          ]
        },
        "role": {
          "description": "The author of this history message. Always `assistant`.",
          "default": "assistant",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "assistant"
          ]
        },
        "content": {
          "description": "The message content. Supply exactly one text part for the initial Live conversation history.",
          "type": "array",
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/LiveInitialTextContentPartParam"
              },
              {
                "$ref": "#/$defs/LiveInitialOutputTextContentPartParam"
              }
            ],
            "x-oai-default-discriminator-value": "text"
          },
          "minItems": 1,
          "maxItems": 1
        }
      },
      "required": [
        "role",
        "content"
      ]
    },
    "LiveInitialDeveloperMessageItemParam": {
      "description": "A developer message included in the initial text history of a Live session.",
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "description": "An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "type": {
          "description": "The history item type. Always `message`.",
          "default": "message",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "message"
          ]
        },
        "status": {
          "anyOf": [
            {
              "description": "The supplied message’s status. Live uses its text as history and does not resume an incomplete message.",
              "$ref": "#/$defs/LiveInitialMessageStatus"
            },
            {
              "type": "null"
            }
          ]
        },
        "role": {
          "description": "The author of this history message. Always `developer`.",
          "default": "developer",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "developer"
          ]
        },
        "content": {
          "description": "The message content. Supply exactly one text part for the initial Live conversation history.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/LiveInitialInputTextContentPartParam"
          },
          "minItems": 1,
          "maxItems": 1
        }
      },
      "required": [
        "role",
        "content"
      ]
    },
    "LiveInitialInputTextContentPartParam": {
      "description": "Text supplied in a developer or user message when starting a Live session.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The text content type. Always `input_text`.",
          "default": "input_text",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "input_text"
          ]
        },
        "text": {
          "description": "The message text to include in the Live session’s initial conversation history.",
          "type": "string"
        }
      },
      "required": [
        "text"
      ]
    },
    "LiveInitialItem": {
      "description": "A developer, user, or assistant message supplied as text history before the Live session starts.",
      "oneOf": [
        {
          "$ref": "#/$defs/LiveInitialDeveloperMessageItemParam"
        },
        {
          "$ref": "#/$defs/LiveInitialUserMessageItemParam"
        },
        {
          "$ref": "#/$defs/LiveInitialAssistantMessageItemParam"
        }
      ]
    },
    "LiveInitialMessageStatus": {
      "type": "string",
      "enum": [
        "incomplete",
        "completed"
      ]
    },
    "LiveInitialOutputTextContentPartParam": {
      "description": "Assistant output text supplied as conversation history when starting a Live session.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The text content type. Always `output_text`.",
          "default": "output_text",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "output_text"
          ]
        },
        "text": {
          "description": "The message text to include in the Live session’s initial conversation history.",
          "type": "string"
        }
      },
      "required": [
        "type",
        "text"
      ]
    },
    "LiveInitialSessionAudioOutputParam": {
      "description": "Settings for speech generated by the Live model. Choose the voice before starting the session.",
      "type": "object",
      "properties": {
        "voice": {
          "description": "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.",
          "oneOf": [
            {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "string",
                  "enum": [
                    "alloy",
                    "ash",
                    "ballad",
                    "beacon",
                    "bossa",
                    "cedar",
                    "cinder",
                    "coral",
                    "delta",
                    "echo",
                    "gleam",
                    "marin",
                    "meridian",
                    "quartz",
                    "ripple",
                    "sage",
                    "shimmer",
                    "stone",
                    "tempo",
                    "verse",
                    "vesper",
                    "willow"
                  ]
                }
              ]
            },
            {
              "$ref": "#/$defs/LiveCustomVoiceParam"
            }
          ]
        }
      },
      "required": []
    },
    "LiveInitialTextContentPartParam": {
      "description": "Assistant text supplied as conversation history when starting a Live session.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The text content type. Always `text`.",
          "default": "text",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "text"
          ]
        },
        "text": {
          "description": "The message text to include in the Live session’s initial conversation history.",
          "type": "string"
        }
      },
      "required": [
        "text"
      ]
    },
    "LiveInitialUserMessageItemParam": {
      "description": "A user message included in the initial text history of a Live session.",
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "description": "An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "type": {
          "description": "The history item type. Always `message`.",
          "default": "message",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "message"
          ]
        },
        "status": {
          "anyOf": [
            {
              "description": "The supplied message’s status. Live uses its text as history and does not resume an incomplete message.",
              "$ref": "#/$defs/LiveInitialMessageStatus"
            },
            {
              "type": "null"
            }
          ]
        },
        "role": {
          "description": "The author of this history message. Always `user`.",
          "default": "user",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "user"
          ]
        },
        "content": {
          "description": "The message content. Supply exactly one text part for the initial Live conversation history.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/LiveInitialInputTextContentPartParam"
          },
          "minItems": 1,
          "maxItems": 1
        }
      },
      "required": [
        "role",
        "content"
      ]
    },
    "LiveMCPToolChoiceParam": {
      "type": "object",
      "properties": {
        "type": {
          "default": "mcp",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "mcp"
          ]
        },
        "server_label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[a-zA-Z0-9_-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[a-zA-Z0-9_-]+$"
        }
      },
      "required": [
        "type",
        "server_label",
        "name"
      ]
    },
    "LiveMediaSessionAudioParam": {
      "type": "object",
      "description": "Startup audio output configuration. WebRTC and SIP negotiate the media format; audio.format is only accepted for primary WebSockets. Voice cannot change after startup.",
      "properties": {
        "output": {
          "$ref": "#/$defs/LiveInitialSessionAudioOutputParam"
        }
      },
      "additionalProperties": false
    },
    "LiveMediaSessionCreateParams": {
      "type": "object",
      "description": "Startup configuration for a Live media session. Follow the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) when writing frontend instructions and the backend prompt under delegation.responses.instructions.",
      "properties": {
        "model": {
          "$ref": "#/$defs/ModelIdsLive"
        },
        "instructions": {
          "$ref": "#/$defs/instructions"
        },
        "audio": {
          "$ref": "#/$defs/LiveMediaSessionAudioParam",
          "description": "Startup audio configuration. WebRTC and SIP negotiate their audio format on the media transport."
        },
        "delegation": {
          "$ref": "#/$defs/delegation"
        },
        "store": {
          "$ref": "#/$defs/store"
        },
        "input": {
          "$ref": "#/$defs/input"
        },
        "client": {
          "$ref": "#/$defs/LiveClientConfigParam"
        }
      },
      "required": [
        "model"
      ],
      "additionalProperties": false
    },
    "LiveReasoningEffort": {
      "type": "string",
      "enum": [
        "none",
        "minimal",
        "low",
        "medium",
        "high",
        "xhigh"
      ]
    },
    "LiveReasoningSummary": {
      "type": "string",
      "enum": [
        "concise",
        "detailed",
        "auto"
      ]
    },
    "LiveResponsesDelegationParam": {
      "description": "Delegate tasks to a Responses model managed by the Live session.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The delegation owner. Always `responses` for tasks handled by the Responses API.",
          "default": "responses",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "responses"
          ]
        },
        "responses": {
          "description": "Backend model, prompt, and tools used when the Live session delegates a task to Responses.",
          "$ref": "#/$defs/LiveResponsesDelegationSettingsInputParam"
        }
      },
      "required": [
        "type",
        "responses"
      ]
    },
    "LiveResponsesDelegationSettingsInputParam": {
      "description": "Model, prompt, and tool settings for tasks delegated by the Live session to a Responses backend.",
      "type": "object",
      "properties": {
        "model": {
          "description": "The model used for server-owned Responses delegations.",
          "type": "string"
        },
        "instructions": {
          "anyOf": [
            {
              "description": "Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt).",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_output_tokens": {
          "anyOf": [
            {
              "description": "Maximum number of output tokens for each delegated response.",
              "type": "integer",
              "minimum": 16
            },
            {
              "type": "null"
            }
          ]
        },
        "service_tier": {
          "anyOf": [
            {
              "description": "Service tier for delegated Responses requests.",
              "$ref": "#/$defs/LiveResponsesServiceTier"
            },
            {
              "type": "null"
            }
          ]
        },
        "reasoning": {
          "anyOf": [
            {
              "description": "Reasoning settings passed to each delegated Responses request.",
              "$ref": "#/$defs/LiveDelegationReasoningInputParam"
            },
            {
              "type": "null"
            }
          ]
        },
        "text": {
          "anyOf": [
            {
              "description": "Text generation settings passed to each delegated Responses request.",
              "$ref": "#/$defs/LiveDelegationTextInputParam"
            },
            {
              "type": "null"
            }
          ]
        },
        "tools": {
          "description": "Tools available to the Responses backend while it handles tasks delegated by the Live model.",
          "type": "array",
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/LiveFunctionToolInputParam"
              },
              {
                "$ref": "#/$defs/LiveWebSearchToolInputParam"
              }
            ]
          }
        },
        "tool_choice": {
          "description": "Controls which tool the Responses backend uses when handling a task delegated by the Live model.",
          "oneOf": [
            {
              "$ref": "#/$defs/LiveToolChoiceEnum"
            },
            {
              "$ref": "#/$defs/LiveFunctionToolChoiceParam"
            },
            {
              "$ref": "#/$defs/LiveMCPToolChoiceParam"
            }
          ]
        },
        "parallel_tool_calls": {
          "anyOf": [
            {
              "description": "Whether the delegated Responses model may request multiple tool calls in a single response.",
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model"
      ]
    },
    "LiveResponsesServiceTier": {
      "type": "string",
      "enum": [
        "auto",
        "default",
        "fast_tier_temp_pilot",
        "flex",
        "priority",
        "ultrafast"
      ]
    },
    "LiveTextVerbosity": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ]
    },
    "LiveToolChoiceEnum": {
      "type": "string",
      "enum": [
        "auto",
        "none",
        "required"
      ]
    },
    "LiveWebRTCTransport": {
      "type": "object",
      "description": "WebRTC transport carrying the offer SDP in a creation request or answer SDP in its response.",
      "properties": {
        "type": {
          "type": "string",
          "description": "The transport used for the Live session. Always `webrtc`.",
          "enum": [
            "webrtc"
          ],
          "x-stainless-const": true
        },
        "sdp": {
          "type": "string",
          "minLength": 1,
          "description": "Session Description Protocol message for the WebRTC connection."
        }
      },
      "required": [
        "type",
        "sdp"
      ],
      "additionalProperties": false
    },
    "LiveWebSearchToolInputParam": {
      "description": "A web search tool available to the Live session’s Responses backend.",
      "type": "object",
      "properties": {
        "type": {
          "description": "The tool type. Always `web_search`.",
          "default": "web_search",
          "x-stainless-const": true,
          "type": "string",
          "enum": [
            "web_search"
          ]
        }
      },
      "required": [
        "type"
      ]
    },
    "ModelIdsLive": {
      "description": "The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "string",
          "enum": [
            "gpt-live-1"
          ]
        }
      ]
    },
    "delegation": {
      "anyOf": [
        {
          "description": "Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend.",
          "oneOf": [
            {
              "$ref": "#/$defs/LiveClientDelegationParam"
            },
            {
              "$ref": "#/$defs/LiveResponsesDelegationParam"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "input": {
      "description": "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.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/LiveInitialItem"
      },
      "maxItems": 128
    },
    "instructions": {
      "anyOf": [
        {
          "description": "Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/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.",
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "store": {
      "description": "Whether to store the session for later forking and recording download. Defaults to false for new sessions.",
      "type": "boolean"
    }
  }
}