# Sideband ## `live.sideband.connect(SidebandConnectParams**kwargs)` **** `` Attach to an existing Live session. Do not send session.start again. ### Parameters - `graceful_close: Optional[bool]` Opt in to the graceful WebSocket closing handshake when the session ends. The server may also enable this behavior by default. ### Example ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted ) client.live.sideband.connect() ``` ## Domain Types ### Connect Client Event - `ConnectClientEvent` Client events accepted by an attached Live sideband WebSocket. The session is already started; send audio over the primary connection. - `class SessionUpdateEvent: …` Update the delegation settings of an active Live session. The server acknowledges accepted changes with `session.updated`. - `session: SessionUpdateConfig` Sparse delegation updates. Omitted settings retain their values. The delegation type cannot change, including resetting Responses delegation to null or client. Model, frontend instructions, audio, and startup input are immutable. - `delegation: Optional[Delegation]` Delegation settings to update. The delegation type must match the current session; omitted settings retain their values. - `class ClientDelegation: …` Delegate tasks to your application. The Live session emits delegation events that your backend handles. - `type: Literal["client"]` The delegation owner. Always `client` for tasks handled by your application. - `"client"` - `class DelegationResponses: …` Update the Responses backend for an existing Live session without changing delegation ownership. - `type: Literal["responses"]` The delegation owner. Always `responses` for tasks handled by the Responses API. - `"responses"` - `responses: Optional[ResponsesDelegationUpdateConfig]` Responses backend settings to update. Omitted settings keep their existing values. - `instructions: Optional[str]` 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[int]` Maximum number of output tokens for each delegated response. - `model: Optional[str]` The Responses backend model to use for subsequent delegated requests. Omit to keep the current backend model. - `parallel_tool_calls: Optional[bool]` Whether the delegated Responses model may request multiple tool calls in a single response. - `reasoning: Optional[Reasoning]` Reasoning settings passed to each delegated Responses request. - `effort: Optional[Literal["none", "minimal", "low", 3 more]]` 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[Literal["concise", "detailed", "auto"]]` The reasoning summary to request from the delegated Responses model, when supported. - `"concise"` - `"detailed"` - `"auto"` - `service_tier: Optional[Literal["auto", "default", "fast_tier_temp_pilot", 3 more]]` Service tier for delegated Responses requests. - `"auto"` - `"default"` - `"fast_tier_temp_pilot"` - `"flex"` - `"priority"` - `"ultrafast"` - `text: Optional[Text]` Text generation settings passed to each delegated Responses request. - `verbosity: Optional[Literal["low", "medium", "high"]]` 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[ToolChoice]` Controls which tool the Responses backend uses when handling a task delegated by the Live model. - `Literal["auto", "none", "required"]` - `"auto"` - `"none"` - `"required"` - `class ToolChoiceLiveFunctionToolChoiceParam: …` - `name: str` - `type: Literal["function"]` - `"function"` - `class ToolChoiceLiveMCPToolChoiceParam: …` - `name: str` - `server_label: str` - `type: Literal["mcp"]` - `"mcp"` - `tools: Optional[List[Tool]]` Tools available to the Responses backend while it handles tasks delegated by the Live model. - `class FunctionTool: …` A function tool available to the Responses backend when the Live model delegates a task. - `name: str` The name the delegated Responses model uses when calling this function. - `type: Literal["function"]` The tool type. Always `function`. - `"function"` - `description: Optional[str]` What the function does and when the delegated Responses model should call it. - `parameters: Optional[Dict[str, object]]` A JSON Schema object describing the arguments accepted by the function. - `strict: Optional[bool]` Whether the delegated Responses model must follow the function’s parameter schema exactly. - `class ToolWebSearch: …` A web search tool available to the Live session’s Responses backend. - `type: Literal["web_search"]` The tool type. Always `web_search`. - `"web_search"` - `type: Literal["session.update"]` The Live client event type. Always `session.update`. - `"session.update"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class InputAudioMuteEvent: …` Mute audio input to the Live model without closing the session. The server acknowledges with `session.input_audio.muted`. - `type: Literal["session.input_audio.mute"]` The Live client event type. Always `session.input_audio.mute`. - `"session.input_audio.mute"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class InputAudioUnmuteEvent: …` Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. - `type: Literal["session.input_audio.unmute"]` The Live client event type. Always `session.input_audio.unmute`. - `"session.input_audio.unmute"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class InstructionsAppendEvent: …` Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. - `content: str` Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts. - `delegation_id: Optional[str]` Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - `type: Literal["session.instructions.append"]` The Live client event type. Always `session.instructions.append`. - `"session.instructions.append"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class ThinkingAppendEvent: …` Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. - `content: str` Silent reasoning or progress context, limited to 500 tokens. It does not directly request speech, but can influence later speech and is not a secrecy boundary. - `delegation_id: Optional[str]` Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - `type: Literal["session.thinking.append"]` The Live client event type. Always `session.thinking.append`. - `"session.thinking.append"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class CommentaryAppendEvent: …` Provide context the Live model can communicate to the user, optionally for an existing client delegation. - `content: str` Speakable context for the Live model, limited to 500 tokens. Use this for a result the model should communicate; use session.thinking.append for silent context. - `delegation_id: Optional[str]` Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - `type: Literal["session.commentary.append"]` The Live client event type. Always `session.commentary.append`. - `"session.commentary.append"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class ResponseItemCreateEvent: …` Add an input item to the Live session’s Responses backend. Requires Responses delegation; use `response.create` to request a response. - `item: ResponseInputItem` An input item to append to the Responses backend conversation, such as a user message or a function tool result. - `class EasyInputMessage: …` A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. Messages with the `assistant` role are presumed to have been generated by the model in previous interactions. - `content: Union[str, ResponseInputMessageContentList]` Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - `str` A text input to the model. - `List[ResponseInputContent]` - `class ResponseInputText: …` A text input to the model. - `text: str` The text input to the model. - `type: Literal["input_text"]` The type of the input item. Always `input_text`. - `"input_text"` - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: Literal["explicit"]` The breakpoint mode. Always `explicit`. - `"explicit"` - `class ResponseInputImage: …` An image input to the model. Learn about [image inputs](/api/docs/guides/images-vision). - `detail: ImageDetail` 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"` - `type: Literal["input_image"]` The type of the input item. Always `input_image`. - `"input_image"` - `file_id: Optional[str]` The ID of the file to be sent to the model. - `image_url: Optional[str]` The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: Literal["explicit"]` The breakpoint mode. Always `explicit`. - `"explicit"` - `class ResponseInputFile: …` A file input to the model. - `type: Literal["input_file"]` The type of the input item. Always `input_file`. - `"input_file"` - `detail: Optional[Literal["auto", "low", "high"]]` The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - `"low"` - `"high"` - `file_data: Optional[str]` The content of the file to be sent to the model. - `file_id: Optional[str]` The ID of the file to be sent to the model. - `file_url: Optional[str]` The URL of the file to be sent to the model. - `filename: Optional[str]` The name of the file to be sent to the model. - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: Literal["explicit"]` The breakpoint mode. Always `explicit`. - `"explicit"` - `role: Literal["user", "assistant", "system", "developer"]` The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `"user"` - `"assistant"` - `"system"` - `"developer"` - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `"commentary"` - `"final_answer"` - `type: Optional[Literal["message"]]` The type of the message input. Always `message`. - `"message"` - `class Message: …` A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. - `content: ResponseInputMessageContentList` A list of one or many input items to the model, containing different content types. - `class ResponseInputText: …` A text input to the model. - `class ResponseInputImage: …` An image input to the model. Learn about [image inputs](/api/docs/guides/images-vision). - `class ResponseInputFile: …` A file input to the model. - `role: Literal["user", "system", "developer"]` The role of the message input. One of `user`, `system`, or `developer`. - `"user"` - `"system"` - `"developer"` - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `type: Optional[Literal["message"]]` The type of the message input. Always set to `message`. - `"message"` - `class ResponseOutputMessage: …` An output message from the model. - `id: str` The unique ID of the output message. - `content: List[Content]` The content of the output message. - `class ResponseOutputText: …` A text output from the model. - `annotations: List[Annotation]` The annotations of the text output. - `class AnnotationFileCitation: …` A citation to a file. - `file_id: str` The ID of the file. - `filename: str` The filename of the file cited. - `index: int` The index of the file in the list of files. - `type: Literal["file_citation"]` The type of the file citation. Always `file_citation`. - `"file_citation"` - `class AnnotationURLCitation: …` A citation for a web resource used to generate a model response. - `end_index: int` The index of the last character of the URL citation in the message. - `start_index: int` The index of the first character of the URL citation in the message. - `title: str` The title of the web resource. - `type: Literal["url_citation"]` The type of the URL citation. Always `url_citation`. - `"url_citation"` - `url: str` The URL of the web resource. - `class AnnotationContainerFileCitation: …` A citation for a container file used to generate a model response. - `container_id: str` The ID of the container file. - `end_index: int` The index of the last character of the container file citation in the message. - `file_id: str` The ID of the file. - `filename: str` The filename of the container file cited. - `start_index: int` The index of the first character of the container file citation in the message. - `type: Literal["container_file_citation"]` The type of the container file citation. Always `container_file_citation`. - `"container_file_citation"` - `class AnnotationFilePath: …` A path to a file. - `file_id: str` The ID of the file. - `index: int` The index of the file in the list of files. - `type: Literal["file_path"]` The type of the file path. Always `file_path`. - `"file_path"` - `text: str` The text output from the model. - `type: Literal["output_text"]` The type of the output text. Always `output_text`. - `"output_text"` - `logprobs: Optional[List[Logprob]]` - `token: str` - `bytes: List[int]` - `logprob: float` - `top_logprobs: List[LogprobTopLogprob]` - `token: str` - `bytes: List[int]` - `logprob: float` - `class ResponseOutputRefusal: …` A refusal from the model. - `refusal: str` The refusal explanation from the model. - `type: Literal["refusal"]` The type of the refusal. Always `refusal`. - `"refusal"` - `role: Literal["assistant"]` The role of the output message. Always `assistant`. - `"assistant"` - `status: Literal["in_progress", "completed", "incomplete"]` The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `type: Literal["message"]` The type of the output message. Always `message`. - `"message"` - `phase: Optional[Literal["commentary", "final_answer"]]` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `"commentary"` - `"final_answer"` - `class ResponseFileSearchToolCall: …` The results of a file search tool call. See the [file search guide](/api/docs/guides/tools-file-search) for more information. - `id: str` The unique ID of the file search tool call. - `queries: List[str]` The queries used to search for files. - `status: Literal["in_progress", "searching", "completed", 2 more]` The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `"in_progress"` - `"searching"` - `"completed"` - `"incomplete"` - `"failed"` - `type: Literal["file_search_call"]` The type of the file search tool call. Always `file_search_call`. - `"file_search_call"` - `results: Optional[List[Result]]` The results of the file search tool call. - `attributes: Optional[Dict[str, Union[str, float, bool]]]` Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers. - `str` - `float` - `bool` - `file_id: Optional[str]` The unique ID of the file. - `filename: Optional[str]` The name of the file. - `score: Optional[float]` The relevance score of the file - a value between 0 and 1. - `text: Optional[str]` The text that was retrieved from the file. - `class ResponseComputerToolCall: …` A tool call to a computer use tool. See the [computer use guide](/api/docs/guides/tools-computer-use) for more information. - `id: str` The unique ID of the computer call. - `call_id: str` An identifier used when responding to the tool call with output. - `pending_safety_checks: List[PendingSafetyCheck]` The pending safety checks for the computer call. - `id: str` The ID of the pending safety check. - `code: Optional[str]` The type of the pending safety check. - `message: Optional[str]` Details about the pending safety check. - `status: Literal["in_progress", "completed", "incomplete"]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `type: Literal["computer_call"]` The type of the computer call. Always `computer_call`. - `"computer_call"` - `action: Optional[Action]` A click action. - `class ActionClick: …` A click action. - `button: Literal["left", "right", "wheel", 2 more]` Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - `"left"` - `"right"` - `"wheel"` - `"back"` - `"forward"` - `type: Literal["click"]` Specifies the event type. For a click action, this property is always `click`. - `"click"` - `x: int` The x-coordinate where the click occurred. - `y: int` The y-coordinate where the click occurred. - `keys: Optional[List[str]]` The keys being held while clicking. - `class ActionDoubleClick: …` A double click action. - `keys: Optional[List[str]]` The keys being held while double-clicking. - `type: Literal["double_click"]` Specifies the event type. For a double click action, this property is always set to `double_click`. - `"double_click"` - `x: int` The x-coordinate where the double click occurred. - `y: int` The y-coordinate where the double click occurred. - `class ActionDrag: …` A drag action. - `path: List[ActionDragPath]` An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg ``` [ { x: 100, y: 200 }, { x: 200, y: 300 } ] ``` - `x: int` The x-coordinate. - `y: int` The y-coordinate. - `type: Literal["drag"]` Specifies the event type. For a drag action, this property is always set to `drag`. - `"drag"` - `keys: Optional[List[str]]` The keys being held while dragging the mouse. - `class ActionKeypress: …` A collection of keypresses the model would like to perform. - `keys: List[str]` The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `type: Literal["keypress"]` Specifies the event type. For a keypress action, this property is always set to `keypress`. - `"keypress"` - `class ActionMove: …` A mouse move action. - `type: Literal["move"]` Specifies the event type. For a move action, this property is always set to `move`. - `"move"` - `x: int` The x-coordinate to move to. - `y: int` The y-coordinate to move to. - `keys: Optional[List[str]]` The keys being held while moving the mouse. - `class ActionScreenshot: …` A screenshot action. - `type: Literal["screenshot"]` Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - `"screenshot"` - `class ActionScroll: …` A scroll action. - `scroll_x: int` The horizontal scroll distance. - `scroll_y: int` The vertical scroll distance. - `type: Literal["scroll"]` Specifies the event type. For a scroll action, this property is always set to `scroll`. - `"scroll"` - `x: int` The x-coordinate where the scroll occurred. - `y: int` The y-coordinate where the scroll occurred. - `keys: Optional[List[str]]` The keys being held while scrolling. - `class ActionType: …` An action to type in text. - `text: str` The text to type. - `type: Literal["type"]` Specifies the event type. For a type action, this property is always set to `type`. - `"type"` - `class ActionWait: …` A wait action. - `type: Literal["wait"]` Specifies the event type. For a wait action, this property is always set to `wait`. - `"wait"` - `actions: Optional[ComputerActionList]` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - `class Click: …` A click action. - `button: Literal["left", "right", "wheel", 2 more]` Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - `"left"` - `"right"` - `"wheel"` - `"back"` - `"forward"` - `type: Literal["click"]` Specifies the event type. For a click action, this property is always `click`. - `"click"` - `x: int` The x-coordinate where the click occurred. - `y: int` The y-coordinate where the click occurred. - `keys: Optional[List[str]]` The keys being held while clicking. - `class DoubleClick: …` A double click action. - `keys: Optional[List[str]]` The keys being held while double-clicking. - `type: Literal["double_click"]` Specifies the event type. For a double click action, this property is always set to `double_click`. - `"double_click"` - `x: int` The x-coordinate where the double click occurred. - `y: int` The y-coordinate where the double click occurred. - `class Drag: …` A drag action. - `path: List[DragPath]` An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg ``` [ { x: 100, y: 200 }, { x: 200, y: 300 } ] ``` - `x: int` The x-coordinate. - `y: int` The y-coordinate. - `type: Literal["drag"]` Specifies the event type. For a drag action, this property is always set to `drag`. - `"drag"` - `keys: Optional[List[str]]` The keys being held while dragging the mouse. - `class Keypress: …` A collection of keypresses the model would like to perform. - `keys: List[str]` The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `type: Literal["keypress"]` Specifies the event type. For a keypress action, this property is always set to `keypress`. - `"keypress"` - `class Move: …` A mouse move action. - `type: Literal["move"]` Specifies the event type. For a move action, this property is always set to `move`. - `"move"` - `x: int` The x-coordinate to move to. - `y: int` The y-coordinate to move to. - `keys: Optional[List[str]]` The keys being held while moving the mouse. - `class Screenshot: …` A screenshot action. - `type: Literal["screenshot"]` Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - `"screenshot"` - `class Scroll: …` A scroll action. - `scroll_x: int` The horizontal scroll distance. - `scroll_y: int` The vertical scroll distance. - `type: Literal["scroll"]` Specifies the event type. For a scroll action, this property is always set to `scroll`. - `"scroll"` - `x: int` The x-coordinate where the scroll occurred. - `y: int` The y-coordinate where the scroll occurred. - `keys: Optional[List[str]]` The keys being held while scrolling. - `class Type: …` An action to type in text. - `text: str` The text to type. - `type: Literal["type"]` Specifies the event type. For a type action, this property is always set to `type`. - `"type"` - `class Wait: …` A wait action. - `type: Literal["wait"]` Specifies the event type. For a wait action, this property is always set to `wait`. - `"wait"` - `class ComputerCallOutput: …` The output of a computer tool call. - `call_id: str` The ID of the computer tool call that produced the output. - `output: ResponseComputerToolCallOutputScreenshot` A computer screenshot image used with the computer use tool. - `type: Literal["computer_screenshot"]` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `"computer_screenshot"` - `file_id: Optional[str]` The identifier of an uploaded file that contains the screenshot. - `image_url: Optional[str]` The URL of the screenshot image. - `type: Literal["computer_call_output"]` The type of the computer tool call output. Always `computer_call_output`. - `"computer_call_output"` - `id: Optional[str]` The ID of the computer tool call output. - `acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]]` The safety checks reported by the API that have been acknowledged by the developer. - `id: str` The ID of the pending safety check. - `code: Optional[str]` The type of the pending safety check. - `message: Optional[str]` Details about the pending safety check. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ResponseFunctionWebSearch: …` The results of a web search tool call. See the [web search guide](/api/docs/guides/tools-web-search) for more information. - `id: str` The unique ID of the web search tool call. - `action: Action` An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - `class ActionSearch: …` Action type "search" - Performs a web search query. - `type: Literal["search"]` The action type. - `"search"` - `queries: Optional[List[str]]` The search queries. - `query: Optional[str]` The search query. - `sources: Optional[List[ActionSearchSource]]` The sources used in the search. - `type: Literal["url"]` The type of source. Always `url`. - `"url"` - `url: str` The URL of the source. - `class ActionOpenPage: …` Action type "open_page" - Opens a specific URL from search results. - `type: Literal["open_page"]` The action type. - `"open_page"` - `url: Optional[str]` The URL opened by the model. - `class ActionFindInPage: …` Action type "find_in_page": Searches for a pattern within a loaded page. - `pattern: str` The pattern or text to search for within the page. - `type: Literal["find_in_page"]` The action type. - `"find_in_page"` - `url: str` The URL of the page searched for the pattern. - `status: Literal["in_progress", "searching", "completed", 2 more]` The status of the web search tool call. - `"in_progress"` - `"searching"` - `"completed"` - `"failed"` - `"incomplete"` - `type: Literal["web_search_call"]` The type of the web search tool call. Always `web_search_call`. - `"web_search_call"` - `class ResponseFunctionToolCall: …` A tool call to run a function. See the [function calling guide](/api/docs/guides/function-calling) for more information. - `arguments: str` A JSON string of the arguments to pass to the function. - `call_id: str` The unique ID of the function tool call generated by the model. - `name: str` The name of the function to run. - `type: Literal["function_call"]` The type of the function tool call. Always `function_call`. - `"function_call"` - `id: Optional[str]` The unique ID of the function tool call. - `async_: Optional[bool]` Whether the function tool call runs asynchronously. - `caller: Optional[Caller]` The execution context that produced this tool call. - `class CallerDirect: …` - `type: Literal["direct"]` - `"direct"` - `class CallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` - `"program"` - `namespace: Optional[str]` The namespace of the function to run. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `class FunctionCallOutput: …` The output of a function tool call. - `output: Union[str, ResponseFunctionCallOutputItemList]` Text, image, or file output of the function tool call. - `str` A JSON string of the output of the function tool call. - `List[ResponseFunctionCallOutputItem]` - `class ResponseInputTextContent: …` A text input to the model. - `text: str` The text input to the model. - `type: Literal["input_text"]` The type of the input item. Always `input_text`. - `"input_text"` - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: Literal["explicit"]` The breakpoint mode. Always `explicit`. - `"explicit"` - `class ResponseInputImageContent: …` An image input to the model. Learn about [image inputs](/api/docs/guides/images-vision) - `type: Literal["input_image"]` The type of the input item. Always `input_image`. - `"input_image"` - `detail: Optional[ImageDetail]` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `file_id: Optional[str]` The ID of the file to be sent to the model. - `image_url: Optional[str]` The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: Literal["explicit"]` The breakpoint mode. Always `explicit`. - `"explicit"` - `class ResponseInputFileContent: …` A file input to the model. - `type: Literal["input_file"]` The type of the input item. Always `input_file`. - `"input_file"` - `detail: Optional[Literal["auto", "low", "high"]]` The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - `"low"` - `"high"` - `file_data: Optional[str]` The base64-encoded data of the file to be sent to the model. - `file_id: Optional[str]` The ID of the file to be sent to the model. - `file_url: Optional[str]` The URL of the file to be sent to the model. - `filename: Optional[str]` The name of the file to be sent to the model. - `prompt_cache_breakpoint: Optional[PromptCacheBreakpoint]` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - `mode: Literal["explicit"]` The breakpoint mode. Always `explicit`. - `"explicit"` - `type: Literal["function_call_output"]` The type of the function tool call output. Always `function_call_output`. - `"function_call_output"` - `id: Optional[str]` The unique ID of the function tool call output. Populated when this item is returned via API. - `call_id: Optional[str]` The unique ID of the function tool call generated by the model. - `caller: Optional[FunctionCallOutputCaller]` The execution context that produced this tool call. - `class FunctionCallOutputCallerDirect: …` - `type: Literal["direct"]` The caller type. Always `direct`. - `"direct"` - `class FunctionCallOutputCallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` The caller type. Always `program`. - `"program"` - `name: Optional[str]` The name of the tool that produced the output. - `namespace: Optional[str]` The namespace of the tool that produced the output. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ToolSearchCall: …` - `arguments: object` The arguments supplied to the tool search call. - `type: Literal["tool_search_call"]` The item type. Always `tool_search_call`. - `"tool_search_call"` - `id: Optional[str]` The unique ID of this tool search call. - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - `execution: Optional[Literal["server", "client"]]` Whether tool search was executed by the server or by the client. - `"server"` - `"client"` - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the tool search call. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ResponseToolSearchOutputItemParam: …` - `tools: List[Tool]` The loaded tool definitions returned by the tool search output. - `class FunctionTool: …` Defines a function in your own code the model can choose to call. Learn more about [function calling](/api/docs/guides/function-calling). - `name: str` The name of the function to call. - `parameters: Optional[Dict[str, object]]` A JSON schema object describing the parameters of the function. - `strict: Optional[bool]` Whether strict parameter validation is enforced for this function tool. - `type: Literal["function"]` The type of the function tool. Always `function`. - `"function"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `async_: Optional[bool]` - `defer_loading: Optional[bool]` Whether this function is deferred and loaded via tool search. - `description: Optional[str]` A description of the function. Used by the model to determine whether or not to call the function. - `output_schema: Optional[Dict[str, object]]` A JSON schema object describing the JSON value encoded in string outputs for this function. - `class FileSearchTool: …` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](/api/docs/guides/tools-file-search). - `type: Literal["file_search"]` The type of the file search tool. Always `file_search`. - `"file_search"` - `vector_store_ids: List[str]` The IDs of the vector stores to search. - `filters: Optional[Filters]` A filter to apply. - `class ComparisonFilter: …` A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `key: str` The key to compare against the value. - `type: Literal["eq", "ne", "gt", 5 more]` Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in - `"eq"` - `"ne"` - `"gt"` - `"gte"` - `"lt"` - `"lte"` - `"in"` - `"nin"` - `value: Union[str, float, bool, List[Union[str, float]]]` The value to compare against the attribute key; supports string, number, or boolean types. - `str` - `float` - `bool` - `List[Union[str, float]]` - `str` - `float` - `class CompoundFilter: …` Combine multiple filters using `and` or `or`. - `filters: List[Filter]` Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - `class ComparisonFilter: …` A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `object` - `type: Literal["and", "or"]` Type of operation: `and` or `or`. - `"and"` - `"or"` - `max_num_results: Optional[int]` The maximum number of results to return. This number should be between 1 and 50 inclusive. - `ranking_options: Optional[RankingOptions]` Ranking options for search. - `hybrid_search: Optional[RankingOptionsHybridSearch]` Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - `embedding_weight: float` The weight of the embedding in the reciprocal ranking fusion. - `text_weight: float` The weight of the text in the reciprocal ranking fusion. - `ranker: Optional[Literal["auto", "default-2024-11-15"]]` The ranker to use for the file search. - `"auto"` - `"default-2024-11-15"` - `score_threshold: Optional[float]` The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - `class ComputerTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](/api/docs/guides/tools-computer-use). - `type: Literal["computer"]` The type of the computer tool. Always `computer`. - `"computer"` - `class ComputerUsePreviewTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](/api/docs/guides/tools-computer-use). - `display_height: int` The height of the computer display. - `display_width: int` The width of the computer display. - `environment: Literal["windows", "mac", "linux", 2 more]` The type of computer environment to control. - `"windows"` - `"mac"` - `"linux"` - `"ubuntu"` - `"browser"` - `type: Literal["computer_use_preview"]` The type of the computer use tool. Always `computer_use_preview`. - `"computer_use_preview"` - `class WebSearchTool: …` Search the Internet for sources related to the prompt. Learn more about the [web search tool](/api/docs/guides/tools-web-search). - `type: Literal["web_search", "web_search_2025_08_26"]` The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - `"web_search"` - `"web_search_2025_08_26"` - `external_web_access: Optional[bool]` Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. - `filters: Optional[Filters]` Filters for the search. - `allowed_domains: Optional[List[str]]` Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size: Optional[Literal["low", "medium", "high"]]` High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` - `"medium"` - `"high"` - `user_location: Optional[UserLocation]` The approximate location of the user. - `city: Optional[str]` Free text input for the city of the user, e.g. `San Francisco`. - `country: Optional[str]` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region: Optional[str]` Free text input for the region of the user, e.g. `California`. - `timezone: Optional[str]` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type: Optional[Literal["approximate"]]` The type of location approximation. Always `approximate`. - `"approximate"` - `class Mcp: …` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](/api/docs/guides/tools-connectors-mcp). - `server_label: str` A label for this MCP server, used to identify it in tool calls. - `type: Literal["mcp"]` The type of the MCP tool. Always `mcp`. - `"mcp"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `allowed_tools: Optional[McpAllowedTools]` List of allowed tool names or a filter object. - `List[str]` A string array of allowed tool names - `class McpAllowedToolsMcpToolFilter: …` A filter object to specify which tools are allowed. - `read_only: Optional[bool]` Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `tool_names: Optional[List[str]]` List of allowed tool names. - `authorization: Optional[str]` An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. - `connector_id: Optional[Literal["connector_dropbox", "connector_gmail", "connector_googlecalendar", 5 more]]` Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about service connectors [here](/api/docs/guides/tools-connectors-mcp#connectors). Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` - `"connector_dropbox"` - `"connector_gmail"` - `"connector_googlecalendar"` - `"connector_googledrive"` - `"connector_microsoftteams"` - `"connector_outlookcalendar"` - `"connector_outlookemail"` - `"connector_sharepoint"` - `defer_loading: Optional[bool]` Whether this MCP tool is deferred and discovered via tool search. - `headers: Optional[Dict[str, str]]` Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `require_approval: Optional[McpRequireApproval]` Specify which of the MCP server's tools require approval. - `class McpRequireApprovalMcpToolApprovalFilter: …` Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval. - `always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways]` A filter object to specify which tools are allowed. - `read_only: Optional[bool]` Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `tool_names: Optional[List[str]]` List of allowed tool names. - `never: Optional[McpRequireApprovalMcpToolApprovalFilterNever]` A filter object to specify which tools are allowed. - `read_only: Optional[bool]` Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `tool_names: Optional[List[str]]` List of allowed tool names. - `Literal["always", "never"]` Specify a single approval policy for all tools. One of `always` or `never`. When set to `always`, all tools will require approval. When set to `never`, all tools will not require approval. - `"always"` - `"never"` - `server_description: Optional[str]` Optional description of the MCP server, used to provide more context. - `server_url: Optional[str]` The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `tunnel_id: Optional[str]` The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `class CodeInterpreter: …` A tool that runs Python code to help generate a response to a prompt. - `container: CodeInterpreterContainer` The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting. - `str` The container ID. - `class CodeInterpreterContainerCodeInterpreterToolAuto: …` Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `type: Literal["auto"]` Always `auto`. - `"auto"` - `file_ids: Optional[List[str]]` An optional list of uploaded files to make available to your code. - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` The memory limit for the code interpreter container. - `"1g"` - `"4g"` - `"16g"` - `"64g"` - `network_policy: Optional[CodeInterpreterContainerCodeInterpreterToolAutoNetworkPolicy]` Network access policy for the container. - `class ContainerNetworkPolicyDisabled: …` - `type: Literal["disabled"]` Disable outbound network access. Always `disabled`. - `"disabled"` - `class ContainerNetworkPolicyAllowlist: …` - `allowed_domains: List[str]` A list of allowed domains when type is `allowlist`. - `type: Literal["allowlist"]` Allow outbound network access only to specified domains. Always `allowlist`. - `"allowlist"` - `domain_secrets: Optional[List[ContainerNetworkPolicyDomainSecret]]` Optional domain-scoped secrets for allowlisted domains. - `domain: str` The domain associated with the secret. - `name: str` The name of the secret to inject for the domain. - `value: str` The secret value to inject for the domain. - `type: Literal["code_interpreter"]` The type of the code interpreter tool. Always `code_interpreter`. - `"code_interpreter"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `class ProgrammaticToolCalling: …` - `type: Literal["programmatic_tool_calling"]` The type of the tool. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `class ImageGeneration: …` A tool that generates images using the GPT image models. - `type: Literal["image_generation"]` The type of the image generation tool. Always `image_generation`. - `"image_generation"` - `action: Optional[Literal["generate", "edit", "auto"]]` Whether to generate a new image or edit an existing image. Default: `auto`. - `"generate"` - `"edit"` - `"auto"` - `background: Optional[Literal["transparent", "opaque", "auto"]]` Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. - `"transparent"` - `"opaque"` - `"auto"` - `input_fidelity: Optional[Literal["high", "low"]]` Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - `"high"` - `"low"` - `input_image_mask: Optional[ImageGenerationInputImageMask]` Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `file_id: Optional[str]` File ID for the mask image. - `image_url: Optional[str]` Base64-encoded mask image. - `model: Optional[Union[str, Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 7 more], null]]` The image generation model to use. One of `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: `gpt-image-1`. - `str` - `Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 7 more]` The image generation model to use. One of `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: `gpt-image-1`. - `"gpt-image-1"` - `"gpt-image-1-mini"` - `"gpt-image-2"` - `"gpt-image-2-2026-04-21"` - `"gpt-image-2.5-sunburst"` - `"gpt-image-2.5-sunburst-2026-09-08"` - `"gpt-image-2.5-flare"` - `"gpt-image-2.5-flare-2026-09-08"` - `"gpt-image-1.5"` - `"chatgpt-image-latest"` - `moderation: Optional[Literal["auto", "low"]]` Moderation level for the generated image. Default: `auto`. - `"auto"` - `"low"` - `output_compression: Optional[int]` Compression level for the output image. Default: 100. - `output_format: Optional[Literal["png", "webp", "jpeg"]]` The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `"png"` - `"webp"` - `"jpeg"` - `partial_images: Optional[int]` Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `quality: Optional[Literal["low", "medium", "high", 3 more]]` The quality of the generated image. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Default: `auto`. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `"auto"` - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"], null]]` The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - `str` - `Literal["1024x1024", "1024x1536", "1536x1024", "auto"]` The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - `"1024x1024"` - `"1024x1536"` - `"1536x1024"` - `"auto"` - `class LocalShell: …` A tool that allows the model to execute shell commands in a local environment. - `type: Literal["local_shell"]` The type of the local shell tool. Always `local_shell`. - `"local_shell"` - `class FunctionShellTool: …` A tool that allows the model to execute shell commands. - `type: Literal["shell"]` The type of the shell tool. Always `shell`. - `"shell"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `environment: Optional[Environment]` - `class ContainerAuto: …` - `type: Literal["container_auto"]` Automatically creates a container for this request - `"container_auto"` - `file_ids: Optional[List[str]]` An optional list of uploaded files to make available to your code. - `memory_limit: Optional[Literal["1g", "4g", "16g", "64g"]]` The memory limit for the container. - `"1g"` - `"4g"` - `"16g"` - `"64g"` - `network_policy: Optional[NetworkPolicy]` Network access policy for the container. - `class ContainerNetworkPolicyDisabled: …` - `class ContainerNetworkPolicyAllowlist: …` - `skills: Optional[List[Skill]]` An optional list of skills referenced by id or inline data. - `class SkillReference: …` - `skill_id: str` The ID of the referenced skill. - `type: Literal["skill_reference"]` References a skill created with the /v1/skills endpoint. - `"skill_reference"` - `version: Optional[str]` Optional skill version. Use a positive integer or 'latest'. Omit for default. - `class InlineSkill: …` - `description: str` The description of the skill. - `name: str` The name of the skill. - `source: InlineSkillSource` Inline skill payload - `data: str` Base64-encoded skill zip bundle. - `media_type: Literal["application/zip"]` The media type of the inline skill payload. Must be `application/zip`. - `"application/zip"` - `type: Literal["base64"]` The type of the inline skill source. Must be `base64`. - `"base64"` - `type: Literal["inline"]` Defines an inline skill for this request. - `"inline"` - `class LocalEnvironment: …` - `type: Literal["local"]` Use a local computer environment. - `"local"` - `skills: Optional[List[LocalSkill]]` An optional list of skills. - `description: str` The description of the skill. - `name: str` The name of the skill. - `path: str` The path to the directory containing the skill. - `class ContainerReference: …` - `container_id: str` The ID of the referenced container. - `type: Literal["container_reference"]` References a container created with the /v1/containers endpoint - `"container_reference"` - `class CustomTool: …` A custom tool that processes input using a specified format. Learn more about [custom tools](/api/docs/guides/function-calling#custom-tools) - `name: str` The name of the custom tool, used to identify it in tool calls. - `type: Literal["custom"]` The type of the custom tool. Always `custom`. - `"custom"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `async_: Optional[bool]` Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - `defer_loading: Optional[bool]` Whether this tool should be deferred and discovered via tool search. - `description: Optional[str]` Optional description of the custom tool, used to provide more context. - `format: Optional[CustomToolInputFormat]` The input format for the custom tool. Default is unconstrained text. - `class Text: …` Unconstrained free-form text. - `type: Literal["text"]` Unconstrained text format. Always `text`. - `"text"` - `class Grammar: …` A grammar defined by the user. - `definition: str` The grammar definition. - `syntax: Literal["lark", "regex"]` The syntax of the grammar definition. One of `lark` or `regex`. - `"lark"` - `"regex"` - `type: Literal["grammar"]` Grammar format. Always `grammar`. - `"grammar"` - `class NamespaceTool: …` Groups function/custom tools under a shared namespace. - `description: str` A description of the namespace shown to the model. - `name: str` The namespace name used in tool calls (for example, `crm`). - `tools: List[Tool]` The function/custom tools available inside this namespace. - `class ToolFunction: …` - `name: str` - `type: Literal["function"]` - `"function"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `async_: Optional[bool]` Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - `defer_loading: Optional[bool]` Whether this function should be deferred and discovered via tool search. - `description: Optional[str]` - `output_schema: Optional[Dict[str, object]]` A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - `parameters: Optional[object]` - `strict: Optional[bool]` Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - `class CustomTool: …` A custom tool that processes input using a specified format. Learn more about [custom tools](/api/docs/guides/function-calling#custom-tools) - `type: Literal["namespace"]` The type of the tool. Always `namespace`. - `"namespace"` - `class ToolSearchTool: …` Hosted or BYOT tool search configuration for deferred tools. - `type: Literal["tool_search"]` The type of the tool. Always `tool_search`. - `"tool_search"` - `description: Optional[str]` Description shown to the model for a client-executed tool search tool. - `execution: Optional[Literal["server", "client"]]` Whether tool search is executed by the server or by the client. - `"server"` - `"client"` - `parameters: Optional[object]` Parameter schema for a client-executed tool search tool. - `class WebSearchPreviewTool: …` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](/api/docs/guides/tools-web-search). - `type: Literal["web_search_preview", "web_search_preview_2025_03_11"]` The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - `"web_search_preview"` - `"web_search_preview_2025_03_11"` - `search_content_types: Optional[List[Literal["text", "image"]]]` - `"text"` - `"image"` - `search_context_size: Optional[Literal["low", "medium", "high"]]` High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` - `"medium"` - `"high"` - `user_location: Optional[UserLocation]` The user's location. - `type: Literal["approximate"]` The type of location approximation. Always `approximate`. - `"approximate"` - `city: Optional[str]` Free text input for the city of the user, e.g. `San Francisco`. - `country: Optional[str]` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region: Optional[str]` Free text input for the region of the user, e.g. `California`. - `timezone: Optional[str]` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `class ApplyPatchTool: …` Allows the assistant to create, delete, or update files using unified diffs. - `type: Literal["apply_patch"]` The type of the tool. Always `apply_patch`. - `"apply_patch"` - `allowed_callers: Optional[List[Literal["direct", "programmatic"]]]` The tool invocation context(s). - `"direct"` - `"programmatic"` - `type: Literal["tool_search_output"]` The item type. Always `tool_search_output`. - `"tool_search_output"` - `id: Optional[str]` The unique ID of this tool search output. - `call_id: Optional[str]` The unique ID of the tool search call generated by the model. - `execution: Optional[Literal["server", "client"]]` Whether tool search was executed by the server or by the client. - `"server"` - `"client"` - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the tool search output. - `"in_progress"` - `"completed"` - `"incomplete"` - `class AdditionalTools: …` - `role: Literal["developer"]` The role that provided the additional tools. Only `developer` is supported. - `"developer"` - `tools: List[Tool]` A list of additional tools made available at this item. - `class FunctionTool: …` Defines a function in your own code the model can choose to call. Learn more about [function calling](/api/docs/guides/function-calling). - `class FileSearchTool: …` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](/api/docs/guides/tools-file-search). - `class ComputerTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](/api/docs/guides/tools-computer-use). - `class ComputerUsePreviewTool: …` A tool that controls a virtual computer. Learn more about the [computer tool](/api/docs/guides/tools-computer-use). - `class WebSearchTool: …` Search the Internet for sources related to the prompt. Learn more about the [web search tool](/api/docs/guides/tools-web-search). - `class Mcp: …` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](/api/docs/guides/tools-connectors-mcp). - `class CodeInterpreter: …` A tool that runs Python code to help generate a response to a prompt. - `class ProgrammaticToolCalling: …` - `class ImageGeneration: …` A tool that generates images using the GPT image models. - `class LocalShell: …` A tool that allows the model to execute shell commands in a local environment. - `class FunctionShellTool: …` A tool that allows the model to execute shell commands. - `class CustomTool: …` A custom tool that processes input using a specified format. Learn more about [custom tools](/api/docs/guides/function-calling#custom-tools) - `class NamespaceTool: …` Groups function/custom tools under a shared namespace. - `class ToolSearchTool: …` Hosted or BYOT tool search configuration for deferred tools. - `class WebSearchPreviewTool: …` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](/api/docs/guides/tools-web-search). - `class ApplyPatchTool: …` Allows the assistant to create, delete, or update files using unified diffs. - `type: Literal["additional_tools"]` The item type. Always `additional_tools`. - `"additional_tools"` - `id: Optional[str]` The unique ID of this additional tools item. - `class ResponseConfigurationUpdateItemParam: …` An update to the conversation's response configuration. The configuration remains in effect for subsequent responses until it is replaced by another configuration update. - `type: Literal["configuration_update"]` The item type. Always `configuration_update`. - `"configuration_update"` - `id: Optional[str]` The unique ID of the configuration update item. - `reasoning: Optional[Reasoning]` Updates to reasoning configuration. Only effort is supported. - `effort: Optional[ReasoningEffort]` The reasoning effort to use for subsequent responses until another configuration update replaces it. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `class ResponseReasoningItem: …` A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](/api/docs/guides/conversation-state). - `id: str` The unique identifier of the reasoning content. - `summary: List[Summary]` Reasoning summary content. - `text: str` A summary of the reasoning output from the model so far. - `type: Literal["summary_text"]` The type of the object. Always `summary_text`. - `"summary_text"` - `type: Literal["reasoning"]` The type of the object. Always `reasoning`. - `"reasoning"` - `content: Optional[List[Content]]` Reasoning text content. - `text: str` The reasoning text from the model. - `type: Literal["reasoning_text"]` The type of the reasoning text. Always `reasoning_text`. - `"reasoning_text"` - `encrypted_content: Optional[str]` The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. When streaming, use the completed reasoning item and its `encrypted_content` from the `response.output_item.done` event in subsequent requests. The `encrypted_content` in `response.output_item.added` may be incomplete. This is especially important when `store` is `false` or when using Zero Data Retention. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ResponseCompactionItemParam: …` A compaction item generated by the [`v1/responses/compact` API](/api/reference/resources/responses/methods/compact). - `encrypted_content: str` The encrypted content of the compaction summary. - `type: Literal["compaction"]` The type of the item. Always `compaction`. - `"compaction"` - `id: Optional[str]` The ID of the compaction item. - `class ImageGenerationCall: …` An image generation request made by the model. - `id: str` The unique ID of the image generation call. - `result: Optional[str]` The generated image encoded in base64. - `status: Literal["in_progress", "completed", "generating", "failed"]` The status of the image generation call. - `"in_progress"` - `"completed"` - `"generating"` - `"failed"` - `type: Literal["image_generation_call"]` The type of the image generation call. Always `image_generation_call`. - `"image_generation_call"` - `action: Optional[Literal["generate", "edit", "auto"]]` The action used for image generation. - `"generate"` - `"edit"` - `"auto"` - `background: Optional[Literal["transparent", "opaque", "auto"]]` The background setting used for generation. - `"transparent"` - `"opaque"` - `"auto"` - `output_format: Optional[Literal["png", "webp", "jpeg"]]` The output format used for generation. - `"png"` - `"webp"` - `"jpeg"` - `quality: Optional[Literal["low", "medium", "high", 3 more]]` The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `"auto"` - `revised_prompt: Optional[str]` The prompt that was used after any model prompt rewriting. - `size: Optional[Union[str, Literal["1024x1024", "1024x1536", "1536x1024"], null]]` The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`. - `str` - `Literal["1024x1024", "1024x1536", "1536x1024"]` The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`. - `"1024x1024"` - `"1024x1536"` - `"1536x1024"` - `class ResponseCodeInterpreterToolCall: …` A tool call to run code. - `id: str` The unique ID of the code interpreter tool call. - `code: Optional[str]` The code to run, or null if not available. - `container_id: str` The ID of the container used to run the code. - `outputs: Optional[List[Output]]` The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - `class OutputLogs: …` The logs output from the code interpreter. - `logs: str` The logs output from the code interpreter. - `type: Literal["logs"]` The type of the output. Always `logs`. - `"logs"` - `class OutputImage: …` The image output from the code interpreter. - `type: Literal["image"]` The type of the output. Always `image`. - `"image"` - `url: str` The URL of the image output from the code interpreter. - `status: Literal["in_progress", "completed", "incomplete", 2 more]` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` - `"completed"` - `"incomplete"` - `"interpreting"` - `"failed"` - `type: Literal["code_interpreter_call"]` The type of the code interpreter tool call. Always `code_interpreter_call`. - `"code_interpreter_call"` - `class LocalShellCall: …` A tool call to run a command on the local shell. - `id: str` The unique ID of the local shell call. - `action: LocalShellCallAction` Execute a shell command on the server. - `command: List[str]` The command to run. - `env: Dict[str, str]` Environment variables to set for the command. - `type: Literal["exec"]` The type of the local shell action. Always `exec`. - `"exec"` - `timeout_ms: Optional[int]` Optional timeout in milliseconds for the command. - `user: Optional[str]` Optional user to run the command as. - `working_directory: Optional[str]` Optional working directory to run the command in. - `call_id: str` The unique ID of the local shell tool call generated by the model. - `status: Literal["in_progress", "completed", "incomplete"]` The status of the local shell call. - `"in_progress"` - `"completed"` - `"incomplete"` - `type: Literal["local_shell_call"]` The type of the local shell call. Always `local_shell_call`. - `"local_shell_call"` - `class LocalShellCallOutput: …` The output of a local shell tool call. - `id: str` The unique ID of the local shell tool call generated by the model. - `output: str` A JSON string of the output of the local shell tool call. - `type: Literal["local_shell_call_output"]` The type of the local shell tool call output. Always `local_shell_call_output`. - `"local_shell_call_output"` - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ShellCall: …` A tool representing a request to execute one or more shell commands. - `action: ShellCallAction` The shell commands and limits that describe how to run the tool call. - `commands: List[str]` Ordered shell commands for the execution environment to run. - `max_output_length: Optional[int]` Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Optional[int]` Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: str` The unique ID of the shell tool call generated by the model. - `type: Literal["shell_call"]` The type of the item. Always `shell_call`. - `"shell_call"` - `id: Optional[str]` The unique ID of the shell tool call. Populated when this item is returned via API. - `caller: Optional[ShellCallCaller]` The execution context that produced this tool call. - `class ShellCallCallerDirect: …` - `type: Literal["direct"]` The caller type. Always `direct`. - `"direct"` - `class ShellCallCallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` The caller type. Always `program`. - `"program"` - `environment: Optional[ShellCallEnvironment]` The environment to execute the shell commands in. - `class LocalEnvironment: …` - `class ContainerReference: …` - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ShellCallOutput: …` The streamed output items emitted by a shell tool call. - `call_id: str` The unique ID of the shell tool call generated by the model. - `output: List[ResponseFunctionShellCallOutputContent]` Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Outcome` The exit or timeout outcome associated with this shell call. - `class OutcomeTimeout: …` Indicates that the shell call exceeded its configured time limit. - `type: Literal["timeout"]` The outcome type. Always `timeout`. - `"timeout"` - `class OutcomeExit: …` Indicates that the shell commands finished and returned an exit code. - `exit_code: int` The exit code returned by the shell process. - `type: Literal["exit"]` The outcome type. Always `exit`. - `"exit"` - `stderr: str` Captured stderr output for the shell call. - `stdout: str` Captured stdout output for the shell call. - `type: Literal["shell_call_output"]` The type of the item. Always `shell_call_output`. - `"shell_call_output"` - `id: Optional[str]` The unique ID of the shell tool call output. Populated when this item is returned via API. - `caller: Optional[ShellCallOutputCaller]` The execution context that produced this tool call. - `class ShellCallOutputCallerDirect: …` - `type: Literal["direct"]` The caller type. Always `direct`. - `"direct"` - `class ShellCallOutputCallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` The caller type. Always `program`. - `"program"` - `max_output_length: Optional[int]` The maximum number of UTF-8 characters captured for this shell call's combined output. - `status: Optional[Literal["in_progress", "completed", "incomplete"]]` The status of the shell call output. - `"in_progress"` - `"completed"` - `"incomplete"` - `class ApplyPatchCall: …` A tool call representing a request to create, delete, or update files using diff patches. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - `operation: ApplyPatchCallOperation` The specific create, delete, or update instruction for the apply_patch tool call. - `class ApplyPatchCallOperationCreateFile: …` Instruction for creating a new file via the apply_patch tool. - `diff: str` Unified diff content to apply when creating the file. - `path: str` Path of the file to create relative to the workspace root. - `type: Literal["create_file"]` The operation type. Always `create_file`. - `"create_file"` - `class ApplyPatchCallOperationDeleteFile: …` Instruction for deleting an existing file via the apply_patch tool. - `path: str` Path of the file to delete relative to the workspace root. - `type: Literal["delete_file"]` The operation type. Always `delete_file`. - `"delete_file"` - `class ApplyPatchCallOperationUpdateFile: …` Instruction for updating an existing file via the apply_patch tool. - `diff: str` Unified diff content to apply to the existing file. - `path: str` Path of the file to update relative to the workspace root. - `type: Literal["update_file"]` The operation type. Always `update_file`. - `"update_file"` - `status: Literal["in_progress", "completed"]` The status of the apply patch tool call. One of `in_progress` or `completed`. - `"in_progress"` - `"completed"` - `type: Literal["apply_patch_call"]` The type of the item. Always `apply_patch_call`. - `"apply_patch_call"` - `id: Optional[str]` The unique ID of the apply patch tool call. Populated when this item is returned via API. - `caller: Optional[ApplyPatchCallCaller]` The execution context that produced this tool call. - `class ApplyPatchCallCallerDirect: …` - `type: Literal["direct"]` The caller type. Always `direct`. - `"direct"` - `class ApplyPatchCallCallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` The caller type. Always `program`. - `"program"` - `class ApplyPatchCallOutput: …` The streamed output emitted by an apply patch tool call. - `call_id: str` The unique ID of the apply patch tool call generated by the model. - `status: Literal["completed", "failed"]` The status of the apply patch tool call output. One of `completed` or `failed`. - `"completed"` - `"failed"` - `type: Literal["apply_patch_call_output"]` The type of the item. Always `apply_patch_call_output`. - `"apply_patch_call_output"` - `id: Optional[str]` The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `caller: Optional[ApplyPatchCallOutputCaller]` The execution context that produced this tool call. - `class ApplyPatchCallOutputCallerDirect: …` - `type: Literal["direct"]` The caller type. Always `direct`. - `"direct"` - `class ApplyPatchCallOutputCallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` The caller type. Always `program`. - `"program"` - `output: Optional[str]` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `class McpListTools: …` A list of tools available on an MCP server. - `id: str` The unique ID of the list. - `server_label: str` The label of the MCP server. - `tools: List[McpListToolsTool]` The tools available on the server. - `input_schema: object` The JSON schema describing the tool's input. - `name: str` The name of the tool. - `annotations: Optional[object]` Additional annotations about the tool. - `description: Optional[str]` The description of the tool. - `type: Literal["mcp_list_tools"]` The type of the item. Always `mcp_list_tools`. - `"mcp_list_tools"` - `error: Optional[str]` Error message if the server could not list tools. - `class McpApprovalRequest: …` A request for human approval of a tool invocation. - `id: str` The unique ID of the approval request. - `arguments: str` A JSON string of arguments for the tool. - `name: str` The name of the tool to run. - `server_label: str` The label of the MCP server making the request. - `type: Literal["mcp_approval_request"]` The type of the item. Always `mcp_approval_request`. - `"mcp_approval_request"` - `class McpApprovalResponse: …` A response to an MCP approval request. - `approval_request_id: str` The ID of the approval request being answered. - `approve: bool` Whether the request was approved. - `type: Literal["mcp_approval_response"]` The type of the item. Always `mcp_approval_response`. - `"mcp_approval_response"` - `id: Optional[str]` The unique ID of the approval response - `reason: Optional[str]` Optional reason for the decision. - `class McpCall: …` An invocation of a tool on an MCP server. - `id: str` The unique ID of the tool call. - `arguments: str` A JSON string of the arguments passed to the tool. - `name: str` The name of the tool that was run. - `server_label: str` The label of the MCP server running the tool. - `type: Literal["mcp_call"]` The type of the item. Always `mcp_call`. - `"mcp_call"` - `approval_request_id: Optional[str]` Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - `error: Optional[McpToolCallError]` The error from the tool call, if any. - `class McpProtocolError: …` - `code: int` - `message: str` - `type: Literal["mcp_protocol_error"]` - `"mcp_protocol_error"` - `class McpToolExecutionError: …` - `content: object` - `type: Literal["mcp_tool_execution_error"]` - `"mcp_tool_execution_error"` - `class HTTPError: …` - `code: int` - `message: str` - `type: Literal["http_error"]` - `"http_error"` - `output: Optional[str]` The output from the tool call. - `status: Optional[Literal["in_progress", "completed", "incomplete", 2 more]]` The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` - `"completed"` - `"incomplete"` - `"calling"` - `"failed"` - `class ResponseCustomToolCallOutput: …` The output of a custom tool call from your code, being sent back to the model. - `call_id: str` The call ID, used to map this custom tool call output to a custom tool call. - `output: Union[str, List[OutputOutputContentList]]` The output from the custom tool call generated by your code. Can be a string or an list of output content. - `str` A string of the output of the custom tool call. - `List[OutputOutputContentList]` Text, image, or file output of the custom tool call. - `class ResponseInputText: …` A text input to the model. - `class ResponseInputImage: …` An image input to the model. Learn about [image inputs](/api/docs/guides/images-vision). - `class ResponseInputFile: …` A file input to the model. - `type: Literal["custom_tool_call_output"]` The type of the custom tool call output. Always `custom_tool_call_output`. - `"custom_tool_call_output"` - `id: Optional[str]` The unique ID of the custom tool call output in the OpenAI platform. - `caller: Optional[Caller]` The execution context that produced this tool call. - `class CallerDirect: …` - `type: Literal["direct"]` The caller type. Always `direct`. - `"direct"` - `class CallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` The caller type. Always `program`. - `"program"` - `class ResponseCustomToolCall: …` A call to a custom tool created by the model. - `call_id: str` An identifier used to map this custom tool call to a tool call output. - `input: str` The input for the custom tool call generated by the model. - `name: str` The name of the custom tool being called. - `type: Literal["custom_tool_call"]` The type of the custom tool call. Always `custom_tool_call`. - `"custom_tool_call"` - `id: Optional[str]` The unique ID of the custom tool call in the OpenAI platform. - `async_: Optional[bool]` Whether the custom tool call runs asynchronously. - `caller: Optional[Caller]` The execution context that produced this tool call. - `class CallerDirect: …` - `type: Literal["direct"]` - `"direct"` - `class CallerProgram: …` - `caller_id: str` The call ID of the program item that produced this tool call. - `type: Literal["program"]` - `"program"` - `namespace: Optional[str]` The namespace of the custom tool being called. - `class CompactionTrigger: …` Compacts the current context. Must be the final input item. - `type: Literal["compaction_trigger"]` The type of the item. Always `compaction_trigger`. - `"compaction_trigger"` - `class ItemReference: …` An internal identifier for an item to reference. - `id: str` The ID of the item to reference. - `type: Optional[Literal["item_reference"]]` The type of item to reference. Always `item_reference`. - `"item_reference"` - `class Program: …` - `id: str` The unique ID of this program item. - `call_id: str` The stable call ID of the program item. - `code: str` The JavaScript source executed by programmatic tool calling. - `fingerprint: str` Opaque program replay fingerprint that must be round-tripped. - `type: Literal["program"]` The item type. Always `program`. - `"program"` - `class ProgramOutput: …` - `id: str` The unique ID of this program output item. - `call_id: str` The call ID of the program item. - `result: str` The result produced by the program item. - `status: Literal["completed", "incomplete"]` The terminal status of the program output. - `"completed"` - `"incomplete"` - `type: Literal["program_output"]` The item type. Always `program_output`. - `"program_output"` - `type: Literal["response.item.create"]` The Live client event type. Always `response.item.create`. - `"response.item.create"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class ResponseCreateEvent: …` Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation. - `type: Literal["response.create"]` The Live client event type. Always `response.create`. - `"response.create"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - `class SessionCloseEvent: …` Request that the Live session close. The terminal `session.closed` event contains the close reason and final usage. - `type: Literal["session.close"]` The Live client event type. Always `session.close`. - `"session.close"` - `event_id: Optional[str]` Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. ### Connect Server Event - `ConnectServerEvent` Server events received by an attached Live sideband WebSocket. Audio deltas are delivered over the primary connection. - `class SessionStartedEvent: …` Returned when a Live session has started. Contains the resolved session configuration, including server defaults. - `event_id: str` The unique ID of the Live server event. - `session: SessionResource` The resolved Live session configuration and server-assigned session metadata. - `id: str` The unique ID of the Live session. Use this ID for sideband connections, forking, and recording download. - `expires_at: int` The Unix timestamp, in seconds, at which the Live session expires. - `model: Union[str, Literal["gpt-live-1"]]` The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter. - `str` - `Literal["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"` - `status: Literal["active"]` The status of the session snapshot. Always `active`, including the final snapshot in session.closed; use the event type to determine that the session has closed. - `"active"` - `audio: Optional[Audio]` Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - `format: Optional[AudioFormat]` Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - `class AudioPCM: …` Raw, mono 16-bit little-endian PCM audio for a Live WebSocket connection. - `rate: Literal[16000, 24000]` Audio sample rate in hertz. Live WebSocket PCM audio supports 16000 or 24000 Hz. - `16000` - `24000` - `type: Literal["audio/pcm"]` The audio encoding. Always `audio/pcm`. - `"audio/pcm"` - `class AudioPCMU: …` Raw, mono G.711 μ-law audio for a Live WebSocket connection. - `rate: int` Audio sample rate in hertz. G.711 audio uses 8000 Hz. - `type: Literal["audio/pcmu"]` The audio encoding. Always `audio/pcmu`. - `"audio/pcmu"` - `class AudioPCMA: …` Raw, mono G.711 A-law audio for a Live WebSocket connection. - `rate: int` Audio sample rate in hertz. G.711 audio uses 8000 Hz. - `type: Literal["audio/pcma"]` The audio encoding. Always `audio/pcma`. - `"audio/pcma"` - `output: Optional[AudioOutput]` The voice used for speech generated by the Live model. - `voice: Optional[AudioOutputVoice]` 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. - `str` - `Literal["alloy", "ash", "ballad", 19 more]` - `"alloy"` - `"ash"` - `"ballad"` - `"beacon"` - `"bossa"` - `"cedar"` - `"cinder"` - `"coral"` - `"delta"` - `"echo"` - `"gleam"` - `"marin"` - `"meridian"` - `"quartz"` - `"ripple"` - `"sage"` - `"shimmer"` - `"stone"` - `"tempo"` - `"verse"` - `"vesper"` - `"willow"` - `class CustomVoice: …` - `id: str` - `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[Union[Literal["all"], List[str], null]]` 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. - `Literal["all"]` - `"all"` - `List[str]` - `allowed_server_events: Optional[Union[Literal["all"], List[ServerEventSelector], null]]` 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. - `Literal["all"]` - `"all"` - `List[ServerEventSelector]` - `type: str` The outer Live server event type. Use 'response.event' for Responses events. - `response_event: Optional[str]` The nested Responses event type. Required when type is 'response.event'; forbidden for other event types. - `delegation: Optional[Delegation]` Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. - `class ClientDelegation: …` Delegate tasks to your application. The Live session emits delegation events that your backend handles. - `type: Literal["client"]` The delegation owner. Always `client` for tasks handled by your application. - `"client"` - `class DelegationResponses: …` 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: str` The model used for server-owned Responses delegations. - `instructions: Optional[str]` 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[int]` Maximum number of output tokens for each delegated response. - `parallel_tool_calls: Optional[bool]` Whether the delegated Responses model may request multiple tool calls in a single response. - `reasoning: Optional[Reasoning]` Reasoning settings passed to each delegated Responses request. - `effort: Optional[Literal["none", "minimal", "low", 3 more]]` 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[Literal["concise", "detailed", "auto"]]` The reasoning summary to request from the delegated Responses model, when supported. - `"concise"` - `"detailed"` - `"auto"` - `service_tier: Optional[Literal["auto", "default", "fast_tier_temp_pilot", 3 more]]` Service tier for delegated Responses requests. - `"auto"` - `"default"` - `"fast_tier_temp_pilot"` - `"flex"` - `"priority"` - `"ultrafast"` - `text: Optional[Text]` Text generation settings passed to each delegated Responses request. - `verbosity: Optional[Literal["low", "medium", "high"]]` 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[ToolChoice]` Controls which tool the Responses backend uses when handling a task delegated by the Live model. - `Literal["auto", "none", "required"]` - `"auto"` - `"none"` - `"required"` - `class ToolChoiceLiveFunctionToolChoiceParam: …` - `name: str` - `type: Literal["function"]` - `"function"` - `class ToolChoiceLiveMCPToolChoiceParam: …` - `name: str` - `server_label: str` - `type: Literal["mcp"]` - `"mcp"` - `tools: Optional[List[Tool]]` Tools available to the Responses backend while it handles tasks delegated by the Live model. - `class FunctionTool: …` A function tool available to the Responses backend when the Live model delegates a task. - `name: str` The name the delegated Responses model uses when calling this function. - `type: Literal["function"]` The tool type. Always `function`. - `"function"` - `description: Optional[str]` What the function does and when the delegated Responses model should call it. - `parameters: Optional[Dict[str, object]]` A JSON Schema object describing the arguments accepted by the function. - `strict: Optional[bool]` Whether the delegated Responses model must follow the function’s parameter schema exactly. - `class ToolWebSearch: …` A web search tool available to the Live session’s Responses backend. - `type: Literal["web_search"]` The tool type. Always `web_search`. - `"web_search"` - `type: Literal["responses"]` The delegation owner. Always `responses` for tasks handled by the Responses API. - `"responses"` - `input: Optional[List[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. - `class Developer: …` A developer message included in the initial text history of a Live session. - `content: List[DeveloperContent]` The message content. Supply exactly one text part for the initial Live conversation history. - `text: str` The message text to include in the Live session’s initial conversation history. - `type: Optional[Literal["input_text"]]` The text content type. Always `input_text`. - `"input_text"` - `role: Literal["developer"]` The author of this history message. Always `developer`. - `"developer"` - `id: Optional[str]` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status: Optional[Literal["incomplete", "completed"]]` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type: Optional[Literal["message"]]` The history item type. Always `message`. - `"message"` - `class User: …` A user message included in the initial text history of a Live session. - `content: List[UserContent]` The message content. Supply exactly one text part for the initial Live conversation history. - `text: str` The message text to include in the Live session’s initial conversation history. - `type: Optional[Literal["input_text"]]` The text content type. Always `input_text`. - `"input_text"` - `role: Literal["user"]` The author of this history message. Always `user`. - `"user"` - `id: Optional[str]` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status: Optional[Literal["incomplete", "completed"]]` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type: Optional[Literal["message"]]` The history item type. Always `message`. - `"message"` - `class Assistant: …` An assistant message included in the initial text history of a Live session. - `content: List[AssistantContent]` The message content. Supply exactly one text part for the initial Live conversation history. - `class AssistantContentText: …` Assistant text supplied as conversation history when starting a Live session. - `text: str` The message text to include in the Live session’s initial conversation history. - `type: Optional[Literal["text"]]` The text content type. Always `text`. - `"text"` - `class AssistantContentOutputText: …` Assistant output text supplied as conversation history when starting a Live session. - `text: str` The message text to include in the Live session’s initial conversation history. - `type: Literal["output_text"]` The text content type. Always `output_text`. - `"output_text"` - `role: Literal["assistant"]` The author of this history message. Always `assistant`. - `"assistant"` - `id: Optional[str]` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status: Optional[Literal["incomplete", "completed"]]` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type: Optional[Literal["message"]]` The history item type. Always `message`. - `"message"` - `instructions: Optional[str]` 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[bool]` Whether to store the session for later forking and recording download. Defaults to false for new sessions. - `type: Literal["session.started"]` The event type, always `session.started`. - `"session.started"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class SessionUpdatedEvent: …` Returned when a Live session update is accepted. Contains the resolved session configuration after the update. - `event_id: str` The unique ID of the Live server event. - `session: SessionResource` The resolved Live session configuration and server-assigned session metadata. - `type: Literal["session.updated"]` The event type, always `session.updated`. - `"session.updated"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class InputAudioMutedEvent: …` Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues. - `event_id: str` The unique ID of the Live server event. - `type: Literal["session.input_audio.muted"]` The event type, always `session.input_audio.muted`. - `"session.input_audio.muted"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class InputAudioUnmutedEvent: …` Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again. - `event_id: str` The unique ID of the Live server event. - `type: Literal["session.input_audio.unmuted"]` The event type, always `session.input_audio.unmuted`. - `"session.input_audio.unmuted"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class InstructionsAppendedEvent: …` Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them. - `end_ms: int` The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - `event_id: str` The unique ID of the Live server event. - `start_ms: int` The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - `type: Literal["session.instructions.appended"]` The event type, always `session.instructions.appended`. - `"session.instructions.appended"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class ThinkingAppendedEvent: …` Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output. - `end_ms: int` The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - `event_id: str` The unique ID of the Live server event. - `start_ms: int` The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - `type: Literal["session.thinking.appended"]` The event type, always `session.thinking.appended`. - `"session.thinking.appended"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class CommentaryAppendedEvent: …` Returned when a session.commentary.append command is accepted into the Live session timeline. Acknowledges the added commentary without guaranteeing exact wording or completed audio playback. - `end_ms: int` The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - `event_id: str` The unique ID of the Live server event. - `start_ms: int` The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - `type: Literal["session.commentary.appended"]` The event type, always `session.commentary.appended`. - `"session.commentary.appended"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class InputTranscriptDeltaEvent: …` A transcript fragment for user input audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. - `delta: str` The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. - `end_ms: int` The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - `event_id: str` The unique ID of the Live server event. - `start_ms: int` The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - `type: Literal["session.input_transcript.delta"]` The event type, always `session.input_transcript.delta`. - `"session.input_transcript.delta"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class OutputTranscriptDeltaEvent: …` A transcript fragment for assistant output audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. - `delta: str` The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. - `end_ms: int` The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - `event_id: str` The unique ID of the Live server event. - `start_ms: int` The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - `type: Literal["session.output_transcript.delta"]` The event type, always `session.output_transcript.delta`. - `"session.output_transcript.delta"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class DelegationCreatedEvent: …` Returned when the Live model delegates work to your application or a Responses backend. Contains delegation metadata and the position on the session timeline where the work was delegated. - `delegation: Delegation` The delegated work identifier and destination. This object contains metadata, not the task text. - `id: str` The unique ID of the delegation. Use this as delegation_id when replying to client-owned work or correlating Responses events. - `target: Union[Literal["client", "responses"]]` Where the Live model delegated the work: `client` for your application, or `responses` for the configured Responses backend. - `Literal["client", "responses"]` Where the Live model delegated the work: `client` for your application, or `responses` for the configured Responses backend. - `"client"` - `"responses"` - `type: Literal["delegation"]` The object type, always `delegation`. - `"delegation"` - `response_id: Optional[str]` The ID of the Responses API response associated with a Responses delegation. Omitted for client delegations. - `event_id: str` The unique ID of the Live server event. - `offset_ms: int` The position on the Live session timeline where the delegation was created, in milliseconds from the beginning of the session. - `type: Literal["session.delegation.created"]` The event type, always `session.delegation.created`. - `"session.delegation.created"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class ResponseEvent: …` A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation. - `event: Dict[str, object]` The nested Responses streaming event. Dispatch on its type field. Response lifecycle snapshots omit input and clear instructions, tools, and output to keep messages small; consume granular output events for the generated content. - `event_id: str` The unique ID of the Live server event. - `type: Literal["response.event"]` The event type, always `response.event`. - `"response.event"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `delegation_id: Optional[str]` The Live delegation associated with the nested Responses event. May be null or omitted when the event cannot be correlated with a delegation. - `class SessionUsageUpdatedEvent: …` Reports cumulative Live audio usage and, when available, the most recent context-window usage. Delegated Responses token usage is reported separately in response.event events. - `event_id: str` The unique ID of the Live server event. - `type: Literal["session.usage.updated"]` The event type, always `session.usage.updated`. - `"session.usage.updated"` - `usage: SessionUsage` The cumulative Live audio usage so far. - `seconds: float` The cumulative Live audio duration in seconds. Do not sum this value across usage events. - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `context_window: Optional[ContextWindow]` The latest measured Live context-window usage. Omitted when the context limit is unknown. - `usage_ratio: float` The latest active context token count divided by the Live model context limit. Can decrease after compaction and may lag between measured audio frames. - `class SessionClosedEvent: …` Returned after the Live session finishes finalizing, with the close reason, final session snapshot, and cumulative audio usage. A connection closing without this event does not confirm successful finalization. - `event_id: str` The unique ID of the Live server event. - `reason: Union[Literal["close_requested", "expired", "content", 2 more]]` Why the Live session ended: `close_requested` for an application close or hangup request, `expired` for the session duration limit, `content` for a safety filter, `remote_hangup` for a graceful remote disconnect, or `connection_lost` for an unexpected primary or upstream disconnection. - `Literal["close_requested", "expired", "content", 2 more]` Why the Live session ended: `close_requested` for an application close or hangup request, `expired` for the session duration limit, `content` for a safety filter, `remote_hangup` for a graceful remote disconnect, or `connection_lost` for an unexpected primary or upstream disconnection. - `"close_requested"` - `"expired"` - `"content"` - `"remote_hangup"` - `"connection_lost"` - `session: SessionResource` The resolved Live session configuration and server-assigned session metadata. - `type: Literal["session.closed"]` The event type, always `session.closed`. - `"session.closed"` - `usage: SessionUsage` The final cumulative Live audio usage after session finalization. - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class ErrorEvent: …` Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error. - `error: Error` Details of the Live error and the client command that caused it, when known. - `code: str` A machine-readable code identifying the Live error, such as `unknown_parameter`. - `message: str` A human-readable explanation of the Live error. - `type: str` The category of error, such as `invalid_request_error` for an invalid Live client command. - `client_event_id: Optional[str]` The event_id of the client command that caused the error, when supplied. - `param: Optional[str]` The parameter that caused the error, when applicable, such as `session.voice`. - `event_id: str` The unique ID of the Live server event. - `type: Literal["error"]` The event type, always `error`. - `"error"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied. - `class InfoEvent: …` An informational notice about the Live session, such as the event permissions applied to a frontend data channel. - `code: str` A machine-readable code for the notice, such as `data_channel_permissions`. - `event_id: str` The unique ID of the Live server event. - `message: str` A human-readable explanation of the Live session notice. - `type: Literal["info"]` The event type, always `info`. - `"info"` - `client_event_id: Optional[str]` The event_id of the client command associated with this server event, when supplied.