GET

/v1/schemas/openai/chat/responses/input_tokens

Accept:

kind inputactivity chathash 43eead7d…extracted Nov 5, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `898eefefea6b5dc52da42f5628a64a0ffba65d850282e1cb59ab459f7e356f92` { "fetchedAt": 1793851833, "extractorVersion": "1", "verifiedAt": null }

Request body

12 properties · 0 required · 199 $defs

property	type	description	constraints
model	string	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](https://developers.openai.com/api/docs/models) to browse …	nullable
input	string \| InputItem[]	Text, image, or file inputs to the model, used to generate a response	nullable
previous_response_id	string	The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`.	nullable
tools	Tool[]	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.	nullable
text	ResponseTextParam	Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - [Structured Outputs](https://developers.openai.com/api/docs/guide…	nullable
reasoning	Reasoning	gpt-5 and o-series models only Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).	nullable
truncation	enum	The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `…	auto \| disabled · deprecated
instructions	string	A system (or developer) message inserted into the model's context. When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) mess…	nullable
personality	string \| enum	A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters.
conversation	string \| Conversation object	The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. Input items and output items from this response are automatically added to this conversation after this response completes.	nullable
tool_choice	enum \| Allowed tools \| Hosted tool \| …	Controls which tool the model should use, if any.	nullable
parallel_tool_calls	boolean	Whether to allow the model to run tool calls in parallel.	nullable

Types

199 $defs

AdditionalToolsItemParamobject

id	string	The unique ID of this additional tools item.	nullable
type*	enum	The item type. Always `additional_tools`.	additional_tools · default: "additional_tools"
role*	enum	The role that provided the additional tools. Only `developer` is supported.	developer · default: "developer"
tools*	Tool[]	A list of additional tools made available at this item.

AnnotationFile citation | URL citation | Container file citation | …

An annotation that applies to a span of output text.

ApplyPatchCallOutputStatusParamenum

Outcome values reported for apply_patch tool call outputs.

completed | failed

ApplyPatchCallStatusParamenum

Status values reported for apply_patch tool calls.

in_progress | completed

ApplyPatchCreateFileOperationParamobject

Instruction for creating a new file via the apply_patch tool.

type*	enum	The operation type. Always `create_file`.	create_file · default: "create_file"
path*	string	Path of the file to create relative to the workspace root.	length ≥ 1
diff*	string	Unified diff content to apply when creating the file.	length ≤ 10485760

ApplyPatchDeleteFileOperationParamobject

Instruction for deleting an existing file via the apply_patch tool.

type*	enum	The operation type. Always `delete_file`.	delete_file · default: "delete_file"
path*	string	Path of the file to delete relative to the workspace root.	length ≥ 1

ApplyPatchOperationParamApply patch create file operation | Apply patch delete file operation | Apply patch update file operation

One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool.

ApplyPatchToolCallItemParamobject

A tool call representing a request to create, delete, or update files using diff patches.

type*	enum	The type of the item. Always `apply_patch_call`.	apply_patch_call · default: "apply_patch_call"
id	string	The unique ID of the apply patch tool call. Populated when this item is returned via API.	nullable
call_id*	string	The unique ID of the apply patch tool call generated by the model.	length ≥ 1 · length ≤ 64
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the apply patch tool call. One of `in_progress` or `completed`.	in_progress \| completed
operation*	Apply patch create file operation \| Apply patch delete file operation \| Apply patch update file operation	The specific create, delete, or update instruction for the apply_patch tool call.

ApplyPatchToolCallOutputItemParamobject

The streamed output emitted by an apply patch tool call.

type*	enum	The type of the item. Always `apply_patch_call_output`.	apply_patch_call_output · default: "apply_patch_call_output"
id	string	The unique ID of the apply patch tool call output. Populated when this item is returned via API.	nullable
call_id*	string	The unique ID of the apply patch tool call generated by the model.	length ≥ 1 · length ≤ 64
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the apply patch tool call output. One of `completed` or `failed`.	completed \| failed
output	string	Optional human-readable log text from the apply patch tool (e.g., patch results or errors).	length ≤ 10485760 · nullable

ApplyPatchToolParamobject

Allows the assistant to create, delete, or update files using unified diffs.

type*	enum	The type of the tool. Always `apply_patch`.	apply_patch · default: "apply_patch"
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

ApplyPatchUpdateFileOperationParamobject

Instruction for updating an existing file via the apply_patch tool.

type*	enum	The operation type. Always `update_file`.	update_file · default: "update_file"
path*	string	Path of the file to update relative to the workspace root.	length ≥ 1
diff*	string	Unified diff content to apply to the existing file.	length ≤ 10485760

ApproximateLocationobject

type*	enum	The type of location approximation. Always `approximate`.	approximate · default: "approximate"
country	string	The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.	nullable
region	string	Free text input for the region of the user, e.g. `California`.	nullable
city	string	Free text input for the city of the user, e.g. `San Francisco`.	nullable
timezone	string	The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.	nullable

ClickParamobject

A click action.

type*	enum	Specifies the event type. For a click action, this property is always `click`.	click · default: "click"
button*	enum	Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.	left \| right \| wheel \| back \| forward
x*	integer	The x-coordinate where the click occurred.
y*	integer	The y-coordinate where the click occurred.
keys	string[]	The keys being held while clicking.	nullable

CodeInterpreterContainerAutoobject

Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

type*	enum	Always `auto`.	auto · default: "auto"
file_ids	string[]	An optional list of uploaded files to make available to your code.	items ≤ 50
memory_limit	enum	The memory limit for the code interpreter container.	1g \| 4g \| 16g \| 64g · nullable
network_policy	object \| object	Network access policy for the container.

CodeInterpreterOutputImageobject

The image output from the code interpreter.

type*	enum	The type of the output. Always `image`.	image · default: "image"
url*	string	The URL of the image output from the code interpreter.	format: uri

CodeInterpreterOutputLogsobject

The logs output from the code interpreter.

type*	enum	The type of the output. Always `logs`.	logs · default: "logs"
logs*	string	The logs output from the code interpreter.

CodeInterpreterToolobject

A tool that runs Python code to help generate a response to a prompt.

type*	enum	The type of the code interpreter tool. Always `code_interpreter`.	code_interpreter
container*	string \| CodeInterpreterToolAuto	The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

CodeInterpreterToolCallobject

A tool call to run code.

type*	enum	The type of the code interpreter tool call. Always `code_interpreter_call`.	code_interpreter_call · default: "code_interpreter_call"
id*	string	The unique ID of the code interpreter tool call.
status*	enum	The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.	in_progress \| completed \| incomplete \| interpreting \| failed
container_id*	string	The ID of the container used to run the code.
code*	string	The code to run, or null if not available.	nullable
outputs*	CodeInterpreterOutputLogs \| CodeInterpreterOutputImage[]	The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available.	nullable

CompactionSummaryItemParamobject

A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact).

