Sideband
Connect
Models
SidebandClientEvent = SessionUpdateEvent { session, type, event_id } or InputAudioMuteEvent { type, event_id } or InputAudioUnmuteEvent { type, event_id } or 10 moreClient events accepted by an attached Live sideband WebSocket. The session has already started. Send input audio over the primary connection.
Client events accepted by an attached Live sideband WebSocket. The session has already started. Send input audio over the primary connection.
SessionUpdateEvent object { session, type, event_id } Update the delegation settings or transcript triggers of an active Live session. The server acknowledges accepted changes with session.updated.
Update the delegation settings or transcript triggers of an active Live session. The server acknowledges accepted changes with session.updated.
InputAudioMuteEvent object { type, event_id } Mute audio input to the Live model without closing the session. The server acknowledges with session.input_audio.muted.
Mute audio input to the Live model without closing the session. The server acknowledges with session.input_audio.muted.
InputAudioUnmuteEvent object { type, event_id } Resume audio input to a Live model after muting it. The server acknowledges with session.input_audio.unmuted. An active audio fixture still pauses inference until playback finishes.
Resume audio input to a Live model after muting it. The server acknowledges with session.input_audio.unmuted. An active audio fixture still pauses inference until playback finishes.
OutputAudioFixturePlayEvent object { audio, type, event_id } Play one complete audio fixture through the session output. Send this event over the primary WebSocket or a server sideband. Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active. fixture.playing acknowledges acceptance and fixture.played reports server mixer drain. These notifications are not exact transport-media boundaries. Input arriving during playback is dropped and not replayed.
Play one complete audio fixture through the session output. Send this event over the primary WebSocket or a server sideband. Audio must be raw mono PCM16 little-endian at 24 kHz, regardless of the session audio format, and at most 30 seconds. The entire payload is validated before model speech is interrupted and input is muted. Only one fixture can be active. fixture.playing acknowledges acceptance and fixture.played reports server mixer drain. These notifications are not exact transport-media boundaries. Input arriving during playback is dropped and not replayed.
InstructionsAppendEvent object { content, delegation_id, type, event_id } Append developer instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. Rejected while an audio fixture is active. These instructions remain in conversation history through compaction and are included in future backend delegations. For external audio, describe content already delivered so the assistant does not repeat it.
Append developer instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. Rejected while an audio fixture is active. These instructions remain in conversation history through compaction and are included in future backend delegations. For external audio, describe content already delivered so the assistant does not repeat it.
Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts.
ThinkingAppendEvent object { content, delegation_id, type, event_id } Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. Rejected while an audio fixture is active.
Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. Rejected while an audio fixture is active.
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.
CommentaryAppendEvent object { content, delegation_id, type, event_id } Provide context the Live model can communicate to the user, optionally for an existing client delegation. Rejected while an audio fixture is active.
Provide context the Live model can communicate to the user, optionally for an existing client delegation. Rejected while an audio fixture is active.
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.
DecisionCreateEvent object { event_id, type } Evaluate the configured questions using the current conversation and Decision inputs. Reusing an event_id is rejected for the lifetime of the session.
Evaluate the configured questions using the current conversation and Decision inputs. Reusing an event_id is rejected for the lifetime of the session.
DecisionItemCreateEvent object { item, type, event_id } Append an input item for future decisions without starting an evaluation or changing Live voice context.
Append an input item for future decisions without starting an evaluation or changing Live voice context.
item: object { content, role, id, type }
content: string or array of InputText { text, type } or InputImage { image_url, type, detail } The text input to the model.
The text input to the model.
DecisionItemDeleteEvent object { item_id, type, event_id } Delete an input item from future decisions without starting an evaluation or changing Live voice context.
Delete an input item from future decisions without starting an evaluation or changing Live voice context.
ResponseItemCreateEvent object { item, type, event_id } Add an input item to the Live session’s Responses backend. Requires Responses delegation; use response.create to request a response.
Add an input item to the Live session’s Responses backend. Requires Responses delegation; use response.create to request a response.
item: EasyInputMessage { content, role, phase, type } or Message { content, role, status, type } or ResponseOutputMessage { id, content, role, 3 more } or 30 moreAn input item to append to the Responses backend conversation, such as a user message or a function tool result.
An input item to append to the Responses backend conversation, such as a user message or a function tool result.
EasyInputMessage object { content, role, phase, type } 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.
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.
Text, image, or audio input to the model, used to generate a response.
Can also contain previous assistant responses.
Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.
A list of one or many input items to the model, containing different content
types.
A list of one or many input items to the model, containing different content types.
ResponseInputImage object { detail, type, file_id, 2 more } An image input to the model. Learn about image inputs.
An image input to the model. Learn about image inputs.
ResponseInputFile object { type, detail, file_data, 4 more } A file input to the model.
A file input to the model.
detail: optional "auto" or "low" or "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.
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.
role: "user" or "assistant" or "system" or "developer"The role of the message input. One of user, assistant, system, or
developer.
The role of the message input. One of user, assistant, system, or
developer.
phase: optional "commentary" or "final_answer" or nullLabels 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.
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.
Message object { content, role, status, type } 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.
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.
role: "user" or "system" or "developer"The role of the message input. One of user, system, or developer.
The role of the message input. One of user, system, or developer.
ResponseOutputMessage object { id, content, role, 3 more } An output message from the model.
An output message from the model.
content: array of ResponseOutputText { annotations, logprobs, text, type } or ResponseOutputRefusal { refusal, type } The content of the output message.
The content of the output message.
ResponseOutputText object { annotations, logprobs, text, type } A text output from the model.
A text output from the model.
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type } The annotations of the text output.
The annotations of the text output.
URLCitation object { end_index, start_index, title, 2 more } A citation for a web resource used to generate a model response.
A citation for a web resource used to generate a model response.
status: "in_progress" or "completed" or "incomplete"The status of the message input. One of in_progress, completed, or
incomplete. Populated when input items are returned via API.
The status of the message input. One of in_progress, completed, or
incomplete. Populated when input items are returned via API.
phase: optional "commentary" or "final_answer" or nullLabels 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.
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.
FileSearchCall object { id, queries, status, 2 more } The results of a file search tool call. See the
file search guide for more information.
The results of a file search tool call. See the file search guide for more information.
status: "in_progress" or "searching" or "completed" or 2 moreThe status of the file search tool call. One of in_progress,
searching, incomplete or failed,
The status of the file search tool call. One of in_progress,
searching, incomplete or failed,
results: optional array of object { attributes, file_id, filename, 2 more } or nullThe results of the file search tool call.
The results of the file search tool call.
attributes: optional map[string or number or boolean] or nullSet 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.
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.
ComputerCall object { id, call_id, pending_safety_checks, 4 more } A tool call to a computer use tool. See the
computer use guide for more information.
A tool call to a computer use tool. See the computer use guide for more information.
pending_safety_checks: array of object { id, code, message } The pending safety checks for the computer call.
The pending safety checks for the computer call.
status: "in_progress" or "completed" or "incomplete"The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.
The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.
ComputerCallOutput object { call_id, output, type, 3 more } The output of a computer tool call.
The output of a computer tool call.
WebSearchCall object { id, status, type, action } The results of a web search tool call. See the
web search guide for more information.
The results of a web search tool call. See the web search guide for more information.
status: "in_progress" or "searching" or "completed" or 2 moreThe status of the web search tool call.
The status of the web search tool call.
action: optional Search { type, queries, query, sources } or OpenPage { type, url } or FindInPage { pattern, type, url } 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).
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).
FunctionCall object { arguments, call_id, name, 6 more } A tool call to run a function. See the
function calling guide for more information.
A tool call to run a function. See the function calling guide for more information.
FunctionCallOutput object { output, type, id, 5 more } The output of a function tool call.
The output of a function tool call.
output: string or array of ResponseInputTextContent { text, type, prompt_cache_breakpoint } or ResponseInputImageContent { type, detail, file_id, 2 more } or ResponseInputFileContent { type, detail, file_data, 4 more } Text, image, or file output of the function tool call.
Text, image, or file output of the function tool call.
array of ResponseInputTextContent { text, type, prompt_cache_breakpoint } or ResponseInputImageContent { type, detail, file_id, 2 more } or ResponseInputFileContent { type, detail, file_data, 4 more } An array of content outputs (text, image, file) for the function tool call.
An array of content outputs (text, image, file) for the function tool call.
ResponseInputTextContent object { text, type, prompt_cache_breakpoint } A text input to the model.
A text input to the model.
ResponseInputImageContent object { type, detail, file_id, 2 more } An image input to the model. Learn about image inputs
An image input to the model. Learn about image inputs
The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.
The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
ResponseInputFileContent object { type, detail, file_data, 4 more } A file input to the model.
A file input to the model.
detail: optional "auto" or "low" or "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.
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.
The base64-encoded data of the file to be sent to the model.
The unique ID of the function tool call output. Populated when this item is returned via API.
The unique ID of the function tool call generated by the model.
caller: optional Direct { type } or Program { caller_id, type } or nullThe execution context that produced this tool call.
The execution context that produced this tool call.
ToolSearchCall object { arguments, type, id, 3 more }
ToolSearchOutput object { tools, type, id, 3 more }
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 moreThe loaded tool definitions returned by the tool search output.
The loaded tool definitions returned by the tool search output.
Function object { name, parameters, strict, 6 more } Defines a function in your own code the model can choose to call. Learn more about function calling.
Defines a function in your own code the model can choose to call. Learn more about function calling.
FileSearch object { type, vector_store_ids, filters, 2 more } A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A filter to apply.
A filter to apply.
ComparisonFilter object { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
CompoundFilter object { filters, type } Combine multiple filters using and or or.
Combine multiple filters using and or or.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
ComparisonFilter object { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options: optional object { hybrid_search, ranker, score_threshold } Ranking options for search.
Ranking options for search.
Computer object { type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
ComputerUsePreview object { display_height, display_width, environment, type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
WebSearch object { type, external_web_access, filters, 2 more } Search the Internet for sources related to the prompt. Learn more about the
web search tool.
Search the Internet for sources related to the prompt. Learn more about the web search tool.
type: "web_search" or "web_search_2025_08_26"The type of the web search tool. One of web_search or web_search_2025_08_26.
The type of the web search tool. One of web_search or web_search_2025_08_26.
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.
search_context_size: optional "low" or "medium" or "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.
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.
user_location: optional object { city, country, region, 2 more } or nullThe approximate location of the user. If omitted or null, defaults to the
United States. To avoid this fallback, pass {"type": "approximate"} without
location fields. To localize results, provide the relevant location fields.
The approximate location of the user. If omitted or null, defaults to the
United States. To avoid this fallback, pass {"type": "approximate"} without
location fields. To localize results, provide the relevant location fields.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
Mcp object { server_label, type, allowed_callers, 9 more } Give the model access to additional tools via remote Model Context Protocol
(MCP) servers. Learn more about MCP.
Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or nullList of allowed tool names or a filter object.
List of allowed tool names or a filter object.
McpToolFilter object { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
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 "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 moreDeprecated.
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.
This field is deprecated for models released after September 1, 2026.
Use server_url to connect to a remote MCP server, or tunnel_id to
connect through a Secure MCP Tunnel.
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
Deprecated.
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.
This field is deprecated for models released after September 1, 2026.
Use server_url to connect to a remote MCP server, or tunnel_id to
connect through a Secure MCP Tunnel.
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
Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or nullSpecify which of the MCP server’s tools require approval.
Specify which of the MCP server’s tools require approval.
McpToolApprovalFilter object { always, never } Specify which of the MCP server’s tools require approval. Can be
always, never, or a filter object associated with tools
that require approval.
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 object { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
never: optional object { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
Optional description of the MCP server, used to provide more context.
CodeInterpreter object { container, type, allowed_callers } A tool that runs Python code to help generate a response to a prompt.
A tool that runs Python code to help generate a response to a prompt.
container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy } 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.
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.
CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy } Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
An optional list of uploaded files to make available to your code.
memory_limit: optional "1g" or "4g" or "16g" or "64g" or nullThe memory limit for the code interpreter container.
The memory limit for the code interpreter container.
network_policy: optional ContainerNetworkPolicyDisabled { type } or ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
ImageGeneration object { type, action, background, 9 more } A tool that generates images using the GPT image models.
A tool that generates images using the GPT image models.
action: optional "generate" or "edit" or "auto"Whether to generate a new image or edit an existing image. Default: auto.
Whether to generate a new image or edit an existing image. Default: auto.
background: optional "transparent" or "opaque" or "auto"Set the background of the generated image. One of transparent, opaque,
or auto. 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.
Default: auto.
Set the background of the generated image. One of transparent, opaque,
or auto. 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.
Default: auto.
input_fidelity: optional "high" or "low" or nullControl how much effort the model will exert to match the style and features, especially facial features, of input images. Supports high and low on gpt-image-1 and gpt-image-1.5; gpt-image-1-mini supports only low. For gpt-image-2, omit this parameter. Defaults to low on supported models.
Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports high and low on gpt-image-1 and gpt-image-1.5; gpt-image-1-mini supports only low. For gpt-image-2, omit this parameter. Defaults to low on supported models.
input_image_mask: optional object { file_id, image_url } Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 6 moreThe 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.
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" or "gpt-image-1-mini" or "gpt-image-1.5" or 6 moreThe 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.
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.
Compression level for the output image. Default: 100.
output_format: optional "png" or "webp" or "jpeg"The output format of the generated image. One of png, webp, or
jpeg. Default: png.
The output format of the generated image. One of png, webp, or
jpeg. Default: png.
Number of partial images to generate in streaming mode, from 0 (default value) to 3.
quality: optional "low" or "medium" or "high" or 3 moreThe 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.
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.
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "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.
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.
"1024x1024" or "1024x1536" or "1536x1024" or "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.
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.
LocalShell object { type } A tool that allows the model to execute shell commands in a local environment.
A tool that allows the model to execute shell commands in a local environment.
Shell object { type, allowed_callers, environment } A tool that allows the model to execute shell commands.
A tool that allows the model to execute shell commands.
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or LocalEnvironment { type, skills } or ContainerReference { container_id, type } or null
ContainerAuto object { type, file_ids, memory_limit, 2 more }
An optional list of uploaded files to make available to your code.
network_policy: optional ContainerNetworkPolicyDisabled { type } or ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
skills: optional array of SkillReference { skill_id, type, version } or InlineSkill { description, name, source, type } An optional list of skills referenced by id or inline data.
An optional list of skills referenced by id or inline data.
Custom object { name, type, allowed_callers, 4 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
ToolSearchOutputNamespaceTool object { description, name, tools, type } Groups function/custom tools under a shared namespace.
Groups function/custom tools under a shared namespace.
tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more } The function/custom tools loaded inside this namespace.
The function/custom tools loaded inside this namespace.
Function object { name, type, allowed_callers, 6 more }
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
Whether this function should be deferred and discovered via tool search.
Custom object { name, type, allowed_callers, 4 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
ToolSearch object { type, description, execution, parameters } Hosted or BYOT tool search configuration for deferred tools.
Hosted or BYOT tool search configuration for deferred tools.
WebSearchPreview object { type, search_content_types, search_context_size, user_location } This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
type: "web_search_preview" or "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.
The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
search_context_size: optional "low" or "medium" or "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.
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.
user_location: optional object { type, city, country, 2 more } or nullThe approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass {"type": "approximate"} without location fields. To localize results, provide the relevant location fields.
The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass {"type": "approximate"} without location fields. To localize results, provide the relevant location fields.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
The unique ID of the tool search call generated by the model.
AdditionalTools object { role, tools, type, id }
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 moreA list of additional tools made available at this item.
A list of additional tools made available at this item.
Function object { name, parameters, strict, 6 more } Defines a function in your own code the model can choose to call. Learn more about function calling.
Defines a function in your own code the model can choose to call. Learn more about function calling.
FileSearch object { type, vector_store_ids, filters, 2 more } A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A filter to apply.
A filter to apply.
ComparisonFilter object { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
CompoundFilter object { filters, type } Combine multiple filters using and or or.
Combine multiple filters using and or or.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
ComparisonFilter object { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options: optional object { hybrid_search, ranker, score_threshold } Ranking options for search.
Ranking options for search.
Computer object { type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
ComputerUsePreview object { display_height, display_width, environment, type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
WebSearch object { type, external_web_access, filters, 2 more } Search the Internet for sources related to the prompt. Learn more about the
web search tool.
Search the Internet for sources related to the prompt. Learn more about the web search tool.
type: "web_search" or "web_search_2025_08_26"The type of the web search tool. One of web_search or web_search_2025_08_26.
The type of the web search tool. One of web_search or web_search_2025_08_26.
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.
search_context_size: optional "low" or "medium" or "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.
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.
user_location: optional object { city, country, region, 2 more } or nullThe approximate location of the user. If omitted or null, defaults to the
United States. To avoid this fallback, pass {"type": "approximate"} without
location fields. To localize results, provide the relevant location fields.
The approximate location of the user. If omitted or null, defaults to the
United States. To avoid this fallback, pass {"type": "approximate"} without
location fields. To localize results, provide the relevant location fields.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
Mcp object { server_label, type, allowed_callers, 9 more } Give the model access to additional tools via remote Model Context Protocol
(MCP) servers. Learn more about MCP.
Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or nullList of allowed tool names or a filter object.
List of allowed tool names or a filter object.
McpToolFilter object { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
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 "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 moreDeprecated.
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.
This field is deprecated for models released after September 1, 2026.
Use server_url to connect to a remote MCP server, or tunnel_id to
connect through a Secure MCP Tunnel.
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
Deprecated.
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.
This field is deprecated for models released after September 1, 2026.
Use server_url to connect to a remote MCP server, or tunnel_id to
connect through a Secure MCP Tunnel.
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
Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or nullSpecify which of the MCP server’s tools require approval.
Specify which of the MCP server’s tools require approval.
McpToolApprovalFilter object { always, never } Specify which of the MCP server’s tools require approval. Can be
always, never, or a filter object associated with tools
that require approval.
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 object { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
never: optional object { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
Optional description of the MCP server, used to provide more context.
CodeInterpreter object { container, type, allowed_callers } A tool that runs Python code to help generate a response to a prompt.
A tool that runs Python code to help generate a response to a prompt.
container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy } 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.
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.
CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy } Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
An optional list of uploaded files to make available to your code.
memory_limit: optional "1g" or "4g" or "16g" or "64g" or nullThe memory limit for the code interpreter container.
The memory limit for the code interpreter container.
network_policy: optional ContainerNetworkPolicyDisabled { type } or ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
ImageGeneration object { type, action, background, 9 more } A tool that generates images using the GPT image models.
A tool that generates images using the GPT image models.
action: optional "generate" or "edit" or "auto"Whether to generate a new image or edit an existing image. Default: auto.
Whether to generate a new image or edit an existing image. Default: auto.
background: optional "transparent" or "opaque" or "auto"Set the background of the generated image. One of transparent, opaque,
or auto. 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.
Default: auto.
Set the background of the generated image. One of transparent, opaque,
or auto. 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.
Default: auto.
input_fidelity: optional "high" or "low" or nullControl how much effort the model will exert to match the style and features, especially facial features, of input images. Supports high and low on gpt-image-1 and gpt-image-1.5; gpt-image-1-mini supports only low. For gpt-image-2, omit this parameter. Defaults to low on supported models.
Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports high and low on gpt-image-1 and gpt-image-1.5; gpt-image-1-mini supports only low. For gpt-image-2, omit this parameter. Defaults to low on supported models.
input_image_mask: optional object { file_id, image_url } Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5" or 6 moreThe 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.
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" or "gpt-image-1-mini" or "gpt-image-1.5" or 6 moreThe 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.
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.
Compression level for the output image. Default: 100.
output_format: optional "png" or "webp" or "jpeg"The output format of the generated image. One of png, webp, or
jpeg. Default: png.
The output format of the generated image. One of png, webp, or
jpeg. Default: png.
Number of partial images to generate in streaming mode, from 0 (default value) to 3.
quality: optional "low" or "medium" or "high" or 3 moreThe 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.
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.
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "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.
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.
"1024x1024" or "1024x1536" or "1536x1024" or "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.
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.
LocalShell object { type } A tool that allows the model to execute shell commands in a local environment.
A tool that allows the model to execute shell commands in a local environment.
Shell object { type, allowed_callers, environment } A tool that allows the model to execute shell commands.
A tool that allows the model to execute shell commands.
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or LocalEnvironment { type, skills } or ContainerReference { container_id, type } or null
ContainerAuto object { type, file_ids, memory_limit, 2 more }
An optional list of uploaded files to make available to your code.
network_policy: optional ContainerNetworkPolicyDisabled { type } or ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
skills: optional array of SkillReference { skill_id, type, version } or InlineSkill { description, name, source, type } An optional list of skills referenced by id or inline data.
An optional list of skills referenced by id or inline data.
Custom object { name, type, allowed_callers, 4 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
Namespace object { description, name, tools, type } Groups function/custom tools under a shared namespace.
Groups function/custom tools under a shared namespace.
tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more } The function/custom tools available inside this namespace.
The function/custom tools available inside this namespace.
Function object { name, type, allowed_callers, 6 more }
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
Whether this function should be deferred and discovered via tool search.
Custom object { name, type, allowed_callers, 4 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
allowed_callers: optional array of "direct" or "programmatic" or nullThe tool invocation context(s).
The tool invocation context(s).
Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
ToolSearch object { type, description, execution, parameters } Hosted or BYOT tool search configuration for deferred tools.
Hosted or BYOT tool search configuration for deferred tools.
WebSearchPreview object { type, search_content_types, search_context_size, user_location } This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
type: "web_search_preview" or "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.
The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
search_context_size: optional "low" or "medium" or "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.
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.
user_location: optional object { type, city, country, 2 more } or nullThe approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass {"type": "approximate"} without location fields. To localize results, provide the relevant location fields.
The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass {"type": "approximate"} without location fields. To localize results, provide the relevant location fields.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
ConfigurationUpdate object { type, id, reasoning } An update to the conversation’s response configuration. The configuration
remains in effect for subsequent responses until it is replaced by another
configuration update.
An update to the conversation’s response configuration. The configuration remains in effect for subsequent responses until it is replaced by another configuration update.
Reasoning object { id, summary, type, 3 more } 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.
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.
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.
Compaction object { encrypted_content, type, id } A compaction item generated by the v1/responses/compact API.
A compaction item generated by the v1/responses/compact API.
ImageGenerationCall object { id, result, status, 8 more } An image generation request made by the model.
An image generation request made by the model.
status: "in_progress" or "completed" or "generating" or "failed"The status of the image generation call.
The status of the image generation call.
background: optional "transparent" or "opaque" or "auto" or nullThe background setting used for generation.
The background setting used for generation.
error: optional object { code, message, param, 2 more } Details of a moderation failure, when available.
Details of a moderation failure, when available.
quality: optional "low" or "medium" or "high" or 3 more or nullThe quality of the image generated by the image generation tool call. One of low, medium, high, xhigh, max, or auto.
The quality of the image generated by the image generation tool call. One of low, medium, high, xhigh, max, or auto.
CodeInterpreterCall object { id, code, container_id, 3 more } A tool call to run code.
A tool call to run code.
outputs: array of Logs { logs, type } or Image { type, url } or nullThe outputs generated by the code interpreter, such as logs or images.
Can be null if no outputs are available.
The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available.
LocalShellCall object { id, action, call_id, 2 more } A tool call to run a command on the local shell.
A tool call to run a command on the local shell.
LocalShellCallOutput object { id, output, type, status } The output of a local shell tool call.
The output of a local shell tool call.
ShellCall object { action, call_id, type, 4 more } A tool representing a request to execute one or more shell commands.
A tool representing a request to execute one or more shell commands.
action: object { commands, max_output_length, timeout_ms } The shell commands and limits that describe how to run the tool call.
The shell commands and limits that describe how to run the tool call.
The unique ID of the shell tool call. Populated when this item is returned via API.
caller: optional Direct { type } or Program { caller_id, type } or nullThe execution context that produced this tool call.
The execution context that produced this tool call.
environment: optional LocalEnvironment { type, skills } or ContainerReference { container_id, type } or nullThe environment to execute the shell commands in.
The environment to execute the shell commands in.
ShellCallOutput object { call_id, output, type, 4 more } The streamed output items emitted by a shell tool call.
The streamed output items emitted by a shell tool call.
Captured chunks of stdout and stderr output, along with their associated outcomes.
Captured chunks of stdout and stderr output, along with their associated outcomes.
The unique ID of the shell tool call output. Populated when this item is returned via API.
caller: optional Direct { type } or Program { caller_id, type } or nullThe execution context that produced this tool call.
The execution context that produced this tool call.
ApplyPatchCall object { call_id, operation, status, 3 more } A tool call representing a request to create, delete, or update files using diff patches.
A tool call representing a request to create, delete, or update files using diff patches.
The unique ID of the apply patch tool call generated by the model.
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type } The specific create, delete, or update instruction for the apply_patch tool call.
The specific create, delete, or update instruction for the apply_patch tool call.
CreateFile object { diff, path, type } Instruction for creating a new file via the apply_patch tool.
Instruction for creating a new file via the apply_patch tool.
DeleteFile object { path, type } Instruction for deleting an existing file via the apply_patch tool.
Instruction for deleting an existing file via the apply_patch tool.
status: "in_progress" or "completed"The status of the apply patch tool call. One of in_progress or completed.
The status of the apply patch tool call. One of in_progress or completed.
The unique ID of the apply patch tool call. Populated when this item is returned via API.
ApplyPatchCallOutput object { call_id, status, type, 3 more } The streamed output emitted by an apply patch tool call.
The streamed output emitted by an apply patch tool call.
The unique ID of the apply patch tool call generated by the model.
status: "completed" or "failed"The status of the apply patch tool call output. One of completed or failed.
The status of the apply patch tool call output. One of completed or failed.
The unique ID of the apply patch tool call output. Populated when this item is returned via API.
McpListTools object { id, server_label, tools, 2 more } A list of tools available on an MCP server.
A list of tools available on an MCP server.
McpApprovalRequest object { id, arguments, name, 2 more } A request for human approval of a tool invocation.
A request for human approval of a tool invocation.
McpApprovalResponse object { approval_request_id, approve, type, 2 more } A response to an MCP approval request.
A response to an MCP approval request.
McpCall object { id, arguments, name, 6 more } An invocation of a tool on an MCP server.
An invocation of a tool on an MCP server.
CustomToolCallOutput object { call_id, output, type, 2 more } The output of a custom tool call from your code, being sent back to the model.
The output of a custom tool call from your code, being sent back to the model.
output: string or array of ResponseInputText { text, type, prompt_cache_breakpoint } or ResponseInputImage { detail, type, file_id, 2 more } or ResponseInputFile { type, detail, file_data, 4 more } The output from the custom tool call generated by your code.
Can be a string or an list of output content.
The output from the custom tool call generated by your code. Can be a string or an list of output content.
OutputContentList = array of ResponseInputText { text, type, prompt_cache_breakpoint } or ResponseInputImage { detail, type, file_id, 2 more } or ResponseInputFile { type, detail, file_data, 4 more } Text, image, or file output of the custom tool call.
Text, image, or file output of the custom tool call.
ResponseInputImage object { detail, type, file_id, 2 more } An image input to the model. Learn about image inputs.
An image input to the model. Learn about image inputs.
ResponseInputFile object { type, detail, file_data, 4 more } A file input to the model.
A file input to the model.
detail: optional "auto" or "low" or "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.
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.
The type of the custom tool call output. Always custom_tool_call_output.
CustomToolCall object { call_id, input, name, 5 more } A call to a custom tool created by the model.
A call to a custom tool created by the model.
ResponseCreateEvent object { type, event_id } Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation.
Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation.
SidebandServerEvent = TransportRinging { event_id, session_id, type } or TransportAnswered { event_id, session_id, type } or TransportFailed { error, event_id, session_id, type } or 20 moreServer events received by an attached Live sideband WebSocket. Audio deltas are delivered over the primary connection.
Server events received by an attached Live sideband WebSocket. Audio deltas are delivered over the primary connection.
TransportRinging object { event_id, session_id, type } The outbound SIP provider leg is ringing or providing early media. Delivered only to sideband observers.
The outbound SIP provider leg is ringing or providing early media. Delivered only to sideband observers.
TransportAnswered object { event_id, session_id, type } The outbound SIP provider leg answered and media is established. Delivered only to sideband observers.
The outbound SIP provider leg answered and media is established. Delivered only to sideband observers.
TransportFailed object { error, event_id, session_id, type } An asynchronous outbound SIP setup failure. Delivered only to sideband observers.
An asynchronous outbound SIP setup failure. Delivered only to sideband observers.
SessionStartedEvent object { event_id, session, type, client_event_id } Returned when a Live session has started. Contains the resolved session configuration, including server defaults.
Returned when a Live session has started. Contains the resolved session configuration, including server defaults.
SessionUpdatedEvent object { event_id, session, type, client_event_id } Returned when a Live session update is accepted. Contains the resolved session configuration after the update.
Returned when a Live session update is accepted. Contains the resolved session configuration after the update.
InputAudioMutedEvent object { event_id, type, client_event_id } Acknowledges a session.input_audio.mute command. An independent input mute sends silence to the model and preserves sideband audio reflection. Fixture playback does not emit this event.
Acknowledges a session.input_audio.mute command. An independent input mute sends silence to the model and preserves sideband audio reflection. Fixture playback does not emit this event.
InputAudioUnmutedEvent object { event_id, type, client_event_id } Acknowledges a session.input_audio.unmute command, removing the independent input mute. An active audio fixture still pauses inference until playback finishes. Fixture playback does not emit this event.
Acknowledges a session.input_audio.unmute command, removing the independent input mute. An active audio fixture still pauses inference until playback finishes. Fixture playback does not emit this event.
OutputAudioFixturePlayingEvent object { event_id, type, client_event_id } The existing playback path has accepted the validated audio fixture. This acknowledgment does not identify when the listener receives the first sample. The optional client_event_id echoes the play command.
The existing playback path has accepted the validated audio fixture. This acknowledgment does not identify when the listener receives the first sample. The optional client_event_id echoes the play command.
OutputAudioFixturePlayedEvent object { event_id, type, client_event_id } The complete audio fixture has drained from the server mixer and normal inference has resumed. Transport buffers may still contain audio; this event does not prove listener-side completion. The optional client_event_id echoes the play command. This event is not emitted for canceled or failed playback.
The complete audio fixture has drained from the server mixer and normal inference has resumed. Transport buffers may still contain audio; this event does not prove listener-side completion. The optional client_event_id echoes the play command. This event is not emitted for canceled or failed playback.
InstructionsAppendedEvent object { end_ms, event_id, start_ms, 2 more } 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.
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.
ThinkingAppendedEvent object { end_ms, event_id, start_ms, 2 more } Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output.
Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output.
CommentaryAppendedEvent object { end_ms, event_id, start_ms, 2 more } 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.
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.
InputTranscriptDeltaEvent object { delta, end_ms, event_id, 3 more } 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.
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.
The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript.
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.
OutputTranscriptDeltaEvent object { delta, end_ms, event_id, 3 more } 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.
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.
The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript.
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.
DelegationCreatedEvent object { delegation, event_id, offset_ms, 2 more } Returned when the Live model delegates work to your application, Responses, or Decisions. Contains delegation metadata and the position on the session timeline where the work was delegated.
Returned when the Live model delegates work to your application, Responses, or Decisions. Contains delegation metadata and the position on the session timeline where the work was delegated.
delegation: object { id, target, type, response_id } The delegated work identifier and destination. This object contains metadata, not the task text.
The delegated work identifier and destination. This object contains metadata, not the task text.
DecisionEvent object { delegation_id, event, event_id, 4 more } A Decision API event for a Live delegation or transcript trigger. For a trigger, source_event_id identifies the transcript delta that caused this evaluation.
A Decision API event for a Live delegation or transcript trigger. For a trigger, source_event_id identifies the transcript delta that caused this evaluation.
event: object { decision, type }
The event_id of the transcript delta that fired this trigger, or null for a delegation.
DecisionItemCreatedEvent object { event_id, item, type, client_event_id } An input item was appended for future decisions.
An input item was appended for future decisions.
item: object { id, content, role, type }
content: string or array of InputText { text, type } or InputImage { image_url, type, detail } The text input to the model.
The text input to the model.
DecisionItemDeletedEvent object { event_id, item_id, type, client_event_id } An input item was removed from future decisions.
An input item was removed from future decisions.
ResponseEvent object { event, event_id, type, 2 more } 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.
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.
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.
SessionUsageUpdatedEvent object { event_id, type, usage, 2 more } 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.
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.
SessionClosedEvent object { event_id, reason, session, 3 more } 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.
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.
reason: "close_requested" or "expired" or "content" or 2 moreWhy 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.
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" or "expired" or "content" or 2 moreWhy 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.
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.
ErrorEvent object { error, event_id, type, client_event_id } 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.
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.