diff --git a/en/resources/responses/index.md b/en/resources/responses/index.md index 68b772e..b6c6965 100644 --- a/en/resources/responses/index.md +++ b/en/resources/responses/index.md @@ -76,7 +76,7 @@ as input for the model's response. - `"message.output_text.logprobs"` -- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` Text, image, or file inputs to the model, used to generate a response. @@ -93,7 +93,7 @@ as input for the model's response. A text input to the model, equivalent to a text input with the `user` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -876,19 +876,15 @@ as input for the model's response. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -899,6 +895,10 @@ as input for the model's response. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -2170,6 +2170,750 @@ as input for the model's response. - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -3184,6 +3928,12 @@ as input for the model's response. - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -4411,7 +5161,7 @@ as input for the model's response. - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -4424,7 +5174,7 @@ as input for the model's response. A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -5207,19 +5957,15 @@ as input for the model's response. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -5230,6 +5976,10 @@ as input for the model's response. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -6501,6 +7251,750 @@ as input for the model's response. - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -7645,19 +9139,15 @@ as input for the model's response. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -7668,6 +9158,10 @@ as input for the model's response. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -8706,6 +10200,764 @@ as input for the model's response. The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -10416,6 +12668,12 @@ as input for the model's response. - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -11700,7 +13958,7 @@ Retrieves a model response with the given ID. - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -11713,7 +13971,7 @@ Retrieves a model response with the given ID. A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -12496,19 +14754,15 @@ Retrieves a model response with the given ID. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -12519,6 +14773,10 @@ Retrieves a model response with the given ID. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -13790,6 +16048,750 @@ Retrieves a model response with the given ID. - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -14934,19 +17936,15 @@ Retrieves a model response with the given ID. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -14957,6 +17955,10 @@ Retrieves a model response with the given ID. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -15995,6 +18997,764 @@ Retrieves a model response with the given ID. The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -17705,6 +21465,12 @@ Retrieves a model response with the given ID. - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -18289,7 +22055,7 @@ the `background` parameter set to `true` can be cancelled. - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -18302,7 +22068,7 @@ the `background` parameter set to `true` can be cancelled. A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -19085,19 +22851,15 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -19108,6 +22870,10 @@ the `background` parameter set to `true` can be cancelled. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -20379,6 +24145,750 @@ the `background` parameter set to `true` can be cancelled. - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -21523,19 +26033,15 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -21546,6 +26052,10 @@ the `background` parameter set to `true` can be cancelled. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -22584,6 +27094,764 @@ the `background` parameter set to `true` can be cancelled. The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -24294,6 +29562,12 @@ the `background` parameter set to `true` can be cancelled. - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -24954,7 +30228,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `string` -- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` Text, image, or file inputs to the model, used to generate a response @@ -24962,7 +30236,7 @@ Learn when and how to compact long-running conversations in the [conversation st A text input to the model, equivalent to a text input with the `user` role. - - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -25744,19 +31018,15 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -25767,6 +31037,10 @@ Learn when and how to compact long-running conversations in the [conversation st The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -27038,6 +32312,750 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -27831,7 +33849,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"response.compaction"` - - `output: array of Message or object { arguments, call_id, name, 4 more } or object { id, arguments, call_id, 4 more } or 22 more` + - `output: array of Message or object { arguments, call_id, name, 4 more } or object { id, arguments, call_id, 4 more } or 23 more` The compacted list of output items. @@ -29278,6 +35296,764 @@ Learn when and how to compact long-running conversations in the [conversation st The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `FunctionCallOutput object { call_id, output, type, 2 more }` The output of a function tool call. @@ -29410,19 +36186,15 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -29433,6 +36205,10 @@ Learn when and how to compact long-running conversations in the [conversation st The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -30776,7 +37552,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"response.compaction"` - - `output: array of Message or object { arguments, call_id, name, 4 more } or object { id, arguments, call_id, 4 more } or 22 more` + - `output: array of Message or object { arguments, call_id, name, 4 more } or object { id, arguments, call_id, 4 more } or 23 more` The compacted list of output items. @@ -32223,6 +38999,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `FunctionCallOutput object { call_id, output, type, 2 more }` The output of a function tool call. @@ -32355,19 +39889,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -32378,6 +39908,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -34474,7 +42008,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -34487,7 +42021,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -35270,19 +42804,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -35293,6 +42823,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -36564,6 +44098,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -37708,19 +45986,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -37731,6 +46005,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -38769,6 +47047,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -40479,6 +49515,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -41019,7 +50061,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -41032,7 +50074,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -41815,19 +50857,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -41838,6 +50876,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -43109,6 +52151,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -44253,19 +54039,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -44276,6 +54058,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -45314,6 +55100,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -47024,6 +57568,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -48041,7 +58591,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -48054,7 +58604,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -48837,19 +59387,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -48860,6 +59406,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -50131,6 +60681,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -51275,19 +62569,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -51298,6 +62588,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -52336,6 +63630,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -54046,6 +66098,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -54530,7 +66588,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -54543,7 +66601,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -55326,19 +67384,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -55349,6 +67403,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -56620,6 +68678,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -57764,19 +70566,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -57787,6 +70585,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -58825,6 +71627,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -60535,6 +74095,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -61272,7 +74838,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -61285,7 +74851,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -62068,19 +75634,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -62091,6 +75653,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -63362,6 +76928,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -64506,19 +78816,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -64529,6 +78835,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -65567,6 +79877,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -67277,6 +82345,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -67658,7 +82732,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -67671,7 +82745,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -68454,19 +83528,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -68477,6 +83547,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -69748,6 +84822,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -70892,19 +86710,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -70915,6 +86729,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -71953,6 +87771,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -73663,6 +90239,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -74651,7 +91233,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ ### Response Output Item -- `ResponseOutputItem = ResponseOutputMessage or object { id, queries, status, 2 more } or object { arguments, call_id, name, 4 more } or 22 more` +- `ResponseOutputItem = ResponseOutputMessage or object { id, queries, status, 2 more } or object { arguments, call_id, name, 4 more } or 23 more` An output message from the model. @@ -75085,19 +91667,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -75108,6 +91686,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -76639,6 +93221,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -77789,19 +95129,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -77812,6 +95148,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -79343,6 +96683,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -80507,19 +98605,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -80530,6 +98624,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -82061,6 +100159,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -83339,7 +102195,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -83352,7 +102208,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -84135,19 +102991,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -84158,6 +103010,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -85429,6 +104285,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -86573,19 +106173,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -86596,6 +106192,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -87634,6 +107234,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -89344,6 +109702,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -90175,7 +110539,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -90188,7 +110552,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -90971,19 +111335,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -90994,6 +111354,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -92265,6 +112629,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -93409,19 +114517,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -93432,6 +114536,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -94470,6 +115578,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -96180,6 +118046,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -96821,6 +118693,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `AdditionalTools object { id, role, tools, type }` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -98120,7 +119994,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"message.output_text.logprobs"` - - `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` Text, image, or file inputs to the model, used to generate a response. @@ -98137,7 +120011,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `user` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -98920,19 +120794,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -98943,6 +120813,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -100214,6 +122088,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -101228,6 +123846,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -102647,7 +125271,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"content_filter"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A system (or developer) message inserted into the model's context. @@ -102660,7 +125284,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model, equivalent to a text input with the `developer` role. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -103443,19 +126067,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -103466,6 +126086,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -104737,6 +127361,750 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -105881,19 +129249,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -105904,6 +129268,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -106942,6 +130310,764 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -108652,6 +132778,12 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `prompt_cache_retention: optional "in_memory" or "24h"` The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - `"in_memory"` @@ -109293,6 +133425,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `AdditionalTools object { id, role, tools, type }` + - `Compaction object { id, encrypted_content, type, created_by }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). @@ -110456,7 +134590,7 @@ Returns a list of input items for a given response. A list of Response items. - - `data: array of ResponseInputMessageItem or ResponseOutputMessage or object { id, queries, status, 2 more } or 23 more` + - `data: array of ResponseInputMessageItem or ResponseOutputMessage or object { id, queries, status, 2 more } or 24 more` A list of items used to generate this response. @@ -111193,19 +135327,15 @@ Returns a list of input items for a given response. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -111216,6 +135346,10 @@ Returns a list of input items for a given response. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -112434,6 +136568,764 @@ Returns a list of input items for a given response. The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -113308,7 +138200,7 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ A list of Response items. - - `data: array of ResponseInputMessageItem or ResponseOutputMessage or object { id, queries, status, 2 more } or 23 more` + - `data: array of ResponseInputMessageItem or ResponseOutputMessage or object { id, queries, status, 2 more } or 24 more` A list of items used to generate this response. @@ -114045,19 +138937,15 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -114068,6 +138956,10 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -115286,6 +140178,764 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The identifier of the actor that created the item. + - `AdditionalTools object { id, role, tools, type }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + - `Reasoning object { id, summary, type, 3 more }` A description of the chain of thought used by a reasoning model while generating @@ -116117,7 +141767,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the conversation. -- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` Text, image, or file inputs to the model, used to generate a response @@ -116125,7 +141775,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok A text input to the model, equivalent to a text input with the `user` role. - - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` A list of one or many input items to the model, containing different content types. @@ -116907,19 +142557,15 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `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). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -116930,6 +142576,10 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -117250,77 +142900,1025 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of string or number` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `string` - - - `number` - - - `boolean` - - - `array of string or number` - - - `string` - - - `number` - + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `string` + + - `number` + + - `boolean` + + - `array of string or number` + + - `string` + + - `number` + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of ComparisonFilter or unknown` + + 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. + + - `unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + 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. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `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`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + 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 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + 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"` + + 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. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + 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. + + - `string` + + The container ID. + + - `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. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + 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`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of SkillReference or InlineSkill` + + An optional list of skills referenced by id or inline data. + + - `SkillReference object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `InlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: InlineSkillSource` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: "inline"` + + Defines an inline skill for this request. + + - `"inline"` + + - `LocalEnvironment object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of LocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `ContainerReference object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Text object { type }` + + Unconstrained free-form text. + + - `type: "text"` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `Grammar object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `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](https://platform.openai.com/docs/guides/tools-web-search). + + - `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`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `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. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: optional string` + + The unique ID of this tool search output. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` + + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `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](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + 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. + - `CompoundFilter object { filters, type }` Combine multiple filters using `and` or `or`. - - `filters: array of ComparisonFilter or unknown` - - 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. - - - `unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - `max_num_results: optional number` The maximum number of results to return. This number should be between 1 and 50 inclusive. @@ -117643,40 +144241,8 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `ContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `allowed_domains: array of string` - - A list of allowed domains when type is `allowlist`. - - - `type: "allowlist"` - - Allow outbound network access only to specified domains. Always `allowlist`. - - - `"allowlist"` - - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: string` - - The domain associated with the secret. - - - `name: string` - - The name of the secret to inject for the domain. - - - `value: string` - - The secret value to inject for the domain. - - `type: "code_interpreter"` The type of the code interpreter tool. Always `code_interpreter`. @@ -117833,128 +144399,10 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "container_auto"` - - Automatically creates a container for this request - - - `"container_auto"` - - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. - - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - The memory limit for the container. - - - `"1g"` - - - `"4g"` - - - `"16g"` - - - `"64g"` - - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `ContainerNetworkPolicyDisabled object { type }` - - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of SkillReference or InlineSkill` - - An optional list of skills referenced by id or inline data. - - - `SkillReference object { skill_id, type, version }` - - - `skill_id: string` - - The ID of the referenced skill. - - - `type: "skill_reference"` - - References a skill created with the /v1/skills endpoint. - - - `"skill_reference"` - - - `version: optional string` - - Optional skill version. Use a positive integer or 'latest'. Omit for default. - - - `InlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: string` - - Base64-encoded skill zip bundle. - - - `media_type: "application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `"application/zip"` - - - `type: "base64"` - - The type of the inline skill source. Must be `base64`. - - - `"base64"` - - - `type: "inline"` - - Defines an inline skill for this request. - - - `"inline"` - - `LocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of LocalSkill` - - An optional list of skills. - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `path: string` - - The path to the directory containing the skill. - - `ContainerReference object { container_id, type }` - - `container_id: string` - - The ID of the referenced container. - - - `type: "container_reference"` - - References a container created with the /v1/containers endpoint - - - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) @@ -117981,38 +144429,6 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The input format for the custom tool. Default is unconstrained text. - - `Text object { type }` - - Unconstrained free-form text. - - - `type: "text"` - - Unconstrained text format. Always `text`. - - - `"text"` - - - `Grammar object { definition, syntax, type }` - - A grammar defined by the user. - - - `definition: string` - - The grammar definition. - - - `syntax: "lark" or "regex"` - - The syntax of the grammar definition. One of `lark` or `regex`. - - - `"lark"` - - - `"regex"` - - - `type: "grammar"` - - Grammar format. Always `grammar`. - - - `"grammar"` - - `Namespace object { description, name, tools, type }` Groups function/custom tools under a shared namespace. @@ -118169,37 +144585,15 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `"apply_patch"` - - `type: "tool_search_output"` + - `type: "additional_tools"` - The item type. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `"tool_search_output"` + - `"additional_tools"` - `id: optional string` - The unique ID of this tool search output. - - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. - - - `execution: optional "server" or "client"` - - Whether tool search was executed by the server or by the client. - - - `"server"` - - - `"client"` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the tool search output. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + The unique ID of this additional tools item. - `Reasoning object { id, summary, type, 3 more }` @@ -118956,6 +145350,20 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok Whether to allow the model to run tool calls in parallel. +- `personality: optional string or "friendly" or "pragmatic"` + + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + + - `string` + + - `"friendly" or "pragmatic"` + + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + + - `"friendly"` + + - `"pragmatic"` + - `previous_response_id: optional string` The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`.