id	string	The ID of the compaction item.	nullable
type*	enum	The type of the item. Always `compaction`.	compaction · default: "compaction"
encrypted_content*	string	The encrypted content of the compaction summary.	length ≤ 104857600

CompactionTriggerItemParamobject

Compacts the current context. Must be the final input item.

id	string	The unique ID of this compaction trigger.	nullable
type*	enum	The type of the item. Always `compaction_trigger`.	compaction_trigger · default: "compaction_trigger"

ComparisonFilterobject

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

type*	enum	Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in	eq \| ne \| gt \| gte \| lt \| lte · +2 more · default: "eq"
key*	string	The key to compare against the value.
value*	string \| number \| boolean \| …	The value to compare against the attribute key; supports string, number, or boolean types.

ComparisonFilterValueItemsstring | number

CompoundFilterobject

Combine multiple filters using `and` or `or`.

type*	enum	Type of operation: `and` or `or`.	and \| or
filters*	ComparisonFilter \| any[]	Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

ComputerActionClick | DoubleClick | Drag | …

ComputerActionListComputerAction[]

Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields.

ComputerCallOutputItemParamobject

The output of a computer tool call.

id	string	The ID of the computer tool call output.	nullable
call_id*	string	The ID of the computer tool call that produced the output.	length ≥ 1 · length ≤ 64
type*	enum	The type of the computer tool call output. Always `computer_call_output`.	computer_call_output · default: "computer_call_output"
output*	ComputerScreenshotImage	A computer screenshot image used with the computer use tool.
acknowledged_safety_checks	ComputerCallSafetyCheckParam[]	The safety checks reported by the API that have been acknowledged by the developer.	nullable
status	enum	The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.	in_progress \| completed \| incomplete · nullable

ComputerCallSafetyCheckParamobject

A pending safety check for the computer call.

id*	string	The ID of the pending safety check.
code	string	The type of the pending safety check.	nullable
message	string	Details about the pending safety check.	nullable

ComputerEnvironmentenum

windows | mac | linux | ubuntu | browser

ComputerScreenshotImageobject

A computer screenshot image used with the computer use tool.

type*	enum	Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.	computer_screenshot · default: "computer_screenshot"
image_url	string	The URL of the screenshot image.	format: uri
file_id	string	The identifier of an uploaded file that contains the screenshot.

ComputerToolobject

A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).

type*

enum

The type of the computer tool. Always `computer`.

computer · default: "computer"

ComputerToolCallobject

A tool call to a computer use tool. See the [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information.

type*	enum	The type of the computer call. Always `computer_call`.	computer_call · default: "computer_call"
id*	string	The unique ID of the computer call.
call_id*	string	An identifier used when responding to the tool call with output.
action	Click \| DoubleClick \| Drag \| …
actions	ComputerAction[]	Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields.
pending_safety_checks*	ComputerCallSafetyCheckParam[]	The pending safety checks for the computer call.
status*	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

ComputerUsePreviewToolobject

A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).

type*	enum	The type of the computer use tool. Always `computer_use_preview`.	computer_use_preview · default: "computer_use_preview"
environment*	enum	The type of computer environment to control.	windows \| mac \| linux \| ubuntu \| browser
display_width*	integer	The width of the computer display.
display_height*	integer	The height of the computer display.

ContainerAutoParamobject

type*	enum	Automatically creates a container for this request	container_auto · default: "container_auto"
file_ids	string[]	An optional list of uploaded files to make available to your code.	items ≤ 50
memory_limit	enum	The memory limit for the container.	1g \| 4g \| 16g \| 64g · nullable
network_policy	object \| object	Network access policy for the container.
skills	SkillReferenceParam \| InlineSkillParam[]	An optional list of skills referenced by id or inline data.	items ≤ 200

ContainerFileCitationBodyobject

A citation for a container file used to generate a model response.

type*	enum	The type of the container file citation. Always `container_file_citation`.	container_file_citation · default: "container_file_citation"
container_id*	string	The ID of the container file.
file_id*	string	The ID of the file.
start_index*	integer	The index of the first character of the container file citation in the message.
end_index*	integer	The index of the last character of the container file citation in the message.
filename*	string	The filename of the container file cited.

ContainerNetworkPolicyAllowlistParamobject

type*	enum	Allow outbound network access only to specified domains. Always `allowlist`.	allowlist · default: "allowlist"
allowed_domains*	string[]	A list of allowed domains when type is `allowlist`.	items ≥ 1
domain_secrets	ContainerNetworkPolicyDomainSecretParam[]	Optional domain-scoped secrets for allowlisted domains.	items ≥ 1

ContainerNetworkPolicyDisabledParamobject

type*

enum

Disable outbound network access. Always `disabled`.

disabled · default: "disabled"

ContainerNetworkPolicyDomainSecretParamobject

domain*	string	The domain associated with the secret.	length ≥ 1
name*	string	The name of the secret to inject for the domain.	length ≥ 1
value*	string	The secret value to inject for the domain.	length ≥ 1 · length ≤ 10485760

ContainerReferenceParamobject

type*	enum	References a container created with the /v1/containers endpoint	container_reference · default: "container_reference"
container_id*	string	The ID of the referenced container.

ConversationParamstring | Conversation object

The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. Input items and output items from this response are automatically added to this conversation after this response completes.

ConversationParam-2object

The conversation that this response belongs to.

id*

string

The unique ID of the conversation.

CoordParamobject

An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.

x*	integer	The x-coordinate.
y*	integer	The y-coordinate.

CustomGrammarFormatParamobject

A grammar defined by the user.

type*	enum	Grammar format. Always `grammar`.	grammar · default: "grammar"
syntax*	enum	The syntax of the grammar definition. One of `lark` or `regex`.	lark \| regex
definition*	string	The grammar definition.

CustomTextFormatParamobject

Unconstrained free-form text.

type*

enum

Unconstrained text format. Always `text`.

text · default: "text"

CustomToolCallobject

A call to a custom tool created by the model.

type*	enum	The type of the custom tool call. Always `custom_tool_call`.	custom_tool_call
id	string	The unique ID of the custom tool call in the OpenAI platform.
call_id*	string	An identifier used to map this custom tool call to a tool call output.
caller	object \| object	The execution context that produced this tool call.	nullable
namespace	string	The namespace of the custom tool being called.
name*	string	The name of the custom tool being called.
input*	string	The input for the custom tool call generated by the model.
async	boolean	Whether the custom tool call runs asynchronously.

CustomToolCallOutputobject

The output of a custom tool call from your code, being sent back to the model.

