Live
Create session
ModelsExpand Collapse
AudioFormat = object { rate, type } or object { rate, type } or object { rate, type } Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately.
Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately.
ClientEvent = SessionStartEvent { session, type, event_id } or SessionUpdateEvent { session, type, event_id } or InputAudioAppendEvent { audio, type, event_id } or 8 moreClient events for Live. Initialize a primary WebSocket with session.start and wait for session.started. WebRTC creation already starts the session. Audio append is primary WebSocket-only. See the Live prompting guide before writing frontend instructions and delegation policies.
Client events for Live. Initialize a primary WebSocket with session.start and wait for session.started. WebRTC creation already starts the session. Audio append is primary WebSocket-only. See the Live prompting guide before writing frontend instructions and delegation policies.
SessionStartEvent object { session, type, event_id } Start a Live session on a primary WebSocket. Send this event before other commands and wait for session.started.
Start a Live session on a primary WebSocket. Send this event before other commands and wait for session.started.
SessionUpdateEvent object { session, type, event_id } Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.
Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.
InputAudioAppendEvent object { audio, type, event_id } Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz.
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.
Resume audio input to a Live model after muting it. The server acknowledges with session.input_audio.unmuted.
InstructionsAppendEvent object { content, delegation_id, type, event_id } Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
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.
Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation.
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.
Provide context the Live model can communicate to the user, optionally for an existing client delegation.
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.
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 object { 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 object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { 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, action, status, type } 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.
action: object { type, queries, query, sources } or object { type, url } or object { 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.
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
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 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 object { type } or object { 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 object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { 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.
The approximate location of the user.
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 object { 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 moreIdentifier 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.
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
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.
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 object { 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 object { 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. 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.
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.
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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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" 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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.
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 object { name, type, allowed_callers, 6 more } or object { 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 user’s location.
The user’s location.
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 object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { 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.
The approximate location of the user.
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 object { 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 moreIdentifier 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.
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
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.
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 object { 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 object { 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. 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.
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.
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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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" 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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.
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 object { name, type, allowed_callers, 6 more } or object { 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 user’s location.
The user’s location.
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, 7 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.
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 object { logs, type } or object { 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 object { type } or object { 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 object { type } or object { 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: object { diff, path, type } or object { path, type } or object { 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.
CommentaryAppendEvent object { content, delegation_id, type, event_id } Provide context the Live model can communicate to the user, optionally for an existing client delegation.
Provide context the Live model can communicate to the user, optionally for an existing client delegation.
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.
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.
DataChannelConfig object { allowed_client_events, allowed_server_events } Control which Live events an untrusted WebRTC frontend can send and receive over its data channel. These restrictions do not apply to trusted sideband connections.
Control which Live events an untrusted WebRTC frontend can send and receive over its data channel. These restrictions do not apply to trusted sideband connections.
allowed_client_events: optional "all" or array of stringClient 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.
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.
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.
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.
array of ServerEventSelector { type, response_event }
DelegationCreatedEvent object { delegation, event_id, offset_ms, 2 more } 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.
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: 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.
Error object { code, message, type, 2 more } Details of an error encountered by the Live session, including the affected parameter or client command when available.
Details of an error encountered by the Live session, including the affected parameter or client command when available.
ForkSessionConfig object { audio, client, delegation, store } Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks.
Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks.
audio: optional object { format } Audio format for a WebSocket fork. WebRTC forks negotiate their audio format and must omit this field.
Audio format for a WebSocket fork. WebRTC forks negotiate their audio format and must omit this field.
Frontend data-channel permissions for a WebRTC fork. Omitted permissions inherit the stored values. Not supported for WebSocket forks.
delegation: optional object { type, responses } Overrides for the stored session’s Responses backend. Only supported when the stored session already uses Responses delegation; the delegation type cannot change.
Overrides for the stored session’s Responses backend. Only supported when the stored session already uses Responses delegation; the delegation type cannot change.
Responses backend settings to update. Omitted settings keep their existing values.
ForkSessionStartEvent object { session, type, event_id } Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty session object to use the stored configuration.
Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty session object to use the stored configuration.
FunctionTool object { name, type, description, 2 more } A function tool available to the Responses backend when the Live model delegates a task.
A function tool available to the Responses backend when the Live model delegates a task.
InitialItem = object { content, role, id, 2 more } or object { content, role, id, 2 more } or object { content, role, id, 2 more } A developer, user, or assistant message supplied as text history before the Live session starts.
A developer, user, or assistant message supplied as text history before the Live session starts.
Developer object { content, role, id, 2 more } A developer message included in the initial text history of a Live session.
A developer message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
User object { content, role, id, 2 more } A user message included in the initial text history of a Live session.
A user message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Assistant object { content, role, id, 2 more } An assistant message included in the initial text history of a Live session.
An assistant message included in the initial text history of a Live session.
content: array of object { text, type } or object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
InputAudioAppendEvent object { audio, type, event_id } Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz.
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.
InstructionsAppendEvent object { content, delegation_id, type, event_id } Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts.
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.
LiveCreateResponse object { session, transport } The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer’s remote answer and wait for session.started on the data channel before sending commands.
The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer’s remote answer and wait for session.started on the data channel before sending commands.
MediaSessionConfig object { model, audio, client, 4 more } Startup configuration for a Live media session. Follow the Live prompting guide when writing frontend instructions and the backend prompt under delegation.responses.instructions.
Startup configuration for a Live media session. Follow the Live prompting guide when writing frontend instructions and the backend prompt under delegation.responses.instructions.
model: string or "gpt-live-1"The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
audio: optional object { output } Startup audio configuration. WebRTC and SIP negotiate their audio format on the media transport.
Startup audio configuration. WebRTC and SIP negotiate their audio format on the media transport.
output: optional object { voice } Settings for speech generated by the Live model. Choose the voice before starting the session.
Settings for speech generated by the Live model. Choose the voice before starting the session.
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.
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.
Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.
Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.
Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.
ClientDelegation object { type } Delegate tasks to your application. The Live session emits delegation events that your backend handles.
Delegate tasks to your application. The Live session emits delegation events that your backend handles.
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.
Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total.
Developer object { content, role, id, 2 more } A developer message included in the initial text history of a Live session.
A developer message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
User object { content, role, id, 2 more } A user message included in the initial text history of a Live session.
A user message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Assistant object { content, role, id, 2 more } An assistant message included in the initial text history of a Live session.
An assistant message included in the initial text history of a Live session.
content: array of object { text, type } or object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the Live prompting guide; put business rules and tool workflows in a separate backend prompt. Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup.
MediaSessionForkConfig object { client, delegation, store } Optional overrides for a stored Live session. Omitted settings are inherited. The model, voice, frontend instructions, and prior conversation come from the stored session. WebRTC negotiates its audio format; audio.format is only supported on WebSocket forks.
Optional overrides for a stored Live session. Omitted settings are inherited. The model, voice, frontend instructions, and prior conversation come from the stored session. WebRTC negotiates its audio format; audio.format is only supported on WebSocket forks.
Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.
delegation: optional object { type, responses } Update the Responses backend for an existing Live session without changing delegation ownership.
Update the Responses backend for an existing Live session without changing delegation ownership.
Responses backend settings to update. Omitted settings keep their existing values.
OutputAudioDeltaEvent object { delta, type, end_ms, start_ms } An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.
An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.
Base64-encoded raw audio. Primary WebSocket events use the session’s configured format; reflected sideband events use mono PCM16LE at 24 kHz.
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.
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.
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 object { 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 object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { 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, action, status, type } 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.
action: object { type, queries, query, sources } or object { type, url } or object { 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.
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
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 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 object { type } or object { 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 object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { 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.
The approximate location of the user.
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 object { 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 moreIdentifier 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.
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
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.
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 object { 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 object { 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. 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.
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.
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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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" 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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.
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 object { name, type, allowed_callers, 6 more } or object { 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 user’s location.
The user’s location.
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 object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { 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.
The approximate location of the user.
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 object { 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 moreIdentifier 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.
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
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.
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 object { 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 object { 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. 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.
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.
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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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" 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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.
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 object { name, type, allowed_callers, 6 more } or object { 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 user’s location.
The user’s location.
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, 7 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.
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 object { logs, type } or object { 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 object { type } or object { 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 object { type } or object { 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: object { diff, path, type } or object { path, type } or object { 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.
ResponsesDelegationConfig object { model, instructions, max_output_tokens, 6 more } Model, prompt, and tool settings for tasks delegated by the Live session to a Responses backend.
Model, prompt, and tool settings for tasks delegated by the Live session to a Responses backend.
Instructions for the delegated Responses model, separate from Live instructions. See backend prompting.
Maximum number of output tokens for each delegated response.
Whether the delegated Responses model may request multiple tool calls in a single response.
reasoning: optional object { effort, summary } or nullReasoning settings passed to each delegated Responses request.
Reasoning settings passed to each delegated Responses request.
service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or nullService tier for delegated Responses requests.
Service tier for delegated Responses requests.
text: optional object { verbosity } or nullText generation settings passed to each delegated Responses request.
Text generation settings passed to each delegated Responses request.
tool_choice: optional "auto" or "none" or "required" or object { name, type } or object { name, server_label, type } Controls which tool the Responses backend uses when handling a task delegated by the Live model.
Controls which tool the Responses backend uses when handling a task delegated by the Live model.
Tools available to the Responses backend while it handles tasks delegated by the Live model.
Tools available to the Responses backend while it handles tasks delegated by the Live model.
FunctionTool object { name, type, description, 2 more } A function tool available to the Responses backend when the Live model delegates a task.
A function tool available to the Responses backend when the Live model delegates a task.
ResponsesDelegationUpdateConfig object { instructions, max_output_tokens, model, 6 more } Updates to the Responses backend of an existing Live session. Omitted settings retain their current values.
Updates to the Responses backend of an existing Live session. Omitted settings retain their current values.
Instructions for the delegated Responses model, separate from Live instructions. See backend prompting.
Maximum number of output tokens for each delegated response.
The Responses backend model to use for subsequent delegated requests. Omit to keep the current backend model.
Whether the delegated Responses model may request multiple tool calls in a single response.
reasoning: optional object { effort, summary } or nullReasoning settings passed to each delegated Responses request.
Reasoning settings passed to each delegated Responses request.
service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or nullService tier for delegated Responses requests.
Service tier for delegated Responses requests.
text: optional object { verbosity } or nullText generation settings passed to each delegated Responses request.
Text generation settings passed to each delegated Responses request.
tool_choice: optional "auto" or "none" or "required" or object { name, type } or object { name, server_label, type } Controls which tool the Responses backend uses when handling a task delegated by the Live model.
Controls which tool the Responses backend uses when handling a task delegated by the Live model.
Tools available to the Responses backend while it handles tasks delegated by the Live model.
Tools available to the Responses backend while it handles tasks delegated by the Live model.
FunctionTool object { name, type, description, 2 more } A function tool available to the Responses backend when the Live model delegates a task.
A function tool available to the Responses backend when the Live model delegates a task.
ServerEvent = SessionStartedEvent { event_id, session, type, client_event_id } or SessionUpdatedEvent { event_id, session, type, client_event_id } or InputAudioMutedEvent { event_id, type, client_event_id } or 19 moreServer events for Live. Response lifecycle events are wrapped inside response.event; dispatch the nested event by its full type and tolerate new response event types. Follow the Live prompting guide when designing the conversation and delegation policy.
Server events for Live. Response lifecycle events are wrapped inside response.event; dispatch the nested event by its full type and tolerate new response event types. Follow the Live prompting guide when designing the conversation and delegation policy.
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 } Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues.
Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues.
InputAudioUnmutedEvent object { event_id, type, client_event_id } Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again.
Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again.
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.
SessionInputAudioAppend object { audio, type } Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting.
Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting.
OutputAudioDeltaEvent object { delta, type, end_ms, start_ms } An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.
An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.
Base64-encoded raw audio. Primary WebSocket events use the session’s configured format; reflected sideband events use mono PCM16LE at 24 kHz.
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 or a Responses backend. 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 or a Responses backend. 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.
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.
InfoEvent object { code, event_id, message, 2 more } An informational notice about the Live session, such as the event permissions applied to a frontend data channel.
An informational notice about the Live session, such as the event permissions applied to a frontend data channel.
TransportDtmfReceived object { event, event_id, type } A SIP DTMF keypress received from the caller. Delivered only to sideband observers.
A SIP DTMF keypress received from the caller. Delivered only to sideband observers.
TransportDtmfSend object { event, event_id, type } A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command.
A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command.
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.
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.
SessionConfig object { model, audio, client, 4 more } Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling.
Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling.
model: string or "gpt-live-1"The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
audio: optional object { format, output } Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup.
Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup.
Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately.
output: optional object { voice } The voice used for speech generated by the Live model.
The voice used for speech generated by the Live model.
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.
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.
Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.
Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.
Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.
ClientDelegation object { type } Delegate tasks to your application. The Live session emits delegation events that your backend handles.
Delegate tasks to your application. The Live session emits delegation events that your backend handles.
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.
Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total.
Developer object { content, role, id, 2 more } A developer message included in the initial text history of a Live session.
A developer message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
User object { content, role, id, 2 more } A user message included in the initial text history of a Live session.
A user message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Assistant object { content, role, id, 2 more } An assistant message included in the initial text history of a Live session.
An assistant message included in the initial text history of a Live session.
content: array of object { text, type } or object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the Live prompting guide; put business rules and tool workflows in a separate backend prompt. Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup.
SessionResource object { id, expires_at, model, 7 more } The resolved Live session configuration and server-assigned session metadata.
The resolved Live session configuration and server-assigned session metadata.
The unique ID of the Live session. Use this ID for sideband connections, forking, and recording download.
model: string or "gpt-live-1"The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
The Live model. Required in the session configuration for every transport; do not pass it as a URL query parameter.
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.
audio: optional object { format, output } Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup.
Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup.
Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately.
output: optional object { voice } The voice used for speech generated by the Live model.
The voice used for speech generated by the Live model.
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.
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.
Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected.
Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.
Who handles tasks delegated by the Live model. Omitted or null selects your application; use responses to let the API manage a Responses backend.
ClientDelegation object { type } Delegate tasks to your application. The Live session emits delegation events that your backend handles.
Delegate tasks to your application. The Live session emits delegation events that your backend handles.
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.
Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total.
Developer object { content, role, id, 2 more } A developer message included in the initial text history of a Live session.
A developer message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
User object { content, role, id, 2 more } A user message included in the initial text history of a Live session.
A user message included in the initial text history of a Live session.
content: array of object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Assistant object { content, role, id, 2 more } An assistant message included in the initial text history of a Live session.
An assistant message included in the initial text history of a Live session.
content: array of object { text, type } or object { text, type } The message content. Supply exactly one text part for the initial Live conversation history.
The message content. Supply exactly one text part for the initial Live conversation history.
An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.
Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the Live prompting guide; put business rules and tool workflows in a separate backend prompt. Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup.
SessionStartEvent object { session, type, event_id } Start a Live session on a primary WebSocket. Send this event before other commands and wait for session.started.
Start a Live session on a primary WebSocket. Send this event before other commands and wait for session.started.
SessionUpdateConfig object { delegation } Changes to an active Live session. Only delegation backend settings can be updated after startup.
Changes to an active Live session. Only delegation backend settings can be updated after startup.
Delegation settings to update. The delegation type must match the current session; omitted settings retain their values.
Delegation settings to update. The delegation type must match the current session; omitted settings retain their values.
ClientDelegation object { type } Delegate tasks to your application. The Live session emits delegation events that your backend handles.
Delegate tasks to your application. The Live session emits delegation events that your backend handles.
Responses object { type, responses } Update the Responses backend for an existing Live session without changing delegation ownership.
Update the Responses backend for an existing Live session without changing delegation ownership.
Responses backend settings to update. Omitted settings keep their existing values.
SessionUpdateEvent object { session, type, event_id } Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.
Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.
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.
ThinkingAppendEvent object { content, delegation_id, type, event_id } Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation.
Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation.
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.
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.
LiveForks
ModelsExpand Collapse
ForkClientEvent = ForkSessionStartEvent { session, type, event_id } or SessionUpdateEvent { session, type, event_id } or InputAudioAppendEvent { audio, type, event_id } or 8 moreClient events for a Live fork WebSocket. First send session.start with an overrides object (which may be empty), then wait for session.started before sending other commands. The model and conversation are inherited from the stored session.
Client events for a Live fork WebSocket. First send session.start with an overrides object (which may be empty), then wait for session.started before sending other commands. The model and conversation are inherited from the stored session.
ForkSessionStartEvent object { session, type, event_id } Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty session object to use the stored configuration.
Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty session object to use the stored configuration.
SessionUpdateEvent object { session, type, event_id } Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.
Update the delegation settings of an active Live session. The server acknowledges accepted changes with session.updated.
InputAudioAppendEvent object { audio, type, event_id } Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport.
Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz.
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.
Resume audio input to a Live model after muting it. The server acknowledges with session.input_audio.unmuted.
InstructionsAppendEvent object { content, delegation_id, type, event_id } Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation.
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.
Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation.
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.
Provide context the Live model can communicate to the user, optionally for an existing client delegation.
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.
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 object { 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 object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { 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, action, status, type } 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.
action: object { type, queries, query, sources } or object { type, url } or object { 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.
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
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 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 object { type } or object { 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 object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { 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.
The approximate location of the user.
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 object { 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 moreIdentifier 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.
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
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.
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 object { 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 object { 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. 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.
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.
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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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" 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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.
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 object { name, type, allowed_callers, 6 more } or object { 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 user’s location.
The user’s location.
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 object { name, parameters, strict, 6 more } or object { type, vector_store_ids, filters, 2 more } or object { 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.
The approximate location of the user.
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 object { 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 moreIdentifier 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.
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
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.
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 object { 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 object { 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. 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.
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.
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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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" 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
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.
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 object { name, type, allowed_callers, 6 more } or object { 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 user’s location.
The user’s location.
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, 7 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.
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 object { logs, type } or object { 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 object { type } or object { 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 object { type } or object { 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: object { diff, path, type } or object { path, type } or object { 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.
ForkServerEvent = SessionStartedEvent { event_id, session, type, client_event_id } or SessionUpdatedEvent { event_id, session, type, client_event_id } or InputAudioMutedEvent { event_id, type, client_event_id } or 19 moreServer events for Live. Response lifecycle events are wrapped inside response.event; dispatch the nested event by its full type and tolerate new response event types. Follow the Live prompting guide when designing the conversation and delegation policy.
Server events for Live. Response lifecycle events are wrapped inside response.event; dispatch the nested event by its full type and tolerate new response event types. Follow the Live prompting guide when designing the conversation and delegation policy.
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 } Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues.
Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues.
InputAudioUnmutedEvent object { event_id, type, client_event_id } Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again.
Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again.
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.
SessionInputAudioAppend object { audio, type } Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting.
Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting.
OutputAudioDeltaEvent object { delta, type, end_ms, start_ms } An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.
An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps.
Base64-encoded raw audio. Primary WebSocket events use the session’s configured format; reflected sideband events use mono PCM16LE at 24 kHz.
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 or a Responses backend. 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 or a Responses backend. 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.
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.
InfoEvent object { code, event_id, message, 2 more } An informational notice about the Live session, such as the event permissions applied to a frontend data channel.
An informational notice about the Live session, such as the event permissions applied to a frontend data channel.
TransportDtmfReceived object { event, event_id, type } A SIP DTMF keypress received from the caller. Delivered only to sideband observers.
A SIP DTMF keypress received from the caller. Delivered only to sideband observers.
TransportDtmfSend object { event, event_id, type } A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command.
A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command.
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.
LiveSessions
Accept call
Download recording
Fork session
Hang up session
Transfer call
Reject call
ModelsExpand Collapse
SessionForkResponse object { session, transport } The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer’s remote answer and wait for session.started on the data channel before sending commands.
The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer’s remote answer and wait for session.started on the data channel before sending commands.