API Reference

Responses

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Run OpenAI Responses API (OpenAI only)

client.responses.create(ResponseCreateParams { input, model, include, 14 more } body, RequestOptionsoptions?): ResponseCreateResponse

POST/v5/responses

Runs inference using the OpenAI Responses API contract, taking an input rather than a chat messages array.

This endpoint is restricted to OpenAI-vendor models: requests whose model (vendor/name) resolves to any other vendor are rejected with an unsupported-vendor error, unlike /v5/chat/completions and /v5/inference which support many vendors. Use it when you specifically need Responses API features such as previous_response_id chaining, instructions, or store; use /v5/chat/completions for the standard messages-based chat contract. When stream is set the response streams as server-sent events; otherwise a single response object is returned.

ParametersExpand Collapse

body: ResponseCreateParams { input, model, include, 14 more }

input: string | Array<EasyInputMessageParam { content, role, phase, type } | OpenAITypesResponsesResponseInputParamMessage { content, role, status, type } | ResponseOutputMessageParam { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessageParam { content, role, phase, type } | OpenAITypesResponsesResponseInputParamMessage { content, role, status, type } | ResponseOutputMessageParam { id, content, role, 3 more } | 23 more>

EasyInputMessageParam { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputTextParam { text, type } | OpenAIResponseInputImageParam { detail, type, file_id, image_url } | OpenAIResponseInputFileParam { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputTextParam { text, type } | OpenAIResponseInputImageParam { detail, type, file_id, image_url } | OpenAIResponseInputFileParam { type, file_data, file_id, 2 more } >

OpenAIResponseInputTextParam { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImageParam { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFileParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputParamMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputTextParam { text, type } | OpenAIResponseInputImageParam { detail, type, file_id, image_url } | OpenAIResponseInputFileParam { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputTextParam { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImageParam { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFileParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

ResponseOutputMessageParam { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<ResponseOutputTextParam { annotations, text, type, logprobs } | ResponseOutputRefusalParam { refusal, type } >

One of the following:

ResponseOutputTextParam { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextParamAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextParamAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

ResponseOutputRefusalParam { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

ResponseFileSearchToolCallParam { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

ResponseComputerToolCallParam { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputParamComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: Output { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseFunctionWebSearchParam { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchParamActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchParamActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchParamActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchParamActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

ResponseFunctionToolCallParam { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputParamFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContentParam { text, type } | ResponseInputImageContentParam { type, detail, file_id, image_url } | ResponseInputFileContentParam { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContentParam { text, type } | ResponseInputImageContentParam { type, detail, file_id, image_url } | ResponseInputFileContentParam { type, file_data, file_id, 2 more } >

ResponseInputTextContentParam { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContentParam { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContentParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseReasoningItemParam { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParamParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputParamImageGenerationCall { id, result, status, type }

An image generation request made by the model.

id: string

result: string | null

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

ResponseCodeInterpreterToolCallParam { id, code, container_id, 3 more }

A tool call to run code.

id: string

code: string | null

container_id: string

outputs: Array<OutputLogs { logs, type } | OutputImage { type, url } > | null

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

OpenAITypesResponsesResponseInputParamLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputParamLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputParamShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironmentParam { type, skills } | ContainerReferenceParam { container_id, type }

One of the following:

LocalEnvironmentParam { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReferenceParam { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputParamShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputParamApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

OpenAITypesResponsesResponseInputParamApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputParamMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputParamMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputParamMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

ResponseCustomToolCallOutputParam { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputTextParam { text, type } | OpenAIResponseInputImageParam { detail, type, file_id, image_url } | OpenAIResponseInputFileParam { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputTextParam { text, type } | OpenAIResponseInputImageParam { detail, type, file_id, image_url } | OpenAIResponseInputFileParam { type, file_data, file_id, 2 more } >

OpenAIResponseInputTextParam { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImageParam { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFileParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

ResponseCustomToolCallParam { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputParamItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

model: string

model specified as model_vendor/model, for example openai/gpt-4o

include?: Array<string>

Which fields to include in the response

instructions?: string

Instructions for the response generation

max_output_tokens?: number

Maximum number of output tokens

metadata?: Record<string, unknown>

Metadata for the response

parallel_tool_calls?: boolean

Whether to enable parallel tool calls

previous_response_id?: string

ID of the previous response for chaining

reasoning?: Record<string, unknown>

Reasoning configuration for the response

store?: boolean

Whether to store the response

stream?: boolean

Whether to stream the response

temperature?: number

Sampling temperature for randomness control

maximum2

minimum0

text?: Record<string, unknown>

Text configuration parameters

tool_choice?: string | Record<string, unknown>

Tool choice configuration

One of the following:

string

Record<string, unknown>

tools?: Array<Record<string, unknown>>

Tools available for the response

top_p?: number

Top-p sampling parameter

maximum1

minimum0

truncation?: "auto" | "disabled"

Truncation configuration

One of the following:

"auto"

"disabled"

ReturnsExpand Collapse

ResponseCreateResponse = OpenAIResponse { id, created_at, model, 29 more } | ResponseAudioDeltaEvent { delta, sequence_number, type } | ResponseAudioDoneEvent { sequence_number, type } | 52 more

Emitted when there is a partial audio response.

One of the following:

OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

ResponseAudioDeltaEvent { delta, sequence_number, type }

Emitted when there is a partial audio response.

delta: string

sequence_number: number

type: "response.audio.delta"

ResponseAudioDoneEvent { sequence_number, type }

Emitted when the audio response is complete.

sequence_number: number

type: "response.audio.done"

ResponseAudioTranscriptDeltaEvent { delta, sequence_number, type }

Emitted when there is a partial transcript of audio.

delta: string

sequence_number: number

type: "response.audio.transcript.delta"

ResponseAudioTranscriptDoneEvent { sequence_number, type }

Emitted when the full audio transcript is completed.

sequence_number: number

type: "response.audio.transcript.done"

ResponseCodeInterpreterCallCodeDeltaEvent { delta, item_id, output_index, 2 more }

Emitted when a partial code snippet is streamed by the code interpreter.

delta: string

item_id: string

output_index: number

sequence_number: number

type: "response.code_interpreter_call_code.delta"

ResponseCodeInterpreterCallCodeDoneEvent { code, item_id, output_index, 2 more }

Emitted when the code snippet is finalized by the code interpreter.

code: string

item_id: string

output_index: number

sequence_number: number

type: "response.code_interpreter_call_code.done"

ResponseCodeInterpreterCallCompletedEvent { item_id, output_index, sequence_number, type }

Emitted when the code interpreter call is completed.

item_id: string

output_index: number

sequence_number: number

type: "response.code_interpreter_call.completed"

ResponseCodeInterpreterCallInProgressEvent { item_id, output_index, sequence_number, type }

Emitted when a code interpreter call is in progress.

item_id: string

output_index: number

sequence_number: number

type: "response.code_interpreter_call.in_progress"

ResponseCodeInterpreterCallInterpretingEvent { item_id, output_index, sequence_number, type }

Emitted when the code interpreter is actively interpreting the code snippet.

item_id: string

output_index: number

sequence_number: number

type: "response.code_interpreter_call.interpreting"

ResponseCompletedEvent { response, sequence_number, type }

Emitted when the model response is complete.

response: OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

sequence_number: number

type: "response.completed"

ResponseContentPartAddedEvent { content_index, item_id, output_index, 3 more }

Emitted when a new content part is added.

content_index: number

item_id: string

output_index: number

part: OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } | PartReasoningText { text, type }

A text output from the model.

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

PartReasoningText { text, type }

Reasoning text from the model.

text: string

type: "reasoning_text"

sequence_number: number

type: "response.content_part.added"

ResponseContentPartDoneEvent { content_index, item_id, output_index, 3 more }

Emitted when a content part is done.

content_index: number

item_id: string

output_index: number

part: OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } | PartReasoningText { text, type }

A text output from the model.

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

PartReasoningText { text, type }

Reasoning text from the model.

text: string

type: "reasoning_text"

sequence_number: number

type: "response.content_part.done"

ResponseCreatedEvent { response, sequence_number, type }

An event that is emitted when a response is created.

response: OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

sequence_number: number

type: "response.created"

ResponseErrorEvent { message, sequence_number, type, 2 more }

Emitted when an error occurs.

message: string

sequence_number: number

type: "error"

code?: string

param?: string

ResponseFileSearchCallCompletedEvent { item_id, output_index, sequence_number, type }

Emitted when a file search call is completed (results found).

item_id: string

output_index: number

sequence_number: number

type: "response.file_search_call.completed"

ResponseFileSearchCallInProgressEvent { item_id, output_index, sequence_number, type }

Emitted when a file search call is initiated.

item_id: string

output_index: number

sequence_number: number

type: "response.file_search_call.in_progress"

ResponseFileSearchCallSearchingEvent { item_id, output_index, sequence_number, type }

Emitted when a file search is currently searching.

item_id: string

output_index: number

sequence_number: number

type: "response.file_search_call.searching"

ResponseFunctionCallArgumentsDeltaEvent { delta, item_id, output_index, 2 more }

Emitted when there is a partial function-call arguments delta.

delta: string

item_id: string

output_index: number

sequence_number: number

type: "response.function_call_arguments.delta"

ResponseFunctionCallArgumentsDoneEvent { arguments, item_id, name, 3 more }

Emitted when function-call arguments are finalized.

arguments: string

item_id: string

name: string

output_index: number

sequence_number: number

type: "response.function_call_arguments.done"

ResponseInProgressEvent { response, sequence_number, type }

Emitted when the response is in progress.

response: OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

sequence_number: number

type: "response.in_progress"

ResponseFailedEvent { response, sequence_number, type }

An event that is emitted when a response fails.

response: OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

sequence_number: number

type: "response.failed"

ResponseIncompleteEvent { response, sequence_number, type }

An event that is emitted when a response finishes as incomplete.

response: OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

sequence_number: number

type: "response.incomplete"

ResponseOutputItemAddedEvent { item, output_index, sequence_number, type }

Emitted when a new output item is added.

item: OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more

An output message from the model.

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

output_index: number

sequence_number: number

type: "response.output_item.added"

ResponseOutputItemDoneEvent { item, output_index, sequence_number, type }

Emitted when an output item is marked done.

item: OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more

An output message from the model.

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

output_index: number

sequence_number: number

type: "response.output_item.done"

ResponseReasoningSummaryPartAddedEvent { item_id, output_index, part, 3 more }

Emitted when a new reasoning summary part is added.

item_id: string

output_index: number

part: Part { text, type }

The summary part that was added.

text: string

type: "summary_text"

sequence_number: number

summary_index: number

type: "response.reasoning_summary_part.added"

ResponseReasoningSummaryPartDoneEvent { item_id, output_index, part, 3 more }

Emitted when a reasoning summary part is completed.

item_id: string

output_index: number

part: Part { text, type }

The completed summary part.

text: string

type: "summary_text"

sequence_number: number

summary_index: number

type: "response.reasoning_summary_part.done"

ResponseReasoningSummaryTextDeltaEvent { delta, item_id, output_index, 3 more }

Emitted when a delta is added to a reasoning summary text.

delta: string

item_id: string

output_index: number

sequence_number: number

summary_index: number

type: "response.reasoning_summary_text.delta"

ResponseReasoningSummaryTextDoneEvent { item_id, output_index, sequence_number, 3 more }

Emitted when a reasoning summary text is completed.

item_id: string

output_index: number

sequence_number: number

summary_index: number

text: string

type: "response.reasoning_summary_text.done"

ResponseReasoningTextDeltaEvent { content_index, delta, item_id, 3 more }

Emitted when a delta is added to a reasoning text.

content_index: number

delta: string

item_id: string

output_index: number

sequence_number: number

type: "response.reasoning_text.delta"

ResponseReasoningTextDoneEvent { content_index, item_id, output_index, 3 more }

Emitted when a reasoning text is completed.

content_index: number

item_id: string

output_index: number

sequence_number: number

text: string

type: "response.reasoning_text.done"

ResponseRefusalDeltaEvent { content_index, delta, item_id, 3 more }

Emitted when there is a partial refusal text.

content_index: number

delta: string

item_id: string

output_index: number

sequence_number: number

type: "response.refusal.delta"

ResponseRefusalDoneEvent { content_index, item_id, output_index, 3 more }

Emitted when refusal text is finalized.

content_index: number

item_id: string

output_index: number

refusal: string

sequence_number: number

type: "response.refusal.done"

ResponseTextDeltaEvent { content_index, delta, item_id, 4 more }

Emitted when there is an additional text delta.

content_index: number

delta: string

item_id: string

logprobs: Array<Logprob>

token: string

logprob: number

top_logprobs?: Array<TopLogprob>

token?: string

logprob?: number

output_index: number

sequence_number: number

type: "response.output_text.delta"

ResponseTextDoneEvent { content_index, item_id, logprobs, 4 more }

Emitted when text content is finalized.

content_index: number

item_id: string

logprobs: Array<Logprob>

token: string

logprob: number

top_logprobs?: Array<TopLogprob>

token?: string

logprob?: number

output_index: number

sequence_number: number

text: string

type: "response.output_text.done"

ResponseWebSearchCallCompletedEvent { item_id, output_index, sequence_number, type }

Emitted when a web search call is completed.

item_id: string

output_index: number

sequence_number: number

type: "response.web_search_call.completed"

ResponseWebSearchCallInProgressEvent { item_id, output_index, sequence_number, type }

Emitted when a web search call is initiated.

item_id: string

output_index: number

sequence_number: number

type: "response.web_search_call.in_progress"

ResponseWebSearchCallSearchingEvent { item_id, output_index, sequence_number, type }

Emitted when a web search call is executing.

item_id: string

output_index: number

sequence_number: number

type: "response.web_search_call.searching"

ResponseImageGenCallCompletedEvent { item_id, output_index, sequence_number, type }

Emitted when an image generation tool call has completed and the final image is available.

item_id: string

output_index: number

sequence_number: number

type: "response.image_generation_call.completed"

ResponseImageGenCallGeneratingEvent { item_id, output_index, sequence_number, type }

Emitted when an image generation tool call is actively generating an image (intermediate state).

item_id: string

output_index: number

sequence_number: number

type: "response.image_generation_call.generating"

ResponseImageGenCallInProgressEvent { item_id, output_index, sequence_number, type }

Emitted when an image generation tool call is in progress.

item_id: string

output_index: number

sequence_number: number

type: "response.image_generation_call.in_progress"

ResponseImageGenCallPartialImageEvent { item_id, output_index, partial_image_b64, 3 more }

Emitted when a partial image is available during image generation streaming.

item_id: string

output_index: number

partial_image_b64: string

partial_image_index: number

sequence_number: number

type: "response.image_generation_call.partial_image"

ResponseMcpCallArgumentsDeltaEvent { delta, item_id, output_index, 2 more }

Emitted when there is a delta (partial update) to the arguments of an MCP tool call.

delta: string

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_call_arguments.delta"

ResponseMcpCallArgumentsDoneEvent { arguments, item_id, output_index, 2 more }

Emitted when the arguments for an MCP tool call are finalized.

arguments: string

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_call_arguments.done"

ResponseMcpCallCompletedEvent { item_id, output_index, sequence_number, type }

Emitted when an MCP tool call has completed successfully.

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_call.completed"

ResponseMcpCallFailedEvent { item_id, output_index, sequence_number, type }

Emitted when an MCP tool call has failed.

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_call.failed"

ResponseMcpCallInProgressEvent { item_id, output_index, sequence_number, type }

Emitted when an MCP tool call is in progress.

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_call.in_progress"

ResponseMcpListToolsCompletedEvent { item_id, output_index, sequence_number, type }

Emitted when the list of available MCP tools has been successfully retrieved.

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_list_tools.completed"

ResponseMcpListToolsFailedEvent { item_id, output_index, sequence_number, type }

Emitted when the attempt to list available MCP tools has failed.

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_list_tools.failed"

ResponseMcpListToolsInProgressEvent { item_id, output_index, sequence_number, type }

Emitted when the system is in the process of retrieving the list of available MCP tools.

item_id: string

output_index: number

sequence_number: number

type: "response.mcp_list_tools.in_progress"

ResponseOutputTextAnnotationAddedEvent { annotation, annotation_index, content_index, 4 more }

Emitted when an annotation is added to output text content.

annotation: unknown

annotation_index: number

content_index: number

item_id: string

output_index: number

sequence_number: number

type: "response.output_text.annotation.added"

ResponseQueuedEvent { response, sequence_number, type }

Emitted when a response is queued and waiting to be processed.

response: OpenAIResponse { id, created_at, model, 29 more }

id: string

created_at: number

model: "gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more | (string & {})

One of the following:

"gpt-5.2" | "gpt-5.2-2025-12-11" | "gpt-5.2-chat-latest" | 83 more

"gpt-5.2"

"gpt-5.2-2025-12-11"

"gpt-5.2-chat-latest"

"gpt-5.2-pro"

"gpt-5.2-pro-2025-12-11"

"gpt-5.1"

"gpt-5.1-2025-11-13"

"gpt-5.1-codex"

"gpt-5.1-mini"

"gpt-5.1-chat-latest"

"gpt-5"

"gpt-5-mini"

"gpt-5-nano"

"gpt-5-2025-08-07"

"gpt-5-mini-2025-08-07"

"gpt-5-nano-2025-08-07"

"gpt-5-chat-latest"

"gpt-4.1"

"gpt-4.1-mini"

"gpt-4.1-nano"

"gpt-4.1-2025-04-14"

"gpt-4.1-mini-2025-04-14"

"gpt-4.1-nano-2025-04-14"

"o4-mini"

"o4-mini-2025-04-16"

"o3"

"o3-2025-04-16"

"o3-mini"

"o3-mini-2025-01-31"

"o1"

"o1-2024-12-17"

"o1-preview"

"o1-preview-2024-09-12"

"o1-mini"

"o1-mini-2024-09-12"

"gpt-4o"

"gpt-4o-2024-11-20"

"gpt-4o-2024-08-06"

"gpt-4o-2024-05-13"

"gpt-4o-audio-preview"

"gpt-4o-audio-preview-2024-10-01"

"gpt-4o-audio-preview-2024-12-17"

"gpt-4o-audio-preview-2025-06-03"

"gpt-4o-mini-audio-preview"

"gpt-4o-mini-audio-preview-2024-12-17"

"gpt-4o-search-preview"

"gpt-4o-mini-search-preview"

"gpt-4o-search-preview-2025-03-11"

"gpt-4o-mini-search-preview-2025-03-11"

"chatgpt-4o-latest"

"codex-mini-latest"

"gpt-4o-mini"

"gpt-4o-mini-2024-07-18"

"gpt-4-turbo"

"gpt-4-turbo-2024-04-09"

"gpt-4-0125-preview"

"gpt-4-turbo-preview"

"gpt-4-1106-preview"

"gpt-4-vision-preview"

"gpt-4"

"gpt-4-0314"

"gpt-4-0613"

"gpt-4-32k"

"gpt-4-32k-0314"

"gpt-4-32k-0613"

"gpt-3.5-turbo"

"gpt-3.5-turbo-16k"

"gpt-3.5-turbo-0301"

"gpt-3.5-turbo-0613"

"gpt-3.5-turbo-1106"

"gpt-3.5-turbo-0125"

"gpt-3.5-turbo-16k-0613"

"o1-pro"

"o1-pro-2025-03-19"

"o3-pro"

"o3-pro-2025-06-10"

"o3-deep-research"

"o3-deep-research-2025-06-26"

"o4-mini-deep-research"

"o4-mini-deep-research-2025-06-26"

"computer-use-preview"

"computer-use-preview-2025-03-11"

"gpt-5-codex"

"gpt-5-pro"

"gpt-5-pro-2025-10-06"

"gpt-5.1-codex-max"

(string & {})

object: "response"

output: Array<OpenAIResponseOutputMessage { id, content, role, 3 more } | OpenAIResponseFileSearchToolCall { id, queries, status, 2 more } | OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more } | 15 more>

One of the following:

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string

encrypted_content: string

type: "compaction"

created_by?: string

OpenAITypesResponsesResponseOutputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseOutputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

ResponseFunctionShellToolCall { id, action, call_id, 4 more }

A tool call that executes one or more shell commands in a managed environment.

id: string

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call"

created_by?: string

environment?: ResponseLocalEnvironment { type } | ResponseContainerReference { container_id, type }

Represents the use of a local environment to perform shell actions.

One of the following:

ResponseLocalEnvironment { type }

Represents the use of a local environment to perform shell actions.

type: "local"

ResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

container_id: string

type: "container_reference"

ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string

call_id: string

output: Array<Output>

outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutputOutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

created_by?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "shell_call_output"

created_by?: string

max_output_length?: number

ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string

call_id: string

operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:

OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string

path: string

type: "create_file"

OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string

type: "delete_file"

OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

created_by?: string

ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

created_by?: string

output?: string

OpenAITypesResponsesResponseOutputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAITypesResponsesResponseOutputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

parallel_tool_calls: boolean

tool_choice: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 5 more

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

One of the following:

"none" | "auto" | "required"

"none"

"auto"

"required"

ToolChoiceAllowed { mode, tools, type }

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

mode: "auto" | "required"

One of the following:

"auto"

"required"

tools: Array<Record<string, unknown>>

type: "allowed_tools"

ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "file_search" | "web_search_preview" | "computer_use_preview" | 3 more

One of the following:

"file_search"

"web_search_preview"

"computer_use_preview"

"web_search_preview_2025_03_11"

"image_generation"

"code_interpreter"

ToolChoiceFunction { name, type }

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

name: string

type: "function"

ToolChoiceMcp { server_label, type, name }

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

server_label: string

type: "mcp"

name?: string

ToolChoiceCustom { name, type }

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

name: string

type: "custom"

ToolChoiceApplyPatch { type }

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

type: "apply_patch"

ToolChoiceShell { type }

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

type: "shell"

tools: Array<FunctionTool { name, type, description, 2 more } | FileSearchTool { type, vector_store_ids, filters, 2 more } | ComputerTool { display_height, display_width, environment, type } | 9 more>

One of the following:

FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string

type: "function"

description?: string

parameters?: Record<string, unknown>

strict?: boolean

FileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

type: "file_search"

vector_store_ids: Array<string>

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type }

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

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

One of the following:

ComparisonFilter { key, type, value }

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

key: string

type: "eq" | "ne" | "gt" | 3 more

One of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

value: string | number | boolean | Array<string | number>

One of the following:

string

number

boolean

Array<string | number>

string

number

unknown

type: "and" | "or"

One of the following:

"and"

"or"

max_num_results?: number

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

hybrid_search?: HybridSearch { embedding_weight, text_weight }

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

embedding_weight: number

text_weight: number

ranker?: "auto" | "default-2024-11-15"

One of the following:

"auto"

"default-2024-11-15"

score_threshold?: number

ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number

display_width: number

environment: "windows" | "mac" | "linux" | 2 more

One of the following:

"windows"

"mac"

"linux"

"ubuntu"

"browser"

type: "computer_use_preview"

WebSearchTool { type, filters, search_context_size, user_location }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

One of the following:

"web_search"

"web_search_2025_08_26"

filters?: Filters { allowed_domains }

Filters for the search.

allowed_domains?: Array<string>

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { city, country, region, 2 more }

The approximate location of the user.

city?: string

country?: string

region?: string

timezone?: string

type?: "approximate"

Mcp { server_label, type, allowed_tools, 6 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

server_label: string

type: "mcp"

allowed_tools?: Array<string> | McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

One of the following:

Array<string>

McpAllowedToolsMcpToolFilter { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

authorization?: string

connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 more

One of the following:

"connector_dropbox"

"connector_gmail"

"connector_googlecalendar"

"connector_googledrive"

"connector_microsoftteams"

"connector_outlookcalendar"

"connector_outlookemail"

"connector_sharepoint"

headers?: Record<string, string>

require_approval?: McpRequireApprovalMcpToolApprovalFilter { always, never } | "always" | "never"

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

One of the following:

McpRequireApprovalMcpToolApprovalFilter { always, never }

Specify which of the MCP server’s tools require approval.

Can be always, never, or a filter object associated with tools that require approval.

always?: Always { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

never?: Never { read_only, tool_names }

A filter object to specify which tools are allowed.

read_only?: boolean

tool_names?: Array<string>

"always" | "never"

"always"

"never"

server_description?: string

server_url?: string

CodeInterpreter { container, type }

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

container: string | CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

One of the following:

string

CodeInterpreterContainerCodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

type: "auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

type: "code_interpreter"

ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

type: "image_generation"

action?: "generate" | "edit" | "auto"

One of the following:

"generate"

"edit"

"auto"

background?: "transparent" | "opaque" | "auto"

One of the following:

"transparent"

"opaque"

"auto"

input_fidelity?: "high" | "low"

One of the following:

"high"

"low"

input_image_mask?: InputImageMask { file_id, image_url }

Optional mask for inpainting.

Contains image_url (string, optional) and file_id (string, optional).

file_id?: string

image_url?: string

model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

One of the following:

(string & {})

"gpt-image-1" | "gpt-image-1-mini" | "gpt-image-1.5"

"gpt-image-1"

"gpt-image-1-mini"

"gpt-image-1.5"

moderation?: "auto" | "low"

One of the following:

"auto"

"low"

output_compression?: number

output_format?: "png" | "webp" | "jpeg"

One of the following:

"png"

"webp"

"jpeg"

partial_images?: number

quality?: "low" | "medium" | "high" | "auto"

One of the following:

"low"

"medium"

"high"

"auto"

size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto"

One of the following:

"1024x1024"

"1024x1536"

"1536x1024"

"auto"

LocalShell { type }

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

type: "local_shell"

FunctionShellTool { type, environment }

A tool that allows the model to execute shell commands.

type: "shell"

environment?: ContainerAuto { type, file_ids, memory_limit, 2 more } | LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

ContainerAuto { type, file_ids, memory_limit, 2 more }

type: "container_auto"

file_ids?: Array<string>

memory_limit?: "1g" | "4g" | "16g" | "64g"

One of the following:

"1g"

"4g"

"16g"

"64g"

network_policy?: ContainerNetworkPolicyDisabled { type } | ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

One of the following:

ContainerNetworkPolicyDisabled { type }

type: "disabled"

ContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

allowed_domains: Array<string>

type: "allowlist"

domain_secrets?: Array<DomainSecret>

domain: string

name: string

value: string

skills?: Array<SkillReference { skill_id, type, version } | InlineSkill { description, name, source, type } >

One of the following:

SkillReference { skill_id, type, version }

skill_id: string

type: "skill_reference"

version?: string

InlineSkill { description, name, source, type }

description: string

name: string

source: Source { data, media_type, type }

Inline skill payload

data: string

media_type: "application/zip"

type: "base64"

type: "inline"

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string

type: "custom"

description?: string

format?: Text { type } | Grammar { definition, syntax, type }

Unconstrained free-form text.

One of the following:

Text { type }

Unconstrained free-form text.

type: "text"

Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string

syntax: "lark" | "regex"

One of the following:

"lark"

"regex"

type: "grammar"

WebSearchPreviewTool { type, search_context_size, user_location }

This tool searches the web for relevant results to use in a response.

Learn more about the web search tool.

type: "web_search_preview" | "web_search_preview_2025_03_11"

One of the following:

"web_search_preview"

"web_search_preview_2025_03_11"

search_context_size?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

user_location?: UserLocation { type, city, country, 2 more }

The user’s location.

type: "approximate"

city?: string

country?: string

region?: string

timezone?: string

ApplyPatchTool { type }

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

type: "apply_patch"

background?: boolean

completed_at?: number

conversation?: Conversation { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

id: string

error?: OpenAIResponseError { code, message }

An error object returned when the model fails to generate a Response.

code: "server_error" | "rate_limit_exceeded" | "invalid_prompt" | 15 more

One of the following:

"server_error"

"rate_limit_exceeded"

"invalid_prompt"

"vector_store_timeout"

"invalid_image"

"invalid_image_format"

"invalid_base64_image"

"invalid_image_url"

"image_too_large"

"image_too_small"

"image_parse_error"

"image_content_policy_violation"

"invalid_image_mode"

"image_file_too_large"

"unsupported_image_media_type"

"empty_image_file"

"failed_to_download_image"

"image_file_not_found"

message: string

incomplete_details?: IncompleteDetails { reason }

Details about why the response is incomplete.

reason?: "max_output_tokens" | "content_filter"

One of the following:

"max_output_tokens"

"content_filter"

instructions?: string | Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

One of the following:

string

Array<EasyInputMessage { content, role, phase, type } | OpenAITypesResponsesResponseInputItemMessage { content, role, status, type } | OpenAIResponseOutputMessage { id, content, role, 3 more } | 23 more>

EasyInputMessage { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "assistant" | "system" | "developer"

One of the following:

"user"

"assistant"

"system"

"developer"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

type?: "message"

OpenAITypesResponsesResponseInputItemMessage { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

role: "user" | "system" | "developer"

One of the following:

"user"

"system"

"developer"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type?: "message"

OpenAIResponseOutputMessage { id, content, role, 3 more }

An output message from the model.

id: string

content: Array<OpenAIResponseOutputText { annotations, text, type, logprobs } | OpenAIResponseOutputRefusal { refusal, type } >

One of the following:

OpenAIResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >

One of the following:

AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

filename: string

index: number

type: "file_citation"

OpenAITypesResponsesResponseOutputTextAnnotationURLCitation { end_index, start_index, title, 2 more }

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

end_index: number

start_index: number

title: string

type: "url_citation"

url: string

AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

end_index: number

file_id: string

filename: string

start_index: number

type: "container_file_citation"

AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string

index: number

type: "file_path"

text: string

type: "output_text"

logprobs?: Array<Logprob>

token: string

bytes: Array<number>

logprob: number

top_logprobs: Array<TopLogprob>

token: string

bytes: Array<number>

logprob: number

OpenAIResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

type: "refusal"

role: "assistant"

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "message"

phase?: "commentary" | "final_answer"

One of the following:

"commentary"

"final_answer"

OpenAIResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string

queries: Array<string>

status: "in_progress" | "searching" | "completed" | 2 more

One of the following:

"in_progress"

"searching"

"completed"

"incomplete"

"failed"

type: "file_search_call"

results?: Array<Result>

attributes?: Record<string, string | number | boolean>

One of the following:

string

number

boolean

file_id?: string

filename?: string

score?: number

text?: string

OpenAIResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string

action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 6 more

A click action.

One of the following:

ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more

One of the following:

"left"

"right"

"wheel"

"back"

"forward"

type: "click"

x: number

y: number

ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"

x: number

y: number

ActionDrag { path, type }

A drag action.

path: Array<Path>

x: number

y: number

type: "drag"

ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>

type: "keypress"

ActionMove { type, x, y }

A mouse move action.

type: "move"

x: number

y: number

ActionScreenshot { type }

A screenshot action.

type: "screenshot"

ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number

scroll_y: number

type: "scroll"

x: number

y: number

ActionType { text, type }

An action to type in text.

text: string

type: "type"

ActionWait { type }

A wait action.

type: "wait"

call_id: string

pending_safety_checks: Array<PendingSafetyCheck>

id: string

code?: string

message?: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "computer_call"

OpenAITypesResponsesResponseInputItemComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string

output: ResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"

file_id?: string

image_url?: string

type: "computer_call_output"

id?: string

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

id: string

code?: string

message?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string

action: OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources } | OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type “search” - Performs a web search query.

One of the following:

OpenAITypesResponsesResponseFunctionWebSearchActionSearch { query, type, queries, sources }

Action type “search” - Performs a web search query.

query: string

type: "search"

queries?: Array<string>

sources?: Array<Source>

type: "url"

url: string

OpenAITypesResponsesResponseFunctionWebSearchActionOpenPage { type, url }

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

type: "open_page"

url?: string

ActionFind { pattern, type, url }

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

pattern: string

type: "find_in_page"

url: string

status: "in_progress" | "searching" | "completed" | "failed"

One of the following:

"in_progress"

"searching"

"completed"

"failed"

type: "web_search_call"

OpenAIResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string

call_id: string

name: string

type: "function_call"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAITypesResponsesResponseInputItemFunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string

output: string | Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

One of the following:

string

Array<ResponseInputTextContent { text, type } | ResponseInputImageContent { type, detail, file_id, image_url } | ResponseInputFileContent { type, file_data, file_id, 2 more } >

ResponseInputTextContent { text, type }

A text input to the model.

text: string

type: "input_text"

ResponseInputImageContent { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"

detail?: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

file_id?: string

image_url?: string

ResponseInputFileContent { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "function_call_output"

id?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

OpenAIResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string

summary: Array<Summary>

text: string

type: "summary_text"

type: "reasoning"

content?: Array<Content>

text: string

type: "reasoning_text"

encrypted_content?: string

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ResponseCompactionItemParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string

type: "compaction"

id?: string

OpenAITypesResponsesResponseInputItemImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string

status: "in_progress" | "completed" | "generating" | "failed"

One of the following:

"in_progress"

"completed"

"generating"

"failed"

type: "image_generation_call"

result?: string

OpenAIResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string

container_id: string

status: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"interpreting"

"failed"

type: "code_interpreter_call"

code?: string

outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } >

One of the following:

OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string

type: "logs"

OutputImage { type, url }

The image output from the code interpreter.

type: "image"

url: string

OpenAITypesResponsesResponseInputItemLocalShellCall { id, action, call_id, 2 more }

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

id: string

action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>

env: Record<string, string>

type: "exec"

timeout_ms?: number

user?: string

working_directory?: string

call_id: string

status: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

type: "local_shell_call"

OpenAITypesResponsesResponseInputItemLocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string

output: string

type: "local_shell_call_output"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCall { action, call_id, type, 3 more }

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

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>

max_output_length?: number

timeout_ms?: number

call_id: string

type: "shell_call"

id?: string

environment?: LocalEnvironment { type, skills } | ContainerReference { container_id, type }

One of the following:

LocalEnvironment { type, skills }

type: "local"

skills?: Array<Skill>

description: string

name: string

path: string

ContainerReference { container_id, type }

container_id: string

type: "container_reference"

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ShellCallOutput { call_id, output, type, 3 more }

The streamed output items emitted by a shell tool call.

call_id: string

output: Array<Output>

outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:

OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"

OutcomeExit { exit_code, type }

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

exit_code: number

type: "exit"

stderr: string

stdout: string

type: "shell_call_output"

id?: string

max_output_length?: number

status?: "in_progress" | "completed" | "incomplete"

One of the following:

"in_progress"

"completed"

"incomplete"

ApplyPatchCall { call_id, operation, status, 2 more }

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

call_id: string

operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:

ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string

path: string

type: "create_file"

ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string

type: "delete_file"

ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string

path: string

type: "update_file"

status: "in_progress" | "completed"

One of the following:

"in_progress"

"completed"

type: "apply_patch_call"

id?: string

ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string

status: "completed" | "failed"

One of the following:

"completed"

"failed"

type: "apply_patch_call_output"

id?: string

output?: string

OpenAITypesResponsesResponseInputItemMcpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string

server_label: string

tools: Array<Tool>

input_schema: unknown

name: string

annotations?: unknown

description?: string

type: "mcp_list_tools"

error?: string

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string

arguments: string

name: string

server_label: string

type: "mcp_approval_request"

OpenAITypesResponsesResponseInputItemMcpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string

approve: boolean

type: "mcp_approval_response"

id?: string

reason?: string

OpenAITypesResponsesResponseInputItemMcpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string

arguments: string

name: string

server_label: string

type: "mcp_call"

approval_request_id?: string

error?: string

output?: string

status?: "in_progress" | "completed" | "incomplete" | 2 more

One of the following:

"in_progress"

"completed"

"incomplete"

"calling"

"failed"

OpenAIResponseCustomToolCallOutput { call_id, output, type, id }

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

call_id: string

output: string | Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

Array<OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

type: "custom_tool_call_output"

id?: string

OpenAIResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string

input: string

name: string

type: "custom_tool_call"

id?: string

OpenAITypesResponsesResponseInputItemItemReference { id, type }

An internal identifier for an item to reference.

id: string

type?: "item_reference"

max_output_tokens?: number

max_tool_calls?: number

metadata?: Record<string, string>

previous_response_id?: string

prompt?: OpenAIResponsePrompt { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string

variables?: Record<string, string | OpenAIResponseInputText { text, type } | OpenAIResponseInputImage { detail, type, file_id, image_url } | OpenAIResponseInputFile { type, file_data, file_id, 2 more } >

One of the following:

string

OpenAIResponseInputText { text, type }

A text input to the model.

text: string

type: "input_text"

OpenAIResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"

One of the following:

"low"

"high"

"auto"

type: "input_image"

file_id?: string

image_url?: string

OpenAIResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"

file_data?: string

file_id?: string

file_url?: string

filename?: string

version?: string

prompt_cache_key?: string

prompt_cache_retention?: "in-memory" | "24h"

One of the following:

"in-memory"

"24h"

reasoning?: Reasoning { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more

One of the following:

"none"

"minimal"

"low"

"medium"

"high"

"xhigh"

generate_summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

summary?: "auto" | "concise" | "detailed"

One of the following:

"auto"

"concise"

"detailed"

safety_identifier?: string

service_tier?: "auto" | "default" | "flex" | 2 more

One of the following:

"auto"

"default"

"flex"

"scale"

"priority"

status?: "completed" | "failed" | "in_progress" | 3 more

One of the following:

"completed"

"failed"

"in_progress"

"cancelled"

"queued"

"incomplete"

temperature?: number

text?: OpenAIResponseTextConfig { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

• Text inputs and outputs
• Structured Outputs

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type }

Default response format. Used to generate text responses.

One of the following:

ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"

ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string

schema: Record<string, unknown>

type: "json_schema"

description?: string

strict?: boolean

ResponseFormatJsonObject { type }

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: "json_object"

verbosity?: "low" | "medium" | "high"

One of the following:

"low"

"medium"

"high"

top_logprobs?: number

top_p?: number

truncation?: "auto" | "disabled"

One of the following:

"auto"

"disabled"

usage?: OpenAIResponseUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens: number

input_tokens_details: InputTokensDetails { cached_tokens }

A detailed breakdown of the input tokens.

cached_tokens: number

output_tokens: number

output_tokens_details: OutputTokensDetails { reasoning_tokens }

A detailed breakdown of the output tokens.

reasoning_tokens: number

total_tokens: number

user?: string

sequence_number: number

type: "response.queued"

ResponseCustomToolCallInputDeltaEvent { delta, item_id, output_index, 2 more }

Event representing a delta (partial update) to the input of a custom tool call.

delta: string

item_id: string

output_index: number

sequence_number: number

type: "response.custom_tool_call_input.delta"

ResponseCustomToolCallInputDoneEvent { input, item_id, output_index, 2 more }

Event indicating that input for a custom tool call is complete.

input: string

item_id: string

output_index: number

sequence_number: number

type: "response.custom_tool_call_input.done"

GenericResponseEvent { type }

type: string

Run OpenAI Responses API (OpenAI only)

TypeScript

HTTP

TypeScript

Python

Go

import SGPClient from 'scale-gp';

const client = new SGPClient({
  accountID: 'My Account ID',
  apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted
});

const response = await client.responses.create({ input: 'string', model: 'model' });

console.log(response);

200 example

{
  "id": "id",
  "created_at": 0,
  "model": "gpt-5.2",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message",
      "phase": "commentary"
    }
  ],
  "parallel_tool_calls": true,
  "tool_choice": "none",
  "tools": [
    {
      "name": "name",
      "type": "function",
      "description": "description",
      "parameters": {
        "foo": "bar"
      },
      "strict": true
    }
  ],
  "background": true,
  "completed_at": 0,
  "conversation": {
    "id": "id"
  },
  "error": {
    "code": "server_error",
    "message": "message"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "instructions": "string",
  "max_output_tokens": 0,
  "max_tool_calls": 0,
  "metadata": {
    "foo": "string"
  },
  "previous_response_id": "previous_response_id",
  "prompt": {
    "id": "id",
    "variables": {
      "foo": "string"
    },
    "version": "version"
  },
  "prompt_cache_key": "prompt_cache_key",
  "prompt_cache_retention": "in-memory",
  "reasoning": {
    "effort": "none",
    "generate_summary": "auto",
    "summary": "auto"
  },
  "safety_identifier": "safety_identifier",
  "service_tier": "auto",
  "status": "completed",
  "temperature": 0,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "top_logprobs": 0,
  "top_p": 0,
  "truncation": "auto",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "user": "user"
}

Returns Examples

200 example

{
  "id": "id",
  "created_at": 0,
  "model": "gpt-5.2",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message",
      "phase": "commentary"
    }
  ],
  "parallel_tool_calls": true,
  "tool_choice": "none",
  "tools": [
    {
      "name": "name",
      "type": "function",
      "description": "description",
      "parameters": {
        "foo": "bar"
      },
      "strict": true
    }
  ],
  "background": true,
  "completed_at": 0,
  "conversation": {
    "id": "id"
  },
  "error": {
    "code": "server_error",
    "message": "message"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "instructions": "string",
  "max_output_tokens": 0,
  "max_tool_calls": 0,
  "metadata": {
    "foo": "string"
  },
  "previous_response_id": "previous_response_id",
  "prompt": {
    "id": "id",
    "variables": {
      "foo": "string"
    },
    "version": "version"
  },
  "prompt_cache_key": "prompt_cache_key",
  "prompt_cache_retention": "in-memory",
  "reasoning": {
    "effort": "none",
    "generate_summary": "auto",
    "summary": "auto"
  },
  "safety_identifier": "safety_identifier",
  "service_tier": "auto",
  "status": "completed",
  "temperature": 0,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "top_logprobs": 0,
  "top_p": 0,
  "truncation": "auto",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "user": "user"
}