type*	enum	The type of the custom tool call output. Always `custom_tool_call_output`.	custom_tool_call_output
id	string	The unique ID of the custom tool call output in the OpenAI platform.
call_id*	string	The call ID, used to map this custom tool call output to a custom tool call.
caller	object \| object	The execution context that produced this tool call.	nullable
output*	string \| FunctionAndCustomToolCallOutput[]	The output from the custom tool call generated by your code. Can be a string or an list of output content.

CustomToolParamobject

A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)

type*	enum	The type of the custom tool. Always `custom`.	custom · default: "custom"
name*	string	The name of the custom tool, used to identify it in tool calls.
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
description	string	Optional description of the custom tool, used to provide more context.
format	Text format \| Grammar format	The input format for the custom tool. Default is unconstrained text.
defer_loading	boolean	Whether this tool should be deferred and discovered via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

DetailEnumenum

low | high | auto | original

DirectToolCallCallerobject

type*

enum

direct · default: "direct"

DirectToolCallCallerParamobject

type*

enum

The caller type. Always `direct`.

direct · default: "direct"

DoubleClickActionobject

A double click action.

type*	enum	Specifies the event type. For a double click action, this property is always set to `double_click`.	double_click · default: "double_click"
x*	integer	The x-coordinate where the double click occurred.
y*	integer	The y-coordinate where the double click occurred.
keys*	string[]	The keys being held while double-clicking.	nullable

DragParamobject

A drag action.

type*	enum	Specifies the event type. For a drag action, this property is always set to `drag`.	drag · default: "drag"
path*	CoordParam[]	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 } ] ```
keys	string[]	The keys being held while dragging the mouse.	nullable

EasyInputMessageobject

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. Messages with the `assistant` role are presumed to have …

role*	enum	The role of the message input. One of `user`, `assistant`, `system`, or `developer`.	user \| assistant \| system \| developer
content*	string \| InputContent[]	Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.
phase	enum	Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can deg…	commentary \| final_answer · nullable
type	enum	The type of the message input. Always `message`.	message

EmptyModelParamobject

FileCitationBodyobject

A citation to a file.

type*	enum	The type of the file citation. Always `file_citation`.	file_citation · default: "file_citation"
file_id*	string	The ID of the file.
index*	integer	The index in the output text at which to insert the file citation.
filename*	string	The filename of the file cited.

FileDetailEnumenum

auto | low | high

FileInputDetailenum

auto | low | high

FilePathobject

A path to a file.

type*	enum	The type of the file path. Always `file_path`.	file_path
file_id*	string	The ID of the file.
index*	integer	The index of the file in the list of files.

FileSearchToolobject

A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search).

type*	enum	The type of the file search tool. Always `file_search`.	file_search · default: "file_search"
vector_store_ids*	string[]	The IDs of the vector stores to search.
max_num_results	integer	The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options	RankingOptions	Ranking options for search.
filters	Comparison Filter \| Compound Filter	A filter to apply.	nullable

FileSearchToolCallobject

The results of a file search tool call. See the [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information.

id*	string	The unique ID of the file search tool call.
type*	enum	The type of the file search tool call. Always `file_search_call`.	file_search_call
status*	enum	The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`,	in_progress \| searching \| completed \| incomplete \| failed
queries*	string[]	The queries used to search for files.
results	object[]	The results of the file search tool call.	nullable

FiltersComparison Filter | Compound Filter

FunctionAndCustomToolCallOutputInput text | Input image | Input file

FunctionCallItemStatusenum

in_progress | completed | incomplete

FunctionCallOutputItemParamobject

The output of a function tool call.

id	string	The unique ID of the function tool call output. Populated when this item is returned via API.	nullable
call_id	string	The unique ID of the function tool call generated by the model.	length ≥ 1 · length ≤ 64 · nullable
type*	enum	The type of the function tool call output. Always `function_call_output`.	function_call_output · default: "function_call_output"
output*	string \| InputTextContentParam \| InputImageContentParamAutoParam \| InputFileContentParam[]	Text, image, or file output of the function tool call.
name	string	The name of the tool that produced the output.	length ≥ 1 · length ≤ 128 · nullable
namespace	string	The namespace of the tool that produced the output.	length ≥ 1 · length ≤ 64 · nullable
caller	object \| object	The execution context that produced this tool call.	nullable
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete · nullable

FunctionShellActionParamobject

Commands and limits describing how to run the shell tool call.

commands*	string[]	Ordered shell commands for the execution environment to run.
timeout_ms	integer	Maximum wall-clock time in milliseconds to allow the shell commands to run.	nullable
max_output_length	integer	Maximum number of UTF-8 characters to capture from combined stdout and stderr output.	nullable

FunctionShellCallItemParamobject

A tool representing a request to execute one or more shell commands.

id	string	The unique ID of the shell tool call. Populated when this item is returned via API.	nullable
call_id*	string	The unique ID of the shell tool call generated by the model.	length ≥ 1 · length ≤ 64
caller	object \| object	The execution context that produced this tool call.	nullable
type*	enum	The type of the item. Always `shell_call`.	shell_call · default: "shell_call"
action*	FunctionShellActionParam	The shell commands and limits that describe how to run the tool call.
status	enum	The status of the shell call. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete · nullable
environment	object \| object	The environment to execute the shell commands in.	nullable

FunctionShellCallItemStatusenum

Status values reported for shell tool calls.

in_progress | completed | incomplete

FunctionShellCallOutputContentParamobject

Captured stdout and stderr for a portion of a shell tool call output.

stdout*	string	Captured stdout output for the shell call.	length ≤ 10485760
stderr*	string	Captured stderr output for the shell call.	length ≤ 10485760
outcome*	Shell call timeout outcome \| Shell call exit outcome	The exit or timeout outcome associated with this shell call.

FunctionShellCallOutputExitOutcomeParamobject

Indicates that the shell commands finished and returned an exit code.

type*	enum	The outcome type. Always `exit`.	exit · default: "exit"
exit_code*	integer	The exit code returned by the shell process.

FunctionShellCallOutputItemParamobject

The streamed output items emitted by a shell tool call.

id	string	The unique ID of the shell tool call output. Populated when this item is returned via API.	nullable
call_id*	string	The unique ID of the shell tool call generated by the model.	length ≥ 1 · length ≤ 64
caller	object \| object	The execution context that produced this tool call.	nullable
type*	enum	The type of the item. Always `shell_call_output`.	shell_call_output · default: "shell_call_output"
output*	FunctionShellCallOutputContentParam[]	Captured chunks of stdout and stderr output, along with their associated outcomes.
status	enum	The status of the shell call output.	in_progress \| completed \| incomplete · nullable
max_output_length	integer	The maximum number of UTF-8 characters captured for this shell call's combined output.	nullable

