diff --git a/en/resources/responses/methods/create/index.md b/en/resources/responses/methods/create/index.md index a7fdc79..1c4e6cb 100644 --- a/en/resources/responses/methods/create/index.md +++ b/en/resources/responses/methods/create/index.md @@ -2,20 +2,14 @@ **post** `/responses` -Creates a model response. Provide [text](/docs/guides/text) or -[image](/docs/guides/images) inputs to generate [text](/docs/guides/text) -or [JSON](/docs/guides/structured-outputs) outputs. Have the model call -your own [custom code](/docs/guides/function-calling) or use built-in -[tools](/docs/guides/tools) like [web search](/docs/guides/tools-web-search) -or [file search](/docs/guides/tools-file-search) to use your own data -as input for the model's response. +Create a model response ### Body Parameters - `background: optional boolean` Whether to run the model response in the background. - [Learn more](/docs/guides/background). + [Learn more](https://platform.openai.com/docs/guides/background). - `context_management: optional array of object { type, compact_threshold }` @@ -74,24 +68,24 @@ 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 27 more` +- `input: optional string or ResponseInput` Text, image, or file inputs to the model, used to generate a response. Learn more: - - [Text inputs and outputs](/docs/guides/text) - - [Image inputs](/docs/guides/images) - - [File inputs](/docs/guides/pdf-files) - - [Conversation state](/docs/guides/conversation-state) - - [Function calling](/docs/guides/function-calling) + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) - `TextInput = string` 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 27 more` + - `ResponseInput = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` A list of one or many input items to the model, containing different content types. @@ -118,7 +112,7 @@ as input for the model's response. A list of one or many input items to the model, containing different content types. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -132,9 +126,19 @@ as input for the model's response. - `"input_text"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -162,7 +166,17 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -172,9 +186,11 @@ as input for the model's response. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -196,6 +212,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "user" or "assistant" or "system" or "developer"` The role of the message input. One of `user`, `assistant`, `system`, or @@ -275,7 +301,7 @@ as input for the model's response. The content of the output message. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `ResponseOutputText object { annotations, text, type, logprobs }` A text output from the model. @@ -379,15 +405,17 @@ as input for the model's response. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -395,15 +423,13 @@ as input for the model's response. - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `ResponseOutputRefusal object { refusal, type }` @@ -455,7 +481,7 @@ as input for the model's response. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -523,7 +549,7 @@ as input for the model's response. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -566,7 +592,7 @@ as input for the model's response. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -770,38 +796,193 @@ as input for the model's response. A click action. + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + - `DoubleClick object { keys, type, x, y }` A double click action. + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + - `Drag object { path, type, keys }` A drag action. + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + - `Keypress object { keys, type }` A collection of keypresses the model would like to perform. + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + - `Move object { type, x, y, keys }` A mouse move action. + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + - `Screenshot object { type }` A screenshot action. + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` A scroll action. + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + - `Type object { text, type }` An action to type in text. + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + - `Wait object { type }` A wait action. + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + - `ComputerCallOutput object { call_id, output, type, 3 more }` The output of a computer tool call. @@ -868,7 +1049,7 @@ as input for the model's response. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -961,10 +1142,10 @@ as input for the model's response. - `"web_search_call"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: string` @@ -988,6 +1169,26 @@ as input for the model's response. The unique ID of the function tool call. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the function to run. @@ -1003,7 +1204,7 @@ as input for the model's response. - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + - `FunctionCallOutput object { call_id, output, type, 3 more }` The output of a function tool call. @@ -1011,7 +1212,7 @@ as input for the model's response. The unique ID of the function tool call generated by the model. - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `output: string or ResponseFunctionCallOutputItemList` Text, image, or file output of the function tool call. @@ -1019,11 +1220,11 @@ as input for the model's response. A JSON string of the output of the function tool call. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `ResponseFunctionCallOutputItemList = array of ResponseFunctionCallOutputItem` An array of content outputs (text, image, file) for the function tool call. - - `ResponseInputTextContent object { text, type }` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -1037,9 +1238,19 @@ as input for the model's response. - `"input_text"` - - `ResponseInputImageContent object { type, detail, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` @@ -1067,7 +1278,17 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -1077,9 +1298,11 @@ as input for the model's response. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -1101,6 +1324,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `type: "function_call_output"` The type of the function tool call output. Always `function_call_output`. @@ -1111,6 +1344,30 @@ as input for the model's response. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -1161,11 +1418,11 @@ as input for the model's response. - `ToolSearchOutput object { tools, type, id, 3 more }` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by the tool search output. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -1179,7 +1436,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -1187,6 +1444,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -1195,6 +1460,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -1365,7 +1634,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -1422,10 +1691,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -1437,6 +1706,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -1469,7 +1746,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -1569,7 +1846,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -1655,6 +1932,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -1677,8 +1970,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -1707,13 +2011,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -1721,8 +2025,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -1791,7 +2101,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -1801,9 +2111,17 @@ as input for the model's response. - `"shell"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - `type: "container_auto"` @@ -1927,9 +2245,9 @@ as input for the model's response. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -1941,6 +2259,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -1997,11 +2323,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -2009,19 +2335,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -2033,6 +2373,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2131,7 +2479,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -2141,6 +2489,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The item type. Always `tool_search_output`. @@ -2181,11 +2537,11 @@ as input for the model's response. - `"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` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` A list of additional tools made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -2199,7 +2555,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -2207,6 +2563,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -2215,6 +2579,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -2318,7 +2686,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -2375,10 +2743,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -2390,6 +2758,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -2422,7 +2798,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -2522,7 +2898,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -2576,6 +2952,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -2598,8 +2990,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -2628,13 +3031,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -2642,8 +3045,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -2712,7 +3121,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -2722,6 +3131,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -2730,9 +3147,9 @@ as input for the model's response. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -2744,6 +3161,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2768,11 +3193,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -2780,19 +3205,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -2804,6 +3243,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2902,7 +3349,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -2912,6 +3359,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The item type. Always `additional_tools`. @@ -2927,13 +3382,13 @@ as input for the model's response. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -2985,7 +3440,7 @@ as input for the model's response. - `Compaction object { encrypted_content, type, id }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -3186,7 +3641,7 @@ as input for the model's response. - `"incomplete"` - - `ShellCall object { action, call_id, type, 3 more }` + - `ShellCall object { action, call_id, type, 4 more }` A tool representing a request to execute one or more shell commands. @@ -3220,6 +3675,30 @@ as input for the model's response. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `environment: optional LocalEnvironment or ContainerReference` The environment to execute the shell commands in. @@ -3238,7 +3717,7 @@ as input for the model's response. - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 3 more }` + - `ShellCallOutput object { call_id, output, type, 4 more }` The streamed output items emitted by a shell tool call. @@ -3296,6 +3775,30 @@ as input for the model's response. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `max_output_length: optional number` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -3310,7 +3813,7 @@ as input for the model's response. - `"incomplete"` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` A tool call representing a request to create, delete, or update files using diff patches. @@ -3390,7 +3893,31 @@ as input for the model's response. The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` The streamed output emitted by an apply patch tool call. @@ -3416,6 +3943,30 @@ as input for the model's response. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `output: optional string` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -3567,7 +4118,7 @@ as input for the model's response. - `"failed"` - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -3588,15 +4139,15 @@ as input for the model's response. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -3610,7 +4161,31 @@ as input for the model's response. The unique ID of the custom tool call output in the OpenAI platform. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -3636,6 +4211,26 @@ as input for the model's response. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. @@ -3664,6 +4259,58 @@ as input for the model's response. - `"item_reference"` + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `"program_output"` + - `instructions: optional string` A system (or developer) message inserted into the model's context. @@ -3674,7 +4321,7 @@ as input for the model's response. - `max_output_tokens: optional number` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - `max_tool_calls: optional number` @@ -3693,12 +4340,18 @@ as input for the model's response. Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](/docs/models) + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `string` - - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more` + - `ChatModel = "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` + + - `"gpt-5.6-sol"` + + - `"gpt-5.6-terra"` + + - `"gpt-5.6-luna"` - `"gpt-5.4"` @@ -3886,7 +4539,7 @@ as input for the model's response. - `"gpt-5.1-codex-max"` -- `moderation: optional object { model }` +- `moderation: optional object { model, policy }` Configuration for running moderation on the input and output of this response. @@ -3894,6 +4547,30 @@ as input for the model's response. The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `policy: optional object { input, output }` + + The policy to apply to moderated response input and output. + + - `input: optional object { mode }` + + The moderation policy for the response input. + + - `mode: "score" or "block"` + + - `"score"` + + - `"block"` + + - `output: optional object { mode }` + + The moderation policy for the response output. + + - `mode: "score" or "block"` + + - `"score"` + + - `"block"` + - `parallel_tool_calls: optional boolean` Whether to allow the model to run tool calls in parallel. @@ -3902,12 +4579,12 @@ as input for the model's response. 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`. + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt: optional ResponsePrompt` Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` @@ -3921,15 +4598,15 @@ as input for the model's response. - `string` - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -3939,11 +4616,34 @@ as input for the model's response. - `prompt_cache_key: optional string` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + +- `prompt_cache_options: optional object { mode, ttl }` + + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `mode: optional "implicit" or "explicit"` + + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + + - `"implicit"` + + - `"explicit"` + + - `ttl: optional "30m"` + + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + + - `"30m"` - `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). + Deprecated. Use `prompt_cache_options.ttl` instead. + + 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](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. 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: @@ -3976,16 +4676,13 @@ as input for the model's response. - `effort: optional ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `"none"` @@ -3999,6 +4696,8 @@ as input for the model's response. - `"xhigh"` + - `"max"` + - `generate_summary: optional "auto" or "concise" or "detailed"` **Deprecated:** use `summary` instead. @@ -4013,6 +4712,24 @@ as input for the model's response. - `"detailed"` + - `mode: optional string or "standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `string` + + - `"standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + - `summary: optional "auto" or "concise" or "detailed"` A summary of the reasoning performed by the model. This can be @@ -4030,7 +4747,7 @@ as input for the model's response. - `safety_identifier: optional string` A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - `service_tier: optional "auto" or "default" or "flex" or 2 more` @@ -4038,7 +4755,7 @@ as input for the model's response. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - When not set, the default behavior is 'auto'. When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. @@ -4062,7 +4779,7 @@ as input for the model's response. If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](/docs/api-reference/responses-streaming) + See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) for more information. - `stream_options: optional object { include_obfuscation }` @@ -4089,8 +4806,8 @@ as input for the model's response. Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - `format: optional ResponseFormatTextConfig` @@ -4098,7 +4815,7 @@ as input for the model's response. Configuring `{ "type": "json_schema" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](/docs/guides/structured-outputs). + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). The default format is `{ "type": "text" }` with no additional options. @@ -4121,7 +4838,7 @@ as input for the model's response. - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: string` @@ -4150,7 +4867,7 @@ as input for the model's response. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs - guide](/docs/guides/structured-outputs). + guide](https://platform.openai.com/docs/guides/structured-outputs). - `ResponseFormatJSONObject object { type }` @@ -4177,7 +4894,7 @@ as input for the model's response. - `"high"` -- `tool_choice: optional ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 5 more` +- `tool_choice: optional ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -4240,12 +4957,12 @@ as input for the model's response. - `ToolChoiceTypes object { type }` Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - `type: "file_search" or "web_search_preview" or "computer" or 5 more` The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + [built-in tools](https://platform.openai.com/docs/guides/tools). Allowed values are: @@ -4319,6 +5036,14 @@ as input for the model's response. - `"custom"` + - `SpecificProgrammaticToolCallingParam object { type }` + + - `type: "programmatic_tool_calling"` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ToolChoiceApplyPatch object { type }` Forces the model to call the apply_patch tool when executing a tool call. @@ -4339,7 +5064,7 @@ as input for the model's response. - `"shell"` -- `tools: optional array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` +- `tools: optional array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. @@ -4347,19 +5072,19 @@ as input for the model's response. We support the following categories of tools: - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](/docs/guides/tools-web-search) - or [file search](/docs/guides/tools-file-search). Learn more about - [built-in tools](/docs/guides/tools). + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - **MCP Tools**: Integrations with third-party systems via custom MCP servers or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](/docs/guides/tools-connectors-mcp). + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code with strongly typed arguments and outputs. Learn more about - [function calling](/docs/guides/function-calling). You can also use + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use custom tools to call your own code. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -4373,7 +5098,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -4381,6 +5106,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -4389,6 +5122,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -4492,7 +5229,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -4549,10 +5286,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -4564,6 +5301,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -4596,7 +5341,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -4696,7 +5441,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -4750,6 +5495,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -4772,8 +5533,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -4802,13 +5574,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -4816,8 +5588,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -4886,7 +5664,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -4896,6 +5674,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -4904,9 +5690,9 @@ as input for the model's response. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -4918,6 +5704,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -4942,11 +5736,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -4954,19 +5748,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -4978,7 +5786,15 @@ as input for the model's response. - `"custom"` - - `defer_loading: optional boolean` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -5076,7 +5892,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -5086,6 +5902,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `top_logprobs: optional number` An integer between 0 and 20 specifying the maximum number of most likely @@ -5120,7 +5944,7 @@ as input for the model's response. This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). ### Returns @@ -5138,7 +5962,7 @@ as input for the model's response. An error object returned when the model fails to generate a Response. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 15 more` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` The error code for the response. @@ -5148,6 +5972,8 @@ as input for the model's response. - `"invalid_prompt"` + - `"bio_policy"` + - `"vector_store_timeout"` - `"invalid_image"` @@ -5194,7 +6020,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 27 more` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` A system (or developer) message inserted into the model's context. @@ -5207,7 +6033,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 27 more` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` A list of one or many input items to the model, containing different content types. @@ -5234,7 +6060,7 @@ as input for the model's response. A list of one or many input items to the model, containing different content types. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -5248,9 +6074,19 @@ as input for the model's response. - `"input_text"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -5278,7 +6114,17 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -5288,9 +6134,11 @@ as input for the model's response. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -5312,6 +6160,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "user" or "assistant" or "system" or "developer"` The role of the message input. One of `user`, `assistant`, `system`, or @@ -5391,7 +6249,7 @@ as input for the model's response. The content of the output message. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `ResponseOutputText object { annotations, text, type, logprobs }` A text output from the model. @@ -5495,15 +6353,17 @@ as input for the model's response. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -5511,15 +6371,13 @@ as input for the model's response. - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `ResponseOutputRefusal object { refusal, type }` @@ -5571,7 +6429,7 @@ as input for the model's response. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -5639,7 +6497,7 @@ as input for the model's response. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -5682,7 +6540,7 @@ as input for the model's response. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -5886,38 +6744,193 @@ as input for the model's response. A click action. + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + - `DoubleClick object { keys, type, x, y }` A double click action. + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + - `Drag object { path, type, keys }` A drag action. + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + - `Keypress object { keys, type }` A collection of keypresses the model would like to perform. + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + - `Move object { type, x, y, keys }` A mouse move action. + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + - `Screenshot object { type }` A screenshot action. + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` A scroll action. + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + - `Type object { text, type }` An action to type in text. + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + - `Wait object { type }` A wait action. + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + - `ComputerCallOutput object { call_id, output, type, 3 more }` The output of a computer tool call. @@ -5984,7 +6997,7 @@ as input for the model's response. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -6077,10 +7090,10 @@ as input for the model's response. - `"web_search_call"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: string` @@ -6104,6 +7117,26 @@ as input for the model's response. The unique ID of the function tool call. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the function to run. @@ -6119,7 +7152,7 @@ as input for the model's response. - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + - `FunctionCallOutput object { call_id, output, type, 3 more }` The output of a function tool call. @@ -6127,7 +7160,7 @@ as input for the model's response. The unique ID of the function tool call generated by the model. - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `output: string or ResponseFunctionCallOutputItemList` Text, image, or file output of the function tool call. @@ -6135,11 +7168,11 @@ as input for the model's response. A JSON string of the output of the function tool call. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `ResponseFunctionCallOutputItemList = array of ResponseFunctionCallOutputItem` An array of content outputs (text, image, file) for the function tool call. - - `ResponseInputTextContent object { text, type }` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -6153,9 +7186,19 @@ as input for the model's response. - `"input_text"` - - `ResponseInputImageContent object { type, detail, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` @@ -6183,7 +7226,17 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -6193,9 +7246,11 @@ as input for the model's response. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -6217,6 +7272,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `type: "function_call_output"` The type of the function tool call output. Always `function_call_output`. @@ -6227,6 +7292,30 @@ as input for the model's response. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -6277,11 +7366,11 @@ as input for the model's response. - `ToolSearchOutput object { tools, type, id, 3 more }` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by the tool search output. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -6295,7 +7384,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -6303,6 +7392,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -6311,6 +7408,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -6481,7 +7582,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -6538,10 +7639,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -6553,6 +7654,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -6585,7 +7694,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -6685,7 +7794,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -6771,15 +7880,31 @@ as input for the model's response. - `"code_interpreter"` - - `ImageGeneration object { type, action, background, 9 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A tool that generates images using the GPT image models. + The tool invocation context(s). - - `type: "image_generation"` + - `"direct"` - The type of the image generation tool. Always `image_generation`. + - `"programmatic"` - - `"image_generation"` + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `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"` @@ -6793,8 +7918,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -6823,13 +7959,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -6837,8 +7973,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -6907,7 +8049,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -6917,6 +8059,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -7043,9 +8193,9 @@ as input for the model's response. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -7057,6 +8207,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -7113,11 +8271,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -7125,19 +8283,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -7149,6 +8321,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -7247,7 +8427,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -7257,6 +8437,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The item type. Always `tool_search_output`. @@ -7297,11 +8485,11 @@ as input for the model's response. - `"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` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` A list of additional tools made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -7315,7 +8503,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -7323,6 +8511,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -7331,6 +8527,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -7434,7 +8634,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -7491,10 +8691,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -7506,6 +8706,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -7538,7 +8746,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -7638,7 +8846,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -7692,6 +8900,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -7714,8 +8938,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -7744,13 +8979,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -7758,8 +8993,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -7828,7 +9069,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -7838,6 +9079,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -7846,9 +9095,9 @@ as input for the model's response. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -7860,6 +9109,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -7884,11 +9141,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -7896,19 +9153,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -7920,6 +9191,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -8018,7 +9297,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -8028,6 +9307,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The item type. Always `additional_tools`. @@ -8043,13 +9330,13 @@ as input for the model's response. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -8101,7 +9388,7 @@ as input for the model's response. - `Compaction object { encrypted_content, type, id }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -8302,7 +9589,7 @@ as input for the model's response. - `"incomplete"` - - `ShellCall object { action, call_id, type, 3 more }` + - `ShellCall object { action, call_id, type, 4 more }` A tool representing a request to execute one or more shell commands. @@ -8336,6 +9623,30 @@ as input for the model's response. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `environment: optional LocalEnvironment or ContainerReference` The environment to execute the shell commands in. @@ -8354,7 +9665,7 @@ as input for the model's response. - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 3 more }` + - `ShellCallOutput object { call_id, output, type, 4 more }` The streamed output items emitted by a shell tool call. @@ -8412,6 +9723,30 @@ as input for the model's response. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `max_output_length: optional number` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -8426,7 +9761,7 @@ as input for the model's response. - `"incomplete"` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` A tool call representing a request to create, delete, or update files using diff patches. @@ -8506,7 +9841,31 @@ as input for the model's response. The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` The streamed output emitted by an apply patch tool call. @@ -8532,6 +9891,30 @@ as input for the model's response. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `output: optional string` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -8683,7 +10066,7 @@ as input for the model's response. - `"failed"` - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -8704,15 +10087,15 @@ as input for the model's response. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -8726,7 +10109,31 @@ as input for the model's response. The unique ID of the custom tool call output in the OpenAI platform. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -8752,6 +10159,26 @@ as input for the model's response. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. @@ -8780,6 +10207,58 @@ as input for the model's response. - `"item_reference"` + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `"program_output"` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -8793,12 +10272,18 @@ as input for the model's response. Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](/docs/models) + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `string` - - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 75 more` + - `ChatModel = "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` + + - `"gpt-5.6-sol"` + + - `"gpt-5.6-terra"` + + - `"gpt-5.6-luna"` - `"gpt-5.4"` @@ -9010,7 +10495,7 @@ as input for the model's response. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -9075,10 +10560,10 @@ as input for the model's response. The text that was retrieved from the file. - - `FunctionCall object { arguments, call_id, name, 4 more }` + - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: string` @@ -9102,6 +10587,26 @@ as input for the model's response. The unique ID of the function tool call. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the function to run. @@ -9117,7 +10622,7 @@ as input for the model's response. - `"incomplete"` - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -9140,15 +10645,15 @@ as input for the model's response. Text, image, or file output of the function call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -9169,6 +10674,30 @@ as input for the model's response. - `"function_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -9176,7 +10705,7 @@ as input for the model's response. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -9272,7 +10801,7 @@ as input for the model's response. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -9315,10 +10844,201 @@ as input for the model's response. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `Click object { button, type, x, 2 more }` A click action. + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + - `actions: optional ComputerActionList` Flattened batched actions for `computer_use`. Each action includes an @@ -9383,13 +11103,13 @@ as input for the model's response. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -9401,6 +11121,8 @@ as input for the model's response. The type of the object. Always `summary_text`. + - `"summary_text"` + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -9415,28 +11137,80 @@ as input for the model's response. The reasoning text from the model. - - `type: "reasoning_text"` + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` - The type of the reasoning text. Always `reasoning_text`. + The unique ID of the program output item. - - `"reasoning_text"` + - `call_id: string` - - `encrypted_content: optional string` + The call ID of the program item. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `result: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The result produced by the program item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: "completed" or "incomplete"` - - `"in_progress"` + The terminal status of the program output item. - `"completed"` - `"incomplete"` + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - `id: string` @@ -9507,11 +11281,11 @@ as input for the model's response. - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by tool search. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -9525,7 +11299,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -9533,6 +11307,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -9541,6 +11323,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -9644,7 +11430,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -9701,10 +11487,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -9716,6 +11502,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -9748,7 +11542,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -9848,7 +11642,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -9902,6 +11696,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -9924,8 +11734,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -9954,13 +11775,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -9968,8 +11789,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -10038,7 +11865,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -10048,6 +11875,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -10056,9 +11891,9 @@ as input for the model's response. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -10070,6 +11905,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -10094,11 +11937,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -10106,19 +11949,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -10130,6 +11987,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -10228,7 +12093,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -10238,6 +12103,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The type of the item. Always `tool_search_output`. @@ -10274,11 +12147,11 @@ as input for the model's response. - `"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` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The additional tool definitions made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -10292,7 +12165,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -10300,6 +12173,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -10308,6 +12189,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -10411,7 +12296,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -10468,10 +12353,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -10483,6 +12368,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -10515,7 +12408,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -10615,7 +12508,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -10669,6 +12562,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -10691,8 +12600,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -10721,13 +12641,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -10735,8 +12655,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -10805,7 +12731,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -10815,6 +12741,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -10823,9 +12757,9 @@ as input for the model's response. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -10837,6 +12771,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -10861,11 +12803,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -10873,19 +12815,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -10897,6 +12853,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -10995,7 +12959,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -11005,6 +12969,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The type of the item. Always `additional_tools`. @@ -11013,7 +12985,7 @@ as input for the model's response. - `Compaction object { id, encrypted_content, type, created_by }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` @@ -11218,7 +13190,7 @@ as input for the model's response. - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -11286,11 +13258,31 @@ as input for the model's response. - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -11366,11 +13358,31 @@ as input for the model's response. - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -11450,11 +13462,31 @@ as input for the model's response. - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -11480,6 +13512,26 @@ as input for the model's response. - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -11635,7 +13687,7 @@ as input for the model's response. Optional reason for the decision. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -11661,11 +13713,31 @@ as input for the model's response. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { id, call_id, output, 3 more }` + - `CustomToolCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -11688,15 +13760,15 @@ as input for the model's response. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -11717,6 +13789,30 @@ as input for the model's response. - `"custom_tool_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -11730,7 +13826,7 @@ as input for the model's response. What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 5 more` + - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -11793,12 +13889,12 @@ as input for the model's response. - `ToolChoiceTypes object { type }` Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - `type: "file_search" or "web_search_preview" or "computer" or 5 more` The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + [built-in tools](https://platform.openai.com/docs/guides/tools). Allowed values are: @@ -11872,6 +13968,14 @@ as input for the model's response. - `"custom"` + - `SpecificProgrammaticToolCallingParam object { type }` + + - `type: "programmatic_tool_calling"` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ToolChoiceApplyPatch object { type }` Forces the model to call the apply_patch tool when executing a tool call. @@ -11892,7 +13996,7 @@ as input for the model's response. - `"shell"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. @@ -11900,19 +14004,19 @@ as input for the model's response. We support the following categories of tools: - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](/docs/guides/tools-web-search) - or [file search](/docs/guides/tools-file-search). Learn more about - [built-in tools](/docs/guides/tools). + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - **MCP Tools**: Integrations with third-party systems via custom MCP servers or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](/docs/guides/tools-connectors-mcp). + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code with strongly typed arguments and outputs. Learn more about - [function calling](/docs/guides/function-calling). You can also use + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use custom tools to call your own code. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 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). @@ -11926,7 +14030,7 @@ as input for the model's response. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -11934,6 +14038,14 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -11942,6 +14054,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this 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). @@ -12045,7 +14161,7 @@ as input for the model's response. - `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). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -12102,10 +14218,10 @@ as input for the model's response. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -12117,6 +14233,14 @@ as input for the model's response. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -12149,7 +14273,7 @@ as input for the model's response. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -12249,7 +14373,7 @@ as input for the model's response. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -12303,6 +14427,22 @@ as input for the model's response. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -12325,8 +14465,19 @@ as input for the model's response. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -12355,13 +14506,13 @@ as input for the model's response. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -12369,8 +14520,14 @@ as input for the model's response. - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -12439,7 +14596,7 @@ as input for the model's response. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -12449,6 +14606,14 @@ as input for the model's response. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -12457,9 +14622,9 @@ as input for the model's response. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -12471,6 +14636,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -12495,11 +14668,11 @@ as input for the model's response. 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 }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -12507,19 +14680,33 @@ as input for the model's response. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -12531,6 +14718,14 @@ as input for the model's response. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -12629,7 +14824,7 @@ as input for the model's response. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -12639,6 +14834,14 @@ as input for the model's response. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `top_p: number` An alternative to sampling with temperature, called nucleus sampling, @@ -12651,7 +14854,7 @@ as input for the model's response. - `background: optional boolean` Whether to run the model response in the background. - [Learn more](/docs/guides/background). + [Learn more](https://platform.openai.com/docs/guides/background). - `completed_at: optional number` @@ -12668,7 +14871,7 @@ as input for the model's response. - `max_output_tokens: optional number` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - `max_tool_calls: optional number` @@ -12790,22 +14993,16 @@ as input for the model's response. - `"error"` - - `output_text: optional string` - - SDK-only convenience property that contains the aggregated text output - from all `output_text` items in the `output` array, if any are present. - Supported in the Python and JavaScript SDKs. - - `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`. + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt: optional ResponsePrompt` Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` @@ -12819,15 +15016,15 @@ as input for the model's response. - `string` - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -12837,11 +15034,34 @@ as input for the model's response. - `prompt_cache_key: optional string` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `prompt_cache_options: optional object { mode, ttl }` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: "implicit" or "explicit"` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: "30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` - `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). + Deprecated. Use `prompt_cache_options.ttl` instead. + + 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](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. 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: @@ -12874,16 +15094,13 @@ as input for the model's response. - `effort: optional ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `"none"` @@ -12897,6 +15114,8 @@ as input for the model's response. - `"xhigh"` + - `"max"` + - `generate_summary: optional "auto" or "concise" or "detailed"` **Deprecated:** use `summary` instead. @@ -12911,6 +15130,24 @@ as input for the model's response. - `"detailed"` + - `mode: optional string or "standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `string` + + - `"standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + - `summary: optional "auto" or "concise" or "detailed"` A summary of the reasoning performed by the model. This can be @@ -12928,7 +15165,7 @@ as input for the model's response. - `safety_identifier: optional string` A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - `service_tier: optional "auto" or "default" or "flex" or 2 more` @@ -12936,7 +15173,7 @@ as input for the model's response. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - When not set, the default behavior is 'auto'. When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. @@ -12973,8 +15210,8 @@ as input for the model's response. Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - `format: optional ResponseFormatTextConfig` @@ -12982,7 +15219,7 @@ as input for the model's response. Configuring `{ "type": "json_schema" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](/docs/guides/structured-outputs). + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). The default format is `{ "type": "text" }` with no additional options. @@ -13005,7 +15242,7 @@ as input for the model's response. - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: string` @@ -13034,7 +15271,7 @@ as input for the model's response. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs - guide](/docs/guides/structured-outputs). + guide](https://platform.openai.com/docs/guides/structured-outputs). - `ResponseFormatJSONObject object { type }` @@ -13091,14 +15328,18 @@ as input for the model's response. The number of input tokens. - - `input_tokens_details: object { cached_tokens }` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` A detailed breakdown of the input tokens. + - `cache_write_tokens: number` + + The number of input tokens that were written to the cache. + - `cached_tokens: number` The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - `output_tokens: number` @@ -13120,7 +15361,7 @@ as input for the model's response. This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). ### Example @@ -13170,6 +15411,8 @@ curl https://api.openai.com/v1/responses \ "type": "file_citation" } ], + "text": "text", + "type": "output_text", "logprobs": [ { "token": "token", @@ -13187,9 +15430,7 @@ curl https://api.openai.com/v1/responses \ } ] } - ], - "text": "text", - "type": "output_text" + ] } ], "role": "assistant", @@ -13209,8 +15450,14 @@ curl https://api.openai.com/v1/responses \ }, "strict": true, "type": "function", + "allowed_callers": [ + "direct" + ], "defer_loading": true, - "description": "description" + "description": "description", + "output_schema": { + "foo": "bar" + } } ], "top_p": 1, @@ -13265,11 +15512,16 @@ curl https://api.openai.com/v1/responses \ "version": "version" }, "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, "prompt_cache_retention": "in_memory", "reasoning": { "context": "auto", "effort": "none", "generate_summary": "auto", + "mode": "standard", "summary": "auto" }, "safety_identifier": "safety-identifier-1234", @@ -13286,6 +15538,7 @@ curl https://api.openai.com/v1/responses \ "usage": { "input_tokens": 0, "input_tokens_details": { + "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0, @@ -13472,7 +15725,8 @@ curl https://api.openai.com/v1/responses \ {"type": "input_text", "text": "what is in this file?"}, { "type": "input_file", - "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf" + "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", + "detail": "auto" } ] }