FunctionShellCallOutputOutcomeParamShell call timeout outcome | Shell call exit outcome

The exit or timeout outcome associated with this shell call.

FunctionShellCallOutputTimeoutOutcomeParamobject

Indicates that the shell call exceeded its configured time limit.

type*

enum

The outcome type. Always `timeout`.

timeout · default: "timeout"

FunctionShellToolParamobject

A tool that allows the model to execute shell commands.

type*	enum	The type of the shell tool. Always `shell`.	shell · default: "shell"
environment	object \| object \| object		nullable
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

FunctionToolobject

Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling).

type*	enum	The type of the function tool. Always `function`.	function · default: "function"
name*	string	The name of the function to call.
async	boolean
description	string	A description of the function. Used by the model to determine whether or not to call the function.	nullable
parameters*	object	A JSON schema object describing the parameters of the function.	nullable
output_schema	object	A JSON schema object describing the JSON value encoded in string outputs for this function.	nullable
strict*	boolean	Whether strict parameter validation is enforced for this function tool.	nullable
defer_loading	boolean	Whether this function is deferred and loaded via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	nullable

FunctionToolCallobject

A tool call to run a function. See the [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information.

id	string	The unique ID of the function tool call.
type*	enum	The type of the function tool call. Always `function_call`.	function_call
call_id*	string	The unique ID of the function tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
namespace	string	The namespace of the function to run.
name*	string	The name of the function to run.
arguments*	string	A JSON string of the arguments to pass to the function.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete
async	boolean	Whether the function tool call runs asynchronously.

FunctionToolParamobject

name*	string		length ≥ 1 · length ≤ 128
description	string		nullable
parameters	EmptyModelParam		nullable
strict	boolean	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.	nullable
type*	enum		function · default: "function"
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
output_schema	object	A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs.	nullable
defer_loading	boolean	Whether this function should be deferred and discovered via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

GrammarSyntax1enum

lark | regex

HTTPErrorobject

type*	enum	http_error · default: "http_error"
code*	integer
message*	string

HybridSearchOptionsobject

embedding_weight*	number	The weight of the embedding in the reciprocal ranking fusion.
text_weight*	number	The weight of the text in the reciprocal ranking fusion.

ImageBackgroundenum

transparent | opaque | auto

ImageDetailenum

low | high | auto | original

ImageGenActionEnumenum

generate | edit | auto

ImageGenToolobject

A tool that generates images using the GPT image models.

type*	enum	The type of the image generation tool. Always `image_generation`.	image_generation
model	string \| enum
complexity	enum	Computation spent planning the image, independently of rendering quality. Overrides the outer response's `reasoning.effort` for image generation. When omitted, inherits a supported outer reasoning effort or uses the image model's configured default. For SVG ou…	low \| medium \| high
quality	enum	The quality of the generated image. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Default: `auto`.	low \| medium \| high \| xhigh \| max \| auto · default: "auto"
size	string \| enum	The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` str…	default: "auto"
output_format	enum	The output format of the generated image. One of `png`, `webp`, `jpeg`, `gif`, or `svg`. Default: `png`. GIF and SVG output require a model that supports the selected format. GIF output does not support partial image streaming (`partial_images` greater than `0…	png \| webp \| jpeg \| gif \| svg · default: "png"
frame_count	integer	Number of GIF frames. Requires `output_format` to be `gif`. Default: 9.	2 ≤ n ≤ 16 · default: 9
frame_duration_ms	integer	Duration of each GIF frame in milliseconds, rounded to 10 ms. Requires `output_format` to be `gif`. Default: 200.	20 ≤ n ≤ 2000 · default: 200
svg	SvgParam	SVG author model settings. Requires `output_format` to be `svg`. When SVG model selection is enabled, omitting this object uses the outer response model. Otherwise, the default SVG author is used and explicit model overrides are unavailable.
output_compression	integer	Compression level for the output image. Default: 100.	0 ≤ n ≤ 100 · default: 100
moderation	enum	Moderation level for the generated image. Default: `auto`.	auto \| low · default: "auto"
background	enum	Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image.	transparent \| opaque \| auto · default: "auto"
input_fidelity	enum	Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…	high \| low · nullable
input_image_mask	object	Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).
partial_images	integer	Number of partial images to generate in streaming mode, from 0 (default value) to 3.	0 ≤ n ≤ 3 · default: 0
action	enum	Whether to generate a new image or edit an existing image. Default: `auto`.	generate \| edit \| auto

ImageGenToolCallobject

An image generation request made by the model.

type*	enum	The type of the image generation call. Always `image_generation_call`.	image_generation_call
id*	string	The unique ID of the image generation call.
status*	enum	The status of the image generation call.	in_progress \| completed \| generating \| failed
result*	string	The generated image encoded in base64.	nullable
error	ImageGenToolCallError	Details of a moderation failure, when available.
size	string \| enum	The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.	nullable
quality	enum	The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`.	low \| medium \| high \| xhigh \| max \| auto · nullable
action	enum	The action used for image generation.	generate \| edit \| auto · nullable
background	enum	The background setting used for generation.	transparent \| opaque \| auto · nullable
output_format	enum	The output format used for generation.	png \| webp \| jpeg \| gif \| svg · nullable
svg_usage	SvgUsage
revised_prompt	string	The prompt that was used after any model prompt rewriting.	nullable

ImageGenToolCallErrorobject

code*	string	The error code.	nullable
type*	string	The error type.
message*	string	A description of the error.
param*	string	The related request parameter.	nullable
moderation_details	ImageGenToolCallModerationDetails	Public details for a `moderation_blocked` error, when available.

ImageGenToolCallModerationDetailsobject

moderation_stage*	enum	The stage where moderation blocked the image generation call.	input \| output \| unknown
categories*	string[]	Public moderation categories. New category values may be added over time.

ImageOutputFormatenum

png | webp | jpeg | gif | svg

InlineSkillParamobject

type*	enum	Defines an inline skill for this request.	inline · default: "inline"
name*	string	The name of the skill.
description*	string	The description of the skill.
source*	InlineSkillSourceParam	Inline skill payload

InlineSkillSourceParamobject

Inline skill payload

type*	enum	The type of the inline skill source. Must be `base64`.	base64 · default: "base64"
media_type*	enum	The media type of the inline skill payload. Must be `application/zip`.	application/zip · default: "application/zip"
data*	string	Base64-encoded skill zip bundle.	length ≥ 1 · length ≤ 70254592

InputContentInput text | Input image | Input file

InputFidelityenum

Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…

high | low

InputFileContentobject

A file input to the model.

type*	enum	The type of the input item. Always `input_file`.	input_file · default: "input_file"
file_id	string	The ID of the file to be sent to the model.	nullable
filename	string	The name of the file to be sent to the model.
file_data	string	The content of the file to be sent to the model.
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.
file_url	string	The URL of the file to be sent to the model.	format: uri
detail	enum	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…	auto \| low \| high

InputFileContentParamobject

A file input to the model.

type*	enum	The type of the input item. Always `input_file`.	input_file · default: "input_file"
file_id	string	The ID of the file to be sent to the model.	nullable
filename	string	The name of the file to be sent to the model.	nullable
file_data	string	The base64-encoded data of the file to be sent to the model.	length ≤ 73400320 · nullable
file_url	string	The URL of the file to be sent to the model.	format: uri · nullable
detail	enum	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…	auto \| low \| high
prompt_cache_breakpoint	PromptCacheBreakpointParam	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.	nullable

InputImageContentobject

An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision).

type*	enum	The type of the input item. Always `input_image`.	input_image · default: "input_image"
image_url	string	The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.	format: uri · nullable
file_id	string	The ID of the file to be sent to the model.	nullable
detail*	enum	The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.	low \| high \| auto \| original
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

InputImageContentParamAutoParamobject

An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)

type*	enum	The type of the input item. Always `input_image`.	input_image · default: "input_image"
image_url	string	The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.	length ≤ 20971520 · format: uri · nullable
file_id	string	The ID of the file to be sent to the model.	nullable
detail	enum	The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.	low \| high \| auto \| original · nullable
prompt_cache_breakpoint	PromptCacheBreakpointParam	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.	nullable

InputItemInput message | InputMessage | OutputMessage | FileSearchToolCall | Compaction trigger | …

InputMessageobject

type	enum	The type of the message input. Always set to `message`.	message
role*	enum	The role of the message input. One of `user`, `system`, or `developer`.	user \| system \| developer
status	enum	The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete
content*	InputContent[]	A list of one or many input items to the model, containing different content types.

InputMessageContentListInputContent[]

A list of one or many input items to the model, containing different content types.

InputTextContentobject

A text input to the model.

type*	enum	The type of the input item. Always `input_text`.	input_text · default: "input_text"
text*	string	The text input to the model.
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

InputTextContentParamobject

A text input to the model.

type*	enum	The type of the input item. Always `input_text`.	input_text · default: "input_text"
text*	string	The text input to the model.	length ≤ 10485760
prompt_cache_breakpoint	PromptCacheBreakpointParam	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.	nullable

ItemInput message | Output message | File search tool call | …

Content item used to generate a response.

ItemReferenceParamobject

An internal identifier for an item to reference.

type	enum	The type of item to reference. Always `item_reference`.	item_reference · default: "item_reference" · nullable
id*	string	The ID of the item to reference.

KeyPressActionobject

A collection of keypresses the model would like to perform.

type*	enum	Specifies the event type. For a keypress action, this property is always set to `keypress`.	keypress · default: "keypress"
keys*	string[]	The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

LegacyComputerActionClick | DoubleClick | Drag | …

LocalEnvironmentParamobject

type*	enum	Use a local computer environment.	local · default: "local"
skills	LocalSkillParam[]	An optional list of skills.	items ≤ 200

LocalShellExecActionobject

Execute a shell command on the server.

type*	enum	The type of the local shell action. Always `exec`.	exec · default: "exec"
command*	string[]	The command to run.
timeout_ms	integer	Optional timeout in milliseconds for the command.	nullable
working_directory	string	Optional working directory to run the command in.	nullable
env*	object	Environment variables to set for the command.
user	string	Optional user to run the command as.	nullable

LocalShellToolCallobject

A tool call to run a command on the local shell.

type*	enum	The type of the local shell call. Always `local_shell_call`.	local_shell_call
id*	string	The unique ID of the local shell call.
call_id*	string	The unique ID of the local shell tool call generated by the model.
action*	LocalShellExecAction	Execute a shell command on the server.
status*	enum	The status of the local shell call.	in_progress \| completed \| incomplete

LocalShellToolCallOutputobject

The output of a local shell tool call.

type*	enum	The type of the local shell tool call output. Always `local_shell_call_output`.	local_shell_call_output
id*	string	The unique ID of the local shell tool call generated by the model.
output*	string	A JSON string of the output of the local shell tool call.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete · nullable

LocalShellToolParamobject

A tool that allows the model to execute shell commands in a local environment.

type*

enum

The type of the local shell tool. Always `local_shell`.

local_shell · default: "local_shell"

LocalSkillParamobject

name*	string	The name of the skill.
description*	string	The description of the skill.
path*	string	The path to the directory containing the skill.

LogProbobject

The log probability of a token.

token*	string
logprob*	number
bytes*	integer[]
top_logprobs*	TopLogProb[]

MCPApprovalRequestobject

A request for human approval of a tool invocation.

type*	enum	The type of the item. Always `mcp_approval_request`.	mcp_approval_request
id*	string	The unique ID of the approval request.
server_label*	string	The label of the MCP server making the request.
name*	string	The name of the tool to run.
arguments*	string	A JSON string of arguments for the tool.

MCPApprovalResponseobject

A response to an MCP approval request.

type*	enum	The type of the item. Always `mcp_approval_response`.	mcp_approval_response
id	string	The unique ID of the approval response	nullable
approval_request_id*	string	The ID of the approval request being answered.
approve*	boolean	Whether the request was approved.
reason	string	Optional reason for the decision.	nullable

MCPListToolsobject

A list of tools available on an MCP server.

type*	enum	The type of the item. Always `mcp_list_tools`.	mcp_list_tools
id*	string	The unique ID of the list.
server_label*	string	The label of the MCP server.
tools*	MCPListToolsTool[]	The tools available on the server.
error	string	Error message if the server could not list tools.	nullable

MCPListToolsToolobject

A tool available on an MCP server.

name*	string	The name of the tool.
description	string	The description of the tool.	nullable
input_schema*	object	The JSON schema describing the tool's input.
annotations	object	Additional annotations about the tool.	nullable

MCPProtocolErrorobject

type*	enum	mcp_protocol_error · default: "mcp_protocol_error"
code*	integer
message*	string

MCPToolobject

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).

type*	enum	The type of the MCP tool. Always `mcp`.	mcp
server_label*	string	A label for this MCP server, used to identify it in tool calls.
server_url	string	The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided.	format: uri
connector_id	enum	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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).	connector_dropbox \| connector_gmail \| connector_googlecalendar \| connector_googledrive \| connector_microsoftteams \| connector_outlookcalendar · +2 more · deprecated
tunnel_id	string	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.
authorization	string	An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.
server_description	string	Optional description of the MCP server, used to provide more context.
headers	object	Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.	nullable
allowed_tools	string[] \| MCP tool filter	List of allowed tool names or a filter object.	nullable
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable
require_approval	MCP tool approval filter \| enum	Specify which of the MCP server's tools require approval.	default: "always" · nullable
defer_loading	boolean	Whether this MCP tool is deferred and discovered via tool search.

MCPToolCallobject

An invocation of a tool on an MCP server.

type*	enum	The type of the item. Always `mcp_call`.	mcp_call
id*	string	The unique ID of the tool call.
server_label*	string	The label of the MCP server running the tool.
name*	string	The name of the tool that was run.
arguments*	string	A JSON string of the arguments passed to the tool.
output	string	The output from the tool call.	nullable
error	object \| object \| object	The error from the tool call, if any.	nullable
status	enum	The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`.	in_progress \| completed \| incomplete \| calling \| failed
approval_request_id	string	Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call.	nullable

MCPToolCallErrorobject | object | object

MCPToolCallStatusenum

in_progress | completed | incomplete | calling | failed

MCPToolExecutionErrorobject

type*	enum		mcp_tool_execution_error · default: "mcp_tool_execution_error"
content*	any

MCPToolFilterobject

A filter object to specify which tools are allowed.

tool_names	string[]	List of allowed tool names.
read_only	boolean	Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter.

MessagePhaseenum

Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can deg…

commentary | final_answer

MoveParamobject

A mouse move action.

type*	enum	Specifies the event type. For a move action, this property is always set to `move`.	move · default: "move"
x*	integer	The x-coordinate to move to.
y*	integer	The y-coordinate to move to.
keys	string[]	The keys being held while moving the mouse.	nullable

NamespaceToolParamobject

Groups function/custom tools under a shared namespace.

type*	enum	The type of the tool. Always `namespace`.	namespace · default: "namespace"
name*	string	The namespace name used in tool calls (for example, `crm`).	length ≥ 1
description*	string	A description of the namespace shown to the model.
tools*	FunctionToolParam \| CustomToolParam[]	The function/custom tools available inside this namespace.	items ≥ 1

OutputMessageobject

An output message from the model.

id*	string	The unique ID of the output message.
type*	enum	The type of the output message. Always `message`.	message
role*	enum	The role of the output message. Always `assistant`.	assistant
content*	OutputMessageContent[]	The content of the output message.
phase	enum	Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can deg…	commentary \| final_answer · nullable
status*	enum	The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.	in_progress \| completed \| incomplete

OutputMessageContentOutput text | Refusal

OutputTextContentobject

A text output from the model.

type*	enum	The type of the output text. Always `output_text`.	output_text · default: "output_text"
text*	string	The text output from the model.
annotations*	Annotation[]	The annotations of the text output.
logprobs	LogProb[]

PersonalityEnumstring | enum

ProgramItemParamobject

id*	string	The unique ID of this program item.
type*	enum	The item type. Always `program`.	program · default: "program"
call_id*	string	The stable call ID of the program item.	length ≥ 1 · length ≤ 64
code*	string	The JavaScript source executed by programmatic tool calling.	length ≤ 10485760
fingerprint*	string	Opaque program replay fingerprint that must be round-tripped.	length ≤ 10485760

ProgrammaticToolCallingParamobject

type*

enum

The type of the tool. Always `programmatic_tool_calling`.

programmatic_tool_calling · default: "programmatic_tool_calling"

ProgramOutputItemParamobject

id*	string	The unique ID of this program output item.
type*	enum	The item type. Always `program_output`.	program_output · default: "program_output"
call_id*	string	The call ID of the program item.	length ≥ 1 · length ≤ 64
result*	string	The result produced by the program item.	length ≤ 10485760
status*	enum	The terminal status of the program output.	completed \| incomplete

ProgramOutputItemStatusenum

completed | incomplete

ProgramToolCallCallerobject

type*	enum		program · default: "program"
caller_id*	string	The call ID of the program item that produced this tool call.

ProgramToolCallCallerParamobject

type*	enum	The caller type. Always `program`.	program · default: "program"
caller_id*	string	The call ID of the program item that produced this tool call.	length ≥ 1 · length ≤ 64

PromptCacheBreakpointConfigobject

Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

mode*	enum	The breakpoint mode. Always `explicit`.	explicit · default: "explicit"
ttl	enum	The minimum lifetime of this cache breakpoint. Defaults to the request TTL.	30m \| 12h

PromptCacheBreakpointParamobject

Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

mode*	enum	The breakpoint mode. Always `explicit`.	explicit · default: "explicit"
ttl	enum	The minimum lifetime of this cache breakpoint. Defaults to the request TTL.	30m \| 12h

RankerVersionTypeenum

auto | default-2024-11-15

RankingOptionsobject

ranker	enum	The ranker to use for the file search.	auto \| default-2024-11-15
score_threshold	number	The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.
hybrid_search	HybridSearchOptions	Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

Reasoningobject

Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).

mode	string \| enum	Controls the reasoning execution mode for the request.
effort	enum	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 a…	none \| minimal \| low \| medium \| high \| xhigh · +1 more · default: "medium" · nullable
summary	enum	A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`.	auto \| concise \| detailed · nullable
context	enum	Controls which reasoning items are rendered back to the model on later turns. If omitted or set to `auto`, the model determines the context mode. The `gpt-5.6` model family defaults to `all_turns`; earlier models default to `current_turn`.	auto \| current_turn \| all_turns · nullable
generate_summary	enum	Deprecated: use `summary` instead.	auto \| concise \| detailed · nullable · deprecated

ReasoningEffortenum

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 a…

ReasoningEffortEnumenum

ReasoningItemobject

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](https://developers.op…

type*	enum	The type of the object. Always `reasoning`.	reasoning
id*	string	The unique identifier of the reasoning content.
encrypted_content	string	The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests.	nullable
summary*	Summary[]	Reasoning summary content.
content	ReasoningTextContent[]	Reasoning text content.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

ReasoningModeEnumstring | enum

ReasoningTextContentobject

Reasoning text from the model.

type*	enum	The type of the reasoning text. Always `reasoning_text`.	reasoning_text · default: "reasoning_text"
text*	string	The reasoning text from the model.

RefusalContentobject

A refusal from the model.

type*	enum	The type of the refusal. Always `refusal`.	refusal · default: "refusal"
refusal*	string	The refusal explanation from the model.

ResponseConfigurationUpdateItemParamobject

An update to the conversation's response configuration. Supply reasoning, text, or both. Each setting stays in effect until a later update replaces it.

id	string	The unique ID of the configuration update item.	nullable
type*	enum	The item type. Always `configuration_update`.	configuration_update · default: "configuration_update"
reasoning	object	Updates to reasoning configuration. Only effort is supported.
text	object	The text output configuration for subsequent responses.

ResponseFormatJsonObjectobject

JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

type*

enum

The type of response format being defined. Always `json_object`.

json_object

ResponseFormatJsonSchemaSchemaobject

The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/).

ResponseFormatTextobject

Default response format. Used to generate text responses.

type*

enum

The type of response format being defined. Always `text`.

text

ResponseTextParamobject

Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - [Structured Outputs](https://developers.openai.com/api/docs/guide…

format	Text \| JSON schema \| JSON object	An object specifying the format that the model must output.
verbosity	enum	Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are `low`, `medium`, and `high`. The default is `medium`.	low \| medium \| high · default: "medium" · nullable

ScreenshotParamobject

A screenshot action.

type*

enum

Specifies the event type. For a screenshot action, this property is always set to `screenshot`.

screenshot · default: "screenshot"

ScrollParamobject

A scroll action.

type*	enum	Specifies the event type. For a scroll action, this property is always set to `scroll`.	scroll · default: "scroll"
x*	integer	The x-coordinate where the scroll occurred.
y*	integer	The y-coordinate where the scroll occurred.
scroll_x*	integer	The horizontal scroll distance.
scroll_y*	integer	The vertical scroll distance.
keys	string[]	The keys being held while scrolling.	nullable

SearchContentTypeenum

text | image

SearchContextSizeenum

low | medium | high

SkillReferenceParamobject

type*	enum	References a skill created with the /v1/skills endpoint.	skill_reference · default: "skill_reference"
skill_id*	string	The ID of the referenced skill.	length ≥ 1 · length ≤ 64
version	string	Optional skill version. Use a positive integer or 'latest'. Omit for default.

SpecificApplyPatchParamobject

Forces the model to call the apply_patch tool when executing a tool call.

type*

enum

The tool to call. Always `apply_patch`.

apply_patch · default: "apply_patch"

SpecificFunctionShellParamobject

Forces the model to call the shell tool when a tool call is required.

type*

enum

The tool to call. Always `shell`.

shell · default: "shell"

SpecificProgrammaticToolCallingParamobject

type*

enum

The tool to call. Always `programmatic_tool_calling`.

programmatic_tool_calling · default: "programmatic_tool_calling"

Summaryobject

A summary text from the model.

type*	enum	The type of the object. Always `summary_text`.	summary_text · default: "summary_text"
text*	string	A summary of the reasoning output from the model so far.

SvgParamobject

model	string		length ≥ 1
reasoning	SvgReasoningParam	Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.	nullable

SvgReasoningParamobject

Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.

effort

enum

Controls how much effort the model should spend on reasoning for this request.

SvgUsageobject

model*	string
input_tokens*	integer
output_tokens*	integer
total_tokens*	integer
reasoning_tokens*	integer

TextResponseFormatConfigurationText | JSON schema | JSON object

An object specifying the format that the model must output.

TextResponseFormatJsonSchemaobject

JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs).

type*	enum	The type of response format being defined. Always `json_schema`.	json_schema
description	string	A description of what the response format is for, used by the model to determine how to respond in the format.
name*	string	The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
schema*	ResponseFormatJsonSchemaSchema	The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/).
strict	boolean	Whether to enable strict schema adherence when generating the output. 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 [Struc…	default: false · nullable

ToolFunction | File search | Computer | …

A tool that can be used to generate a response.

ToolCallCallerobject | object

The execution context that produced this tool call.

ToolCallCallerParamobject | object

The execution context that produced this tool call.

ToolChoiceAllowedobject

Constrains the tools available to the model to a pre-defined set.

type*	enum	Allowed tool configuration type. Always `allowed_tools`.	allowed_tools
mode*	enum	Constrains the tools available to the model to a pre-defined set.	auto \| required
tools*	object[]	A list of tool definitions that the model should be allowed to call.

ToolChoiceCustomobject

Use this option to force the model to call a specific custom tool.

type*	enum	For custom tool calling, the type is always `custom`.	custom
name*	string	The name of the custom tool to call.

ToolChoiceFunctionobject

Use this option to force the model to call a specific function.

type*	enum	For function calling, the type is always `function`.	function
name*	string	The name of the function to call.

ToolChoiceMCPobject

Use this option to force the model to call a specific tool on a remote MCP server.

type*	enum	For MCP tools, the type is always `mcp`.	mcp
server_label*	string	The label of the MCP server to use.
name	string	The name of the tool to call on the server.	nullable

ToolChoiceOptionsenum

Controls which (if any) tool is called by the model.

none | auto | required

ToolChoiceParamenum | Allowed tools | Hosted tool | …

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 the model can call.

ToolChoiceTypesobject

Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://developers.openai.com/api/docs/guides/tools).

type*

enum

The type of hosted tool the model should to use. Learn more about [built-in tools](https://developers.openai.com/api/docs/guides/tools).

ToolSearchCallItemParamobject

id	string	The unique ID of this tool search call.	nullable
call_id	string	The unique ID of the tool search call generated by the model.	length ≥ 1 · length ≤ 64 · nullable
type*	enum	The item type. Always `tool_search_call`.	tool_search_call · default: "tool_search_call"
execution	enum	Whether tool search was executed by the server or by the client.	server \| client
arguments*	EmptyModelParam	The arguments supplied to the tool search call.
status	enum	The status of the tool search call.	in_progress \| completed \| incomplete · nullable

ToolSearchExecutionTypeenum

server | client

ToolSearchOutputFunctionToolParamobject

name*	string	The name of the loaded function tool.	length ≥ 1 · length ≤ 128
description	string		nullable
parameters	EmptyModelParam		nullable
strict	boolean	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.	nullable
type*	enum		function · default: "function"
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
output_schema	object	A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs.	nullable
defer_loading	boolean	Whether this function should be deferred and discovered via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

ToolSearchOutputItemParamobject

id	string	The unique ID of this tool search output.	nullable
call_id	string	The unique ID of the tool search call generated by the model.	length ≥ 1 · length ≤ 64 · nullable
type*	enum	The item type. Always `tool_search_output`.	tool_search_output · default: "tool_search_output"
execution	enum	Whether tool search was executed by the server or by the client.	server \| client
tools*	ToolSearchOutputTool[]	The loaded tool definitions returned by the tool search output.
status	enum	The status of the tool search output.	in_progress \| completed \| incomplete · nullable

ToolSearchOutputNamespaceToolParamobject

Groups function/custom tools under a shared namespace.

type*	enum	The type of the tool. Always `namespace`.	namespace · default: "namespace"
name*	string	The namespace name used in tool calls (for example, `crm`).	length ≥ 1
description*	string	A description of the namespace shown to the model.
tools*	ToolSearchOutputFunctionToolParam \| CustomToolParam[]	The function/custom tools loaded inside this namespace.	items ≥ 1

ToolSearchOutputToolFunction | File search | Computer | …

A tool definition returned by a tool search output.

ToolSearchToolParamobject

Hosted or BYOT tool search configuration for deferred tools.

type*	enum	The type of the tool. Always `tool_search`.	tool_search · default: "tool_search"
execution	enum	Whether tool search is executed by the server or by the client.	server \| client
description	string	Description shown to the model for a client-executed tool search tool.	nullable
parameters	EmptyModelParam	Parameter schema for a client-executed tool search tool.	nullable

TopLogProbobject

The top log probability of a token.

token*	string
logprob*	number
bytes*	integer[]

TruncationEnumenum

auto | disabled

TypeParamobject

An action to type in text.

type*	enum	Specifies the event type. For a type action, this property is always set to `type`.	type · default: "type"
text*	string	The text to type.

UrlCitationBodyobject

A citation for a web resource used to generate a model response.

type*	enum	The type of the URL citation. Always `url_citation`.	url_citation · default: "url_citation"
url*	string	The URL of the web resource.	format: uri
start_index*	integer	The index of the first character of the URL citation in the message.
end_index*	integer	The index of the last character of the URL citation in the message.
title*	string	The title of the web resource.

VectorStoreFileAttributesobject

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characte…

nullable

Verbosityenum

Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are `low`, `medium`, and `high`. The default is `medium`.

low | medium | high · default: "medium" · nullable

WaitParamobject

A wait action.

type*

enum

Specifies the event type. For a wait action, this property is always set to `wait`.

wait · default: "wait"

WebSearchActionFindobject

Action type "find_in_page": Searches for a pattern within a loaded page.

type*	enum	The action type.	find_in_page
url*	string	The URL of the page searched for the pattern.	format: uri
pattern*	string	The pattern or text to search for within the page.

WebSearchActionOpenPageobject

Action type "open_page" - Opens a specific URL from search results.

type*	enum	The action type.	open_page
url	string	The URL opened by the model.	format: uri · nullable

WebSearchActionSearchobject

Action type "search" - Performs a web search query.

type*	enum	The action type.	search
query	string	The search query.	deprecated
queries	string[]	The search queries.
sources	Web search source[]	The sources used in the search.

WebSearchApproximateLocationobject

The approximate location of the user.

type	enum	The type of location approximation. Always `approximate`.	approximate · default: "approximate"
country	string	The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.	nullable
region	string	Free text input for the region of the user, e.g. `California`.	nullable
city	string	Free text input for the city of the user, e.g. `San Francisco`.	nullable
timezone	string	The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.	nullable

WebSearchCallStatusenum

in_progress | searching | completed | failed | incomplete

WebSearchPreviewToolobject

This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).

type*	enum	The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.	web_search_preview \| web_search_preview_2025_03_11 · default: "web_search_preview"
user_location	ApproximateLocation	The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass `{"type": "approximate"}` without location fields. To localize results, provide the relevant location fields.	nullable
search_context_size	enum	High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.	low \| medium \| high
search_content_types	SearchContentType[]

WebSearchToolobject

Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).

type*	enum	The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.	web_search \| web_search_2025_08_26 · default: "web_search"
external_web_access	boolean	Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.	default: true
filters	object	Filters for the search.	nullable
user_location	object	The approximate location of the user.	nullable
search_context_size	enum	High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.	low \| medium \| high · default: "medium"

WebSearchToolCallobject

The results of a web search tool call. See the [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.

id*	string	The unique ID of the web search tool call.
type*	enum	The type of the web search tool call. Always `web_search_call`.	web_search_call
status*	enum	The status of the web search tool call.	in_progress \| searching \| completed \| failed \| incomplete
action*	Search action \| Open page action \| Find action	An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).

Validate a payload

before you spend tokens

shell

$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"openai","endpointId":"responses/input_tokens","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}

/v1/schemas/openai/chat/responses/input_tokens

Request body

Types

AdditionalToolsItemParamobject

AnnotationFile citation | URL citation | Container file citation | …

ApplyPatchCallOutputStatusParamenum

ApplyPatchCallStatusParamenum

ApplyPatchCreateFileOperationParamobject

ApplyPatchDeleteFileOperationParamobject

ApplyPatchOperationParamApply patch create file operation | Apply patch delete file operation | Apply patch update file operation

ApplyPatchToolCallItemParamobject

ApplyPatchToolCallOutputItemParamobject

ApplyPatchToolParamobject

ApplyPatchUpdateFileOperationParamobject

ApproximateLocationobject

CallableToolAllowedCallerenum

ClickButtonTypeenum

ClickParamobject

CodeInterpreterContainerAutoobject

CodeInterpreterOutputImageobject

CodeInterpreterOutputLogsobject

CodeInterpreterToolobject

CodeInterpreterToolCallobject

CompactionSummaryItemParamobject

CompactionTriggerItemParamobject

ComparisonFilterobject

ComparisonFilterValueItemsstring | number

CompoundFilterobject

ComputerActionClick | DoubleClick | Drag | …

ComputerActionListComputerAction[]

ComputerCallOutputItemParamobject

ComputerCallSafetyCheckParamobject

ComputerEnvironmentenum

ComputerScreenshotImageobject

ComputerToolobject

ComputerToolCallobject

ComputerUsePreviewToolobject

ContainerAutoParamobject

ContainerFileCitationBodyobject

ContainerMemoryLimitenum

ContainerNetworkPolicyAllowlistParamobject

ContainerNetworkPolicyDisabledParamobject

ContainerNetworkPolicyDomainSecretParamobject

ContainerReferenceParamobject

ConversationParamstring | Conversation object

ConversationParam-2object

CoordParamobject

CustomGrammarFormatParamobject

CustomTextFormatParamobject

CustomToolCallobject

CustomToolCallOutputobject

CustomToolParamobject

DetailEnumenum

DirectToolCallCallerobject

DirectToolCallCallerParamobject

DoubleClickActionobject

DragParamobject

EasyInputMessageobject

EmptyModelParamobject

FileCitationBodyobject

FileDetailEnumenum

FileInputDetailenum

FilePathobject

FileSearchToolobject

FileSearchToolCallobject

FiltersComparison Filter | Compound Filter

FunctionAndCustomToolCallOutputInput text | Input image | Input file

FunctionCallItemStatusenum

FunctionCallOutputItemParamobject

FunctionShellActionParamobject

FunctionShellCallItemParamobject

FunctionShellCallItemStatusenum

FunctionShellCallOutputContentParamobject

FunctionShellCallOutputExitOutcomeParamobject

FunctionShellCallOutputItemParamobject

FunctionShellCallOutputOutcomeParamShell call timeout outcome | Shell call exit outcome

FunctionShellCallOutputTimeoutOutcomeParamobject

FunctionShellToolParamobject

FunctionToolobject

FunctionToolCallobject