openapi: 3.2.0 info: title: AIML Responses API version: 1.0.0 servers: - url: https://api.aimlapi.com tags: - name: Responses paths: /v1/responses: post: operationId: _v1_responses requestBody: required: true content: application/json: schema: anyOf: - type: object properties: model: type: string enum: - gpt-3.5-turbo - openai/gpt-3.5-turbo - gpt-3.5-turbo-0125 - openai/gpt-3.5-turbo-0125 - gpt-3.5-turbo-1106 - openai/gpt-3.5-turbo-1106 - gpt-4 - openai/gpt-4 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. top_p: type: number minimum: 0.01 maximum: 1 description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' required: - model - input title: gpt-3.5-turbo, openai/gpt-3.5-turbo, gpt-3.5-turbo-0125, openai/gpt-3.5-turbo-0125, gpt-3.5-turbo-1106, openai/gpt-3.5-turbo-1106, gpt-4, openai/gpt-4 - type: object properties: model: type: string enum: - gpt-4.1-mini - openai/gpt-4.1-mini - gpt-4.1-mini-2025-04-14 - openai/gpt-4.1-mini-2025-04-14 - gpt-4.1 - openai/gpt-4.1 - gpt-4.1-2025-04-14 - openai/gpt-4.1-2025-04-14 - gpt-4o-mini - openai/gpt-4o-mini - gpt-4o-mini-2024-07-18 - openai/gpt-4o-mini-2024-07-18 - gpt-4o - openai/gpt-4o - gpt-4o-2024-08-06 - openai/gpt-4o-2024-08-06 - gpt-4o-2024-11-20 - openai/gpt-4o-2024-11-20 - gpt-4o-2024-05-13 - openai/gpt-4o-2024-05-13 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: code: type: string description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - interpreting description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - code - id - outputs - status - type - container_id description: A tool call to run code. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. top_p: type: number minimum: 0.01 maximum: 1 description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: gpt-4.1-mini, openai/gpt-4.1-mini, gpt-4.1-mini-2025-04-14, openai/gpt-4.1-mini-2025-04-14, gpt-4.1, openai/gpt-4.1, gpt-4.1-2025-04-14, openai/gpt-4.1-2025-04-14, gpt-4o-mini, openai/gpt-4o-mini, gpt-4o-mini-2024-07-18, openai/gpt-4o-mini-2024-07-18, gpt-4o, openai/gpt-4o, gpt-4o-2024-08-06, openai/gpt-4o-2024-08-06, gpt-4o-2024-11-20, openai/gpt-4o-2024-11-20, gpt-4o-2024-05-13, openai/gpt-4o-2024-05-13 - type: object properties: model: type: string enum: - gpt-4.1-nano - openai/gpt-4.1-nano - gpt-4.1-nano-2025-04-14 - openai/gpt-4.1-nano-2025-04-14 - gpt-4-turbo - openai/gpt-4-turbo - gpt-4-turbo-2024-04-09 - openai/gpt-4-turbo-2024-04-09 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: code: type: string description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - interpreting description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - code - id - outputs - status - type - container_id description: A tool call to run code. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. top_p: type: number minimum: 0.01 maximum: 1 description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: gpt-4.1-nano, openai/gpt-4.1-nano, gpt-4.1-nano-2025-04-14, openai/gpt-4.1-nano-2025-04-14, gpt-4-turbo, openai/gpt-4-turbo, gpt-4-turbo-2024-04-09, openai/gpt-4-turbo-2024-04-09 - type: object properties: model: type: string enum: - o1 - openai/o1 - o1-2024-12-17 - openai/o1-2024-12-17 - o3-mini - openai/o3-mini - o3-mini-2025-01-31 - openai/o3-mini-2025-01-31 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: o1, openai/o1, o1-2024-12-17, openai/o1-2024-12-17, o3-mini, openai/o3-mini, o3-mini-2025-01-31, openai/o3-mini-2025-01-31 - type: object properties: model: type: string enum: - o4-mini-2025-04-16 - openai/o4-mini-2025-04-16 - o3-2025-04-16 - openai/o3-2025-04-16 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: code: type: string description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - interpreting description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - code - id - outputs - status - type - container_id description: A tool call to run code. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: o4-mini-2025-04-16, openai/o4-mini-2025-04-16, o3-2025-04-16, openai/o3-2025-04-16 - type: object properties: model: type: string enum: - gpt-5-nano-2025-08-07 - openai/gpt-5-nano-2025-08-07 - gpt-5.5-2026-04-23 - openai/gpt-5.5-2026-04-23 - gpt-5.6-sol - openai/gpt-5.6-sol - gpt-5.6-terra - openai/gpt-5.6-terra - gpt-5.6-luna - openai/gpt-5.6-luna - gpt-5-2025-08-07 - openai/gpt-5-2025-08-07 - gpt-5-mini-2025-08-07 - openai/gpt-5-mini-2025-08-07 - gpt-5 - openai/gpt-5 - gpt-5-mini - openai/gpt-5-mini - gpt-5-nano - openai/gpt-5-nano - openai/gpt-5-5 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: code: type: string description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - interpreting description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - code - id - outputs - status - type - container_id description: A tool call to run code. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' required: - model - input title: gpt-5-nano-2025-08-07, openai/gpt-5-nano-2025-08-07, gpt-5.5-2026-04-23, openai/gpt-5.5-2026-04-23, gpt-5.6-sol, openai/gpt-5.6-sol, gpt-5.6-terra, openai/gpt-5.6-terra, gpt-5.6-luna, openai/gpt-5.6-luna, gpt-5-2025-08-07, openai/gpt-5-2025-08-07, gpt-5-mini-2025-08-07, openai/gpt-5-mini-2025-08-07, gpt-5, openai/gpt-5, gpt-5-mini, openai/gpt-5-mini, gpt-5-nano, openai/gpt-5-nano, openai/gpt-5-5 - type: object properties: model: type: string enum: - gpt-5-pro - openai/gpt-5-pro - gpt-5.2-pro-2025-12-11 - openai/gpt-5.2-pro-2025-12-11 - openai/gpt-5-2-pro input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: gpt-5-pro, openai/gpt-5-pro, gpt-5.2-pro-2025-12-11, openai/gpt-5.2-pro-2025-12-11, openai/gpt-5-2-pro - type: object properties: model: type: string enum: - gpt-5.1-2025-11-13 - openai/gpt-5.1-2025-11-13 - gpt-5.2-2025-12-11 - openai/gpt-5.2-2025-12-11 - gpt-5.4-2026-03-05 - openai/gpt-5.4-2026-03-05 - openai/gpt-5-1 - openai/gpt-5-2 - openai/gpt-5-4 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: code: type: string description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - interpreting description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - code - id - outputs - status - type - container_id description: A tool call to run code. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. top_p: type: number minimum: 0.01 maximum: 1 description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' required: - model - input title: gpt-5.1-2025-11-13, openai/gpt-5.1-2025-11-13, gpt-5.2-2025-12-11, openai/gpt-5.2-2025-12-11, gpt-5.4-2026-03-05, openai/gpt-5.4-2026-03-05, openai/gpt-5-1, openai/gpt-5-2, openai/gpt-5-4 - type: object properties: model: type: string enum: - gpt-5.1-codex - openai/gpt-5.1-codex - gpt-5.1-codex-mini - openai/gpt-5.1-codex-mini - gpt-5.2-codex - openai/gpt-5.2-codex - gpt-5.3-codex - openai/gpt-5.3-codex - openai/gpt-5-1-codex - openai/gpt-5-1-codex-mini - openai/gpt-5-2-codex - openai/gpt-5-3-codex input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type description: A tool call to run a command on the local shell. - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type description: The output of a local shell tool call. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' required: - model - input title: gpt-5.1-codex, openai/gpt-5.1-codex, gpt-5.1-codex-mini, openai/gpt-5.1-codex-mini, gpt-5.2-codex, openai/gpt-5.2-codex, gpt-5.3-codex, openai/gpt-5.3-codex, openai/gpt-5-1-codex, openai/gpt-5-1-codex-mini, openai/gpt-5-2-codex, openai/gpt-5-3-codex - type: object properties: model: type: string enum: - gpt-5.2-chat-latest - openai/gpt-5.2-chat-latest - gpt-5.4-pro-2026-03-05 - openai/gpt-5.4-pro-2026-03-05 - gpt-5.5-pro-2026-04-23 - openai/gpt-5.5-pro-2026-04-23 - openai/gpt-5-2-chat-latest - openai/gpt-5-4-pro - openai/gpt-5-5-pro input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: code: type: string description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - interpreting description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - code - id - outputs - status - type - container_id description: A tool call to run code. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: gpt-5.2-chat-latest, openai/gpt-5.2-chat-latest, gpt-5.4-pro-2026-03-05, openai/gpt-5.4-pro-2026-03-05, gpt-5.5-pro-2026-04-23, openai/gpt-5.5-pro-2026-04-23, openai/gpt-5-2-chat-latest, openai/gpt-5-4-pro, openai/gpt-5-5-pro - type: object properties: model: type: string enum: - o3-pro - openai/o3-pro input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type description: The results of a web search tool call. - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type description: A tool call to run a function. - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type description: The output of a function tool call. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: type: object additionalProperties: {} description: The JSON schema describing the tool's input. name: type: string description: The name of the tool. annotations: type: - object - 'null' additionalProperties: {} description: Additional annotations about the tool. description: type: - string - 'null' description: The description of the tool. required: - input_schema - name description: The tools available on the server. type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type description: A list of tools available on an MCP server. - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type description: A request for human approval of a tool invocation. - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type description: A response to an MCP approval request. - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type description: An invocation of a tool on an MCP server. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: name: type: string description: The name of the function to call. parameters: type: object additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: anyOf: - type: boolean - {} - {} description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: string description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - parameters - type description: Defines a function in your own code the model can choose to call. - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. required: - model - input title: o3-pro, openai/o3-pro - type: object properties: model: type: string enum: - test/dummy-responses input: type: string minLength: 1 instructions: type: string max_output_tokens: type: integer minimum: 1 stream: type: boolean enum: - false test: type: object properties: delay: type: number runningPolls: type: number tokens: type: number errorStatus: type: number submitErrorStatus: type: number required: - model - input title: test/dummy-responses - type: object properties: model: type: string enum: - x-ai/grok-4-3 - grok-4-3 input: anyOf: - type: string description: A text input to the model, equivalent to a text input with the user role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. description: A list of one or many input items to the model, containing different content types. required: - role - content description: 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. - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content description: An output message from the model. - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type description: A description of the chain of thought used by a reasoning model while generating a response. - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: Text, image, or file inputs to the model, used to generate a response. background: type: boolean default: false description: Whether to run the model response in the background. instructions: type: - string - 'null' description: 'A system (or developer) message inserted into the model''s context. When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.' include: type: - array - 'null' items: type: string enum: - message.input_image.image_url - computer_call_output.output.image_url - reasoning.encrypted_content - code_interpreter_call.outputs description: 'Specify additional output data to include in the model response. Currently supported values are: - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). ' max_output_tokens: type: integer minimum: 16 description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: anyOf: - type: string - oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. store: type: - boolean - 'null' default: false description: Whether to store the generated model response for later retrieval via API. stream: type: - boolean - 'null' default: false description: 'If set to true, the model response data will be streamed to the client as it is generated using server-sent events. ' text: type: object properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. required: - format description: Configuration options for a text response from the model. Can be plain text or structured JSON data. truncation: type: string enum: - auto - disabled default: disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' tools: type: array items: anyOf: - type: object properties: type: type: string enum: - web_search filters: type: object properties: allowed_domains: type: array items: type: string minLength: 1 description: Restrict results to these domains. Mutually exclusive with excluded_domains (enforced by xAI). excluded_domains: type: array items: type: string minLength: 1 description: Exclude results from these domains. description: Domain include/exclude filters for the web search. enable_image_understanding: type: boolean description: Let Grok analyze images found on matching pages. enable_image_search: type: boolean description: Include image search results. required: - type description: xAI Agent Tools web_search. Documented here; validated by xAI (passthrough). - type: object properties: type: type: string enum: - x_search allowed_x_handles: type: array items: type: string minLength: 1 description: Restrict the search to posts from these X handles. Mutually exclusive with excluded_x_handles (enforced by xAI). excluded_x_handles: type: array items: type: string minLength: 1 description: Exclude posts from these X handles. from_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Earliest post date to consider, ISO8601 (YYYY-MM-DD). to_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Latest post date to consider, ISO8601 (YYYY-MM-DD). enable_image_understanding: type: boolean description: Let Grok analyze images attached to matching posts. enable_video_understanding: type: boolean description: Let Grok analyze videos attached to matching posts. required: - type description: xAI Agent Tools x_search — real-time X (Twitter) search. Documented here; validated by xAI (passthrough). - type: object properties: type: type: string minLength: 1 required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: How the model should select which tool (or tools) to use when generating a response. parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run tool calls in parallel. reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: 'o-series models only Configuration options for reasoning models.' required: - model - input title: x-ai/grok-4-3, grok-4-3 responses: '200': content: application/json: schema: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls text/event-stream: schema: oneOf: - type: object properties: delta: type: string description: The text delta that was added. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.audio.delta description: The type of the event. required: - delta - sequence_number - type - type: object properties: sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.audio.done description: The type of the event. required: - sequence_number - type - type: object properties: delta: type: string description: The text delta that was added. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.audio.transcript.delta description: The type of the event. required: - delta - sequence_number - type - type: object properties: sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.audio.transcript.done description: The type of the event. required: - sequence_number - type - type: object properties: delta: type: string description: The partial code snippet being streamed by the code interpreter. item_id: type: string description: The unique identifier of the code interpreter tool call item. output_index: type: number sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.code_interpreter_call_code.delta description: The type of the event. required: - delta - item_id - output_index - sequence_number - type - type: object properties: code: type: string description: The final code snippet output by the code interpreter. item_id: type: string description: The unique identifier of the code interpreter tool call item. output_index: type: number description: The index of the output item in the response for which the code is finalized. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.code_interpreter_call_code.done description: The type of the event. required: - code - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the code interpreter tool call item. output_index: type: number description: The index of the output item in the response for which the code interpreter call is completed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.code_interpreter_call.completed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the code interpreter tool call item. output_index: type: number description: The index of the output item in the response for which the code interpreter call is in progress. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.code_interpreter_call.in_progress description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the code interpreter tool call item. output_index: type: number description: The index of the output item in the response for which the code interpreter is interpreting code. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.code_interpreter_call.interpreting description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: response: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls description: Properties of the completed response. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.completed description: The type of the event. required: - response - sequence_number - type - type: object properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. param: type: string description: The error parameter. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - error description: The type of the event. required: - code - message - param - sequence_number - type - type: object properties: item_id: type: string description: The ID of the output item that the file search call is initiated. output_index: type: number description: The index of the output item that the file search call is initiated. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.file_search_call.completed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the output item that the file search call is initiated. output_index: type: number description: The index of the output item that the file search call is initiated. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.file_search_call.in_progress description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the output item that the file search call is initiated. output_index: type: number description: The index of the output item that the file search call is searching. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.file_search_call.searching description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: delta: type: string description: The function-call arguments delta that is added. item_id: type: string description: The ID of the output item that the function-call arguments delta is added to. output_index: type: number description: The index of the output item that the function-call arguments delta is added to. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.function_call_arguments.delta description: The type of the event. required: - delta - item_id - output_index - sequence_number - type - type: object properties: arguments: type: string description: The function-call arguments. item_id: type: string description: The ID of the item. output_index: type: number sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.function_call_arguments.done description: The type of the event. required: - arguments - item_id - output_index - sequence_number - type - type: object properties: response: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls description: The response that in progress. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.in_progress description: The type of the event. required: - response - sequence_number - type - type: object properties: response: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls description: The response that failed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.failed description: The type of the event. required: - response - sequence_number - type - type: object properties: response: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls description: The response that was incomplete. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.incomplete description: The type of the event. required: - response - sequence_number - type - type: object properties: item: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: The output item that was added. output_index: type: number description: The index of the output item that was added. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.output_item.added description: The type of the event. required: - item - output_index - sequence_number - type - type: object properties: item: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: The output item that was marked done. output_index: type: number description: The index of the output item that was marked done. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.output_item.done description: The type of the event. required: - item - output_index - sequence_number - type - type: object properties: delta: type: string description: The text delta that was added to the summary. item_id: type: string description: The ID of the item this summary text delta is associated with. output_index: type: number description: The index of the output item this summary text delta is associated with. sequence_number: type: number description: The sequence number of this event. summary_index: type: number description: The index of the summary part within the reasoning summary. type: type: string enum: - response.reasoning_summary_text.delta description: The type of the event. required: - delta - item_id - output_index - sequence_number - summary_index - type - type: object properties: item_id: type: string description: The ID of the item this summary text is associated with. output_index: type: number description: The index of the output item this summary text is associated with. sequence_number: type: number description: The sequence number of this event. summary_index: type: number description: The index of the summary part within the reasoning summary. text: type: string description: The full text of the completed reasoning summary. type: type: string enum: - response.reasoning_summary_text.done description: The type of the event. required: - item_id - output_index - sequence_number - summary_index - text - type - type: object properties: content_index: type: number description: The index of the reasoning content part this delta is associated with. delta: type: string description: The text delta that was added to the reasoning content. item_id: type: string description: The ID of the item this reasoning text delta is associated with. output_index: type: number description: The index of the output item this reasoning text delta is associated with. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.reasoning_text.delta description: The type of the event. required: - content_index - delta - item_id - output_index - sequence_number - type - type: object properties: content_index: type: number description: The index of the reasoning content part. item_id: type: string description: The ID of the item this reasoning text is associated with. output_index: type: number description: The index of the output item this reasoning text is associated with. sequence_number: type: number description: The sequence number of this event. text: type: string description: The full text of the completed reasoning content. type: type: string enum: - response.reasoning_text.done description: The type of the event. required: - content_index - item_id - output_index - sequence_number - text - type - type: object properties: content_index: type: number description: The index of the content part that the refusal text is added to. delta: type: string description: The refusal text that is added. item_id: type: string description: The ID of the output item that the refusal text is added to. output_index: type: number description: The index of the output item that the refusal text is added to. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.refusal.delta description: The type of the event. required: - content_index - delta - item_id - output_index - sequence_number - type - type: object properties: content_index: type: number description: The index of the content part that the refusal text is finalized. item_id: type: string description: The ID of the output item that the refusal text is finalized. output_index: type: number description: The index of the output item that the refusal text is finalized. refusal: type: string description: The refusal text that is finalized. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.refusal.done description: The type of the event. required: - content_index - item_id - output_index - refusal - sequence_number - type - type: object properties: item_id: type: string description: Unique ID for the output item associated with the web search call. output_index: type: number description: The index of the output item that the web search call is associated with. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.web_search_call.completed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: Unique ID for the output item associated with the web search call. output_index: type: number description: The index of the output item that the web search call is associated with. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.web_search_call.in_progress description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: Unique ID for the output item associated with the web search call. output_index: type: number description: The index of the output item that the web search call is associated with. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.web_search_call.searching description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the image generation item being processed. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.image_generation_call.completed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the image generation item being processed. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.image_generation_call.generating description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the image generation item being processed. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.image_generation_call.in_progress description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the image generation item being processed. output_index: type: number description: The index of the output item in the response's output array. partial_image_b64: type: string description: Base64-encoded partial image data, suitable for rendering as an image. partial_image_index: type: number description: 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.image_generation_call.partial_image description: The type of the event. required: - item_id - output_index - partial_image_b64 - partial_image_index - sequence_number - type - type: object properties: delta: type: string description: A JSON string containing the partial update to the arguments for the MCP tool call. item_id: type: string description: The unique identifier of the MCP tool call item being processed. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_call_arguments.delta description: The type of the event. required: - delta - item_id - output_index - sequence_number - type - type: object properties: arguments: type: string description: A JSON string containing the finalized arguments for the MCP tool call. item_id: type: string description: The unique identifier of the MCP tool call item being processed. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_call_arguments.done description: The type of the event. required: - arguments - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the MCP tool call item that completed. output_index: type: number description: The index of the output item that completed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_call.completed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the MCP tool call item that failed. output_index: type: number description: The index of the output item that failed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_call.failed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The unique identifier of the MCP tool call item being processed. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_call.in_progress description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the MCP tool call item that produced this output. output_index: type: number description: The index of the output item that was processed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_list_tools.completed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the MCP tool call item that failed. output_index: type: number description: The index of the output item that failed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_list_tools.failed description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the MCP tool call item that is being processed. output_index: type: number description: The index of the output item that is being processed. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.mcp_list_tools.in_progress description: The type of the event. required: - item_id - output_index - sequence_number - type - type: object properties: annotation: description: The annotation object being added. annotation_index: type: number description: The index of the annotation within the content part. content_index: type: number description: The index of the content part within the output item. item_id: type: string description: The unique identifier of the item to which the annotation is being added. output_index: type: number description: The index of the output item in the response's output array. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.output_text.annotation.added description: The type of the event. required: - annotation_index - content_index - item_id - output_index - sequence_number - type - type: object properties: response: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls description: The full response object that is queued. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.queued description: The type of the event. required: - response - sequence_number - type - type: object properties: delta: type: string description: The incremental input data (delta) for the custom tool call. item_id: type: string description: Unique identifier for the API item associated with this event. output_index: type: number description: The index of the output this delta applies to. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.custom_tool_call_input.delta description: The type of the event. required: - delta - item_id - output_index - sequence_number - type - type: object properties: input: type: string description: The complete input data for the custom tool call. item_id: type: string description: Unique identifier for the API item associated with this event. output_index: type: number description: The index of the output this event applies to. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.custom_tool_call_input.done description: The type of the event. required: - input - item_id - output_index - sequence_number - type - type: object properties: item_id: type: string description: The ID of the item this summary part is associated with. output_index: type: number description: The index of the output item this summary part is associated with. part: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the event. required: - text - type description: The completed summary part. sequence_number: type: number description: The sequence number of this event. summary_index: type: number description: The index of the summary part within the reasoning summary. type: type: string enum: - response.reasoning_summary_part.done description: The type of the event. required: - item_id - output_index - part - sequence_number - summary_index - type - type: object properties: content_index: type: number description: The index of the content part that the text content is finalized. item_id: type: string description: The ID of the output item that the text content is finalized. logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number top_logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number required: - token - bytes - logprob required: - token - bytes - logprob - top_logprobs description: The log probabilities of the tokens in the delta. output_index: type: number description: The index of the output item that the text content is finalized. sequence_number: type: number description: The sequence number of this event. text: type: string description: The text content that is finalized. type: type: string enum: - response.output_text.done description: The type of the event. required: - content_index - item_id - logprobs - output_index - sequence_number - text - type - type: object properties: item_id: type: string description: The ID of the item this summary part is associated with. output_index: type: number description: The index of the output item this summary part is associated with. part: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the event. required: - text - type description: The summary part that was added. sequence_number: type: number description: The sequence number of this event. summary_index: type: number description: The index of the summary part within the reasoning summary. type: type: string enum: - response.reasoning_summary_part.added description: The type of the event. required: - item_id - output_index - part - sequence_number - summary_index - type - type: object properties: content_index: type: number description: The index of the content part that the text delta was added to. delta: type: string description: The text delta that was added. item_id: type: string description: The ID of the output item that the text delta was added to. logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number top_logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number required: - token - bytes - logprob required: - token - bytes - logprob - top_logprobs description: The log probabilities of the tokens in the delta. output_index: type: number description: The index of the output item that the text delta was added to. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.output_text.delta description: The type of the event. required: - content_index - delta - item_id - logprobs - output_index - sequence_number - type - type: object properties: content_index: type: number description: The index of the content part that is done. item_id: type: string description: The ID of the output item that the content part was added to. output_index: type: number description: The index of the output item that the content part was added to. part: anyOf: - type: object properties: annotations: type: array items: anyOf: - type: object properties: file_id: type: string filename: type: string index: type: number type: type: string enum: - file_citation description: The type of the event. required: - file_id - filename - index - type - type: object properties: end_index: type: number description: The index of the last character of the URL citation in the message. start_index: type: number description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the event. url: type: string description: The URL of the web resource. required: - end_index - start_index - title - type - url - type: object properties: container_id: type: string end_index: type: number file_id: type: string filename: type: string start_index: type: number type: type: string enum: - container_file_citation description: The type of the event. required: - container_id - end_index - file_id - filename - start_index - type - type: object properties: file_id: type: string index: type: number type: type: string enum: - file_path description: The type of the event. required: - file_id - index - type text: type: string type: type: string enum: - output_text description: The type of the event. logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number top_logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number required: - token - bytes - logprob required: - token - bytes - logprob - top_logprobs required: - annotations - text - type - logprobs - type: object properties: refusal: type: string description: The refusal text that is finalized. type: type: string enum: - refusal description: The type of the event. required: - refusal - type - type: object properties: text: type: string description: Configuration options for a text response from the model. Can be plain text or structured JSON data. type: type: string enum: - reasoning_text description: The type of the event. required: - text - type description: The content part that is done. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.content_part.done description: The type of the event. required: - content_index - item_id - output_index - part - sequence_number - type - type: object properties: response: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls description: The response that was created. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.created description: The type of the event. required: - response - sequence_number - type - type: object properties: content_index: type: number description: The index of the content part that was added. item_id: type: string description: The ID of the output item that the content part was added to. output_index: type: number description: The index of the output item that the content part was added to. part: anyOf: - type: object properties: annotations: type: array items: anyOf: - type: object properties: file_id: type: string filename: type: string index: type: number type: type: string enum: - file_citation description: The type of the event. required: - file_id - filename - index - type - type: object properties: end_index: type: number description: The index of the last character of the URL citation in the message. start_index: type: number description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the event. url: type: string description: The URL of the web resource. required: - end_index - start_index - title - type - url - type: object properties: container_id: type: string end_index: type: number file_id: type: string filename: type: string start_index: type: number type: type: string enum: - container_file_citation description: The type of the event. required: - container_id - end_index - file_id - filename - start_index - type - type: object properties: file_id: type: string index: type: number type: type: string enum: - file_path description: The type of the event. required: - file_id - index - type text: type: string type: type: string enum: - output_text description: The type of the event. logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number top_logprobs: type: array items: type: object properties: token: type: string bytes: type: array items: type: number logprob: type: number required: - token - bytes - logprob required: - token - bytes - logprob - top_logprobs required: - annotations - text - type - logprobs - type: object properties: refusal: type: string description: The refusal text that is finalized. type: type: string enum: - refusal description: The type of the event. required: - refusal - type - type: object properties: text: type: string description: Configuration options for a text response from the model. Can be plain text or structured JSON data. type: type: string enum: - reasoning_text description: The type of the event. required: - text - type description: The content part that was added. sequence_number: type: number description: The sequence number of this event. type: type: string enum: - response.content_part.added description: The type of the event. required: - content_index - item_id - output_index - part - sequence_number - type tags: - Responses summary: V1 responses x-summary-source: derived /v1/responses/:response_id: get: operationId: _v1_responses_:response_id requestBody: required: true content: application/json: schema: type: object properties: model: type: string enum: - gpt-3.5-turbo - openai/gpt-3.5-turbo - gpt-3.5-turbo-0125 - openai/gpt-3.5-turbo-0125 - gpt-3.5-turbo-1106 - openai/gpt-3.5-turbo-1106 - gpt-4 - openai/gpt-4 - gpt-4.1-mini - openai/gpt-4.1-mini - gpt-4.1-mini-2025-04-14 - openai/gpt-4.1-mini-2025-04-14 - gpt-4.1-nano - openai/gpt-4.1-nano - gpt-4.1-nano-2025-04-14 - openai/gpt-4.1-nano-2025-04-14 - gpt-4.1 - openai/gpt-4.1 - gpt-4.1-2025-04-14 - openai/gpt-4.1-2025-04-14 - gpt-4-turbo - openai/gpt-4-turbo - gpt-4-turbo-2024-04-09 - openai/gpt-4-turbo-2024-04-09 - gpt-4o-mini - openai/gpt-4o-mini - gpt-4o-mini-2024-07-18 - openai/gpt-4o-mini-2024-07-18 - gpt-4o - openai/gpt-4o - gpt-4o-2024-08-06 - openai/gpt-4o-2024-08-06 - gpt-4o-2024-11-20 - openai/gpt-4o-2024-11-20 - gpt-4o-2024-05-13 - openai/gpt-4o-2024-05-13 - o1 - openai/o1 - o1-2024-12-17 - openai/o1-2024-12-17 - o3-mini - openai/o3-mini - o3-mini-2025-01-31 - openai/o3-mini-2025-01-31 - o4-mini-2025-04-16 - openai/o4-mini-2025-04-16 - gpt-5-nano-2025-08-07 - openai/gpt-5-nano-2025-08-07 - gpt-5-pro - openai/gpt-5-pro - gpt-5.1-2025-11-13 - openai/gpt-5.1-2025-11-13 - gpt-5.1-codex - openai/gpt-5.1-codex - gpt-5.1-codex-mini - openai/gpt-5.1-codex-mini - gpt-5.2-2025-12-11 - openai/gpt-5.2-2025-12-11 - gpt-5.2-chat-latest - openai/gpt-5.2-chat-latest - gpt-5.2-pro-2025-12-11 - openai/gpt-5.2-pro-2025-12-11 - gpt-5.2-codex - openai/gpt-5.2-codex - gpt-5.3-codex - openai/gpt-5.3-codex - gpt-5.4-2026-03-05 - openai/gpt-5.4-2026-03-05 - gpt-5.4-pro-2026-03-05 - openai/gpt-5.4-pro-2026-03-05 - gpt-5.5-2026-04-23 - openai/gpt-5.5-2026-04-23 - gpt-5.5-pro-2026-04-23 - openai/gpt-5.5-pro-2026-04-23 - gpt-5.6-sol - openai/gpt-5.6-sol - gpt-5.6-terra - openai/gpt-5.6-terra - gpt-5.6-luna - openai/gpt-5.6-luna - o3-pro - openai/o3-pro - o3-2025-04-16 - openai/o3-2025-04-16 - gpt-5-2025-08-07 - openai/gpt-5-2025-08-07 - gpt-5-mini-2025-08-07 - openai/gpt-5-mini-2025-08-07 - gpt-5 - openai/gpt-5 - gpt-5-mini - openai/gpt-5-mini - gpt-5-nano - openai/gpt-5-nano - openai/gpt-5-1 - openai/gpt-5-1-codex - openai/gpt-5-1-codex-mini - openai/gpt-5-2 - openai/gpt-5-2-chat-latest - openai/gpt-5-2-pro - openai/gpt-5-2-codex - openai/gpt-5-3-codex - openai/gpt-5-4 - openai/gpt-5-4-pro - openai/gpt-5-5 - openai/gpt-5-5-pro - test/dummy-responses id: type: string required: - model - id title: gpt-3.5-turbo, openai/gpt-3.5-turbo, gpt-3.5-turbo-0125, openai/gpt-3.5-turbo-0125, gpt-3.5-turbo-1106, openai/gpt-3.5-turbo-1106, gpt-4, openai/gpt-4, gpt-4.1-mini, openai/gpt-4.1-mini, gpt-4.1-mini-2025-04-14, openai/gpt-4.1-mini-2025-04-14, gpt-4.1-nano, openai/gpt-4.1-nano, gpt-4.1-nano-2025-04-14, openai/gpt-4.1-nano-2025-04-14, gpt-4.1, openai/gpt-4.1, gpt-4.1-2025-04-14, openai/gpt-4.1-2025-04-14, gpt-4-turbo, openai/gpt-4-turbo, gpt-4-turbo-2024-04-09, openai/gpt-4-turbo-2024-04-09, gpt-4o-mini, openai/gpt-4o-mini, gpt-4o-mini-2024-07-18, openai/gpt-4o-mini-2024-07-18, gpt-4o, openai/gpt-4o, gpt-4o-2024-08-06, openai/gpt-4o-2024-08-06, gpt-4o-2024-11-20, openai/gpt-4o-2024-11-20, gpt-4o-2024-05-13, openai/gpt-4o-2024-05-13, o1, openai/o1, o1-2024-12-17, openai/o1-2024-12-17, o3-mini, openai/o3-mini, o3-mini-2025-01-31, openai/o3-mini-2025-01-31, o4-mini-2025-04-16, openai/o4-mini-2025-04-16, gpt-5-nano-2025-08-07, openai/gpt-5-nano-2025-08-07, gpt-5-pro, openai/gpt-5-pro, gpt-5.1-2025-11-13, openai/gpt-5.1-2025-11-13, gpt-5.1-codex, openai/gpt-5.1-codex, gpt-5.1-codex-mini, openai/gpt-5.1-codex-mini, gpt-5.2-2025-12-11, openai/gpt-5.2-2025-12-11, gpt-5.2-chat-latest, openai/gpt-5.2-chat-latest, gpt-5.2-pro-2025-12-11, openai/gpt-5.2-pro-2025-12-11, gpt-5.2-codex, openai/gpt-5.2-codex, gpt-5.3-codex, openai/gpt-5.3-codex, gpt-5.4-2026-03-05, openai/gpt-5.4-2026-03-05, gpt-5.4-pro-2026-03-05, openai/gpt-5.4-pro-2026-03-05, gpt-5.5-2026-04-23, openai/gpt-5.5-2026-04-23, gpt-5.5-pro-2026-04-23, openai/gpt-5.5-pro-2026-04-23, gpt-5.6-sol, openai/gpt-5.6-sol, gpt-5.6-terra, openai/gpt-5.6-terra, gpt-5.6-luna, openai/gpt-5.6-luna, o3-pro, openai/o3-pro, o3-2025-04-16, openai/o3-2025-04-16, gpt-5-2025-08-07, openai/gpt-5-2025-08-07, gpt-5-mini-2025-08-07, openai/gpt-5-mini-2025-08-07, gpt-5, openai/gpt-5, gpt-5-mini, openai/gpt-5-mini, gpt-5-nano, openai/gpt-5-nano, openai/gpt-5-1, openai/gpt-5-1-codex, openai/gpt-5-1-codex-mini, openai/gpt-5-2, openai/gpt-5-2-chat-latest, openai/gpt-5-2-pro, openai/gpt-5-2-codex, openai/gpt-5-3-codex, openai/gpt-5-4, openai/gpt-5-4-pro, openai/gpt-5-5, openai/gpt-5-5-pro, test/dummy-responses responses: '200': content: application/json: schema: type: object properties: background: type: - boolean - 'null' description: Whether to run the model response in the background. example: false created_at: type: number description: Unix timestamp (in seconds) of when this Response was created. example: 1762343744 error: type: - object - 'null' properties: code: type: string description: The error code for the response. message: type: string description: A human-readable description of the error. required: - code - message description: An error object returned when the model fails to generate a Response. example: null id: type: string description: Unique identifier for this Response. example: resp_68963fb142d08197b4d3ae3ad852542c054845c6ea84caa2 incomplete_details: type: - object - 'null' properties: reason: type: string description: The reason why the response is incomplete. description: Details about why the response is incomplete. example: null instructions: anyOf: - type: string description: A text input to the model, equivalent to a text input with the developer role. - type: array items: anyOf: - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - assistant - system - developer description: The role of the message input. content: anyOf: - type: string description: A text input to the model. - type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. description: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. required: - role - content description: 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. - type: object properties: type: type: string enum: - message description: The type of the message input. Always message. role: type: string enum: - user - system - developer description: The role of the message input. status: type: string enum: - in_progress - completed - incomplete description: The status of item. content: type: array items: oneOf: - type: object properties: type: type: string enum: - input_text description: The type of the input item. Always input_text. text: type: string description: The text input to the model. required: - type - text description: A text input to the model. - type: object properties: type: type: string enum: - input_image description: The type of the input item. Always input_image. detail: type: string enum: - high - low - auto default: auto description: The detail level of the image to be sent to the model. One of high, low, or auto. image_url: type: - string - 'null' description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. required: - type - type: object properties: type: type: string enum: - input_file description: The type of the input item. Always input_file. file_data: type: string description: The content of the file to be sent to the model. filename: type: string description: The name of the file to be sent to the model. required: - type description: A list of one or many input items to the model, containing different content types. required: - role - content - type: object properties: id: type: string description: The unique ID of the output message. role: type: string enum: - assistant description: The role of the output message. Always assistant. status: type: string enum: - in_progress - completed - incomplete description: The status of the message input. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - id - role - status - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: A JSON string of the output of the function tool call. type: type: string enum: - function_call_output description: The type of the function tool call output. Always function_call_output. id: type: - string - 'null' description: The unique ID of the function tool call output. Populated when this item is returned via API. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - call_id - output - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the local shell tool call generated by the model. output: type: string description: A JSON string of the output of the local shell tool call. type: type: string enum: - local_shell_call_output description: The type of the local shell tool call output. Always local_shell_call_output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the item. required: - id - output - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: approval_request_id: type: string description: The ID of the approval request being answered. approve: type: boolean description: Whether the request was approved. type: type: string enum: - mcp_approval_response description: The type of the item. Always mcp_approval_response. id: type: - string - 'null' description: The unique ID of the approval response. reason: type: - string - 'null' description: Optional reason for the decision. required: - approval_request_id - approve - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: id: type: string description: The ID of the item to reference. type: type: - string - 'null' enum: - item_reference description: The type of item to reference. Always item_reference. required: - id description: An internal identifier for an item to reference. description: A list of one or many input items to the model, containing different content types. - {} description: A system (or developer) message inserted into the model's context. example: null max_output_tokens: type: - integer - 'null' description: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. example: null metadata: type: - object - 'null' additionalProperties: {} description: 'Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.' example: {} model: type: string description: Model ID used to generate the response. example: gpt-5-chat-latest object: type: string enum: - response description: The object type of this resource - always set to response. example: response output: type: - array - 'null' items: oneOf: - type: object properties: role: type: string enum: - assistant description: The role of the output message. Always assistant. type: type: string enum: - message description: The type of the output message. Always message. content: type: array items: oneOf: - type: object properties: annotations: type: array items: oneOf: - type: object properties: end_index: type: integer description: The index of the last character of the URL citation in the message. start_index: type: integer description: The index of the first character of the URL citation in the message. title: type: string description: The title of the web resource. type: type: string enum: - url_citation description: The type of the URL citation. Always url_citation. url: type: string format: uri description: The URL of the web resource. required: - end_index - start_index - title - type - url description: A citation for a web resource used to generate a model response. - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_citation required: - file_id - index - type - type: object properties: container_id: type: string start_index: type: integer end_index: type: integer file_id: type: string type: type: string enum: - container_file_citation required: - container_id - start_index - end_index - file_id - type - type: object properties: file_id: type: string index: type: integer type: type: string enum: - file_path required: - file_id - index - type description: The annotations of the text output. text: type: string description: The text output from the model. type: type: string enum: - output_text description: The type of the output text. Always output_text. logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string top_logprobs: type: array items: type: object properties: bytes: type: array items: type: integer logprob: type: number token: type: string required: - bytes - logprob - token required: - bytes - logprob - token - top_logprobs required: - annotations - text - type - type: object properties: refusal: type: string description: The refusal explanationfrom the model. type: type: string enum: - refusal description: The type of the refusal. Always refusal. required: - refusal - type description: The content of the output message. required: - role - type - content - type: object properties: id: type: string queries: type: array items: type: string status: type: string enum: - in_progress - searching - incomplete - failed - completed type: type: string enum: - file_search_call results: type: - array - 'null' items: type: object properties: attributes: type: - object - 'null' additionalProperties: anyOf: - type: string - type: number - type: boolean file_id: type: string filename: type: string score: type: number text: type: string required: - id - queries - status - type - type: object properties: action: oneOf: - type: object properties: button: type: string enum: - left - right - wheel - back - forward description: Indicates which mouse button was pressed during the click. type: type: string enum: - click description: Specifies the event type. For a click action, this property is always set to click. x: type: integer description: The x-coordinate where the click occurred. y: type: integer description: The y-coordinate where the click occurred. required: - button - type - x - y description: A click action. - type: object properties: type: type: string enum: - double_click description: Specifies the event type. For a double click action, this property is always set to double_click. x: type: integer description: The x-coordinate where the double click occurred. y: type: integer description: The y-coordinate where the double click occurred. required: - type - x - y description: A double click action. - type: object properties: path: type: array items: type: object properties: x: type: integer description: The y-coordinate. y: type: integer description: The y-coordinate. required: - x - y description: An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg type: type: string enum: - drag description: Specifies the event type. For a drag action, this property is always set to drag. required: - path - type description: A drag action. - type: object properties: keys: type: array items: type: string description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. type: type: string enum: - keypress description: Specifies the event type. For a keypress action, this property is always set to keypress. required: - keys - type description: A collection of keypresses the model would like to perform. - type: object properties: type: type: string enum: - move description: Specifies the event type. For a move action, this property is always set to move. x: type: integer description: The x-coordinate to move to. y: type: integer description: The y-coordinate to move to. required: - type - x - y description: A mouse move action. - type: object properties: type: type: string enum: - screenshot description: Specifies the event type. For a screenshot action, this property is always set to screenshot. required: - type description: A screenshot action. - type: object properties: type: type: string enum: - scroll description: Specifies the event type. For a scroll action, this property is always set to scroll. scroll_x: type: integer description: The horizontal scroll distance. scroll_y: type: integer description: The vertical scroll distance. x: type: integer description: The x-coordinate where the scroll occurred. y: type: integer description: The y-coordinate where the scroll occurred. required: - type - scroll_x - scroll_y - x - y description: A scroll action. - type: object properties: type: type: string enum: - type description: Specifies the event type. For a type action, this property is always set to type. text: type: string description: The text to type. required: - type - text description: An action to type in text. - type: object properties: type: type: string enum: - wait description: Specifies the event type. For a wait action, this property is always set to wait. required: - type description: A wait action. call_id: type: string description: An identifier used when responding to the tool call with output. id: type: string description: The unique ID of the computer call. pending_safety_checks: type: array items: type: object properties: code: type: string description: The type of the pending safety check. id: type: string description: The ID of the pending safety check. message: type: string description: Details about the pending safety check. required: - code - id - message description: The pending safety checks for the computer call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. type: type: string enum: - computer_call description: The type of the computer call. Always computer_call. required: - action - call_id - id - pending_safety_checks - status - type - type: object properties: call_id: type: string description: The ID of the computer tool call that produced the output. output: type: object properties: type: type: string enum: - computer_screenshot description: Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. image_url: type: string format: uri description: The URL of the screenshot image. required: - type description: A computer screenshot image used with the computer use tool. type: type: string enum: - computer_call_output description: The type of the computer tool call output. Always computer_call_output. acknowledged_safety_checks: type: - array - 'null' items: type: object properties: id: type: string description: The ID of the pending safety check. code: type: - string - 'null' description: The type of the pending safety check. message: type: - string - 'null' description: Details about the pending safety check. required: - id description: The safety checks reported by the API that have been acknowledged by the developer. id: type: - string - 'null' description: The ID of the computer tool call output. status: type: - string - 'null' enum: - in_progress - completed - incomplete description: The status of the message input. required: - call_id - output - type - type: object properties: id: type: string description: The unique ID of the web search tool call. status: type: string enum: - in_progress - completed - searching - failed description: The status of the web search tool call. type: type: string enum: - web_search_call description: The type of the web search tool call. Always web_search_call. required: - id - status - type - type: object properties: arguments: type: string description: A JSON string of the arguments to pass to the function. call_id: type: string description: The unique ID of the function tool call generated by the model. name: type: string description: The name of the function to run. type: type: string enum: - function_call description: The type of the function tool call. Always function_call. id: type: string description: The unique ID of the function tool call. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - arguments - call_id - name - type - type: object properties: id: type: string description: The unique identifier of the reasoning content. summary: type: array items: type: object properties: text: type: string description: A short summary of the reasoning used by the model when generating the response. type: type: string enum: - summary_text description: The type of the object. Always summary_text. required: - text - type description: Reasoning text contents. type: type: string enum: - reasoning description: The type of the object. Always reasoning. encrypted_content: type: - string - 'null' description: The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. status: type: string enum: - in_progress - completed - incomplete description: The status of the item. required: - id - summary - type - type: object properties: id: type: string result: type: - string - 'null' status: type: string enum: - in_progress - completed - failed - generating type: type: string enum: - image_generation_call required: - id - result - status - type - type: object properties: code: type: - string - 'null' description: The code to run, or null if not available. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: - array - 'null' items: oneOf: - type: object properties: logs: type: string description: The logs output from the code interpreter. type: type: string enum: - logs description: The type of the output. Always 'logs'. required: - logs - type - type: object properties: type: type: string enum: - image url: type: string required: - type - url description: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. status: type: string enum: - in_progress - completed - incomplete - interpreting - failed description: The status of the code interpreter tool call. type: type: string enum: - code_interpreter_call description: The type of the code interpreter tool call. Always code_interpreter_call. container_id: type: string description: The ID of the container used to run the code. required: - id - status - type - container_id - type: object properties: action: type: object properties: command: type: array items: type: string description: The command to run. env: type: object additionalProperties: type: string description: Environment variables to set for the command. type: type: string enum: - exec description: The type of the local shell action. Always exec. timeout_ms: type: - integer - 'null' description: Optional timeout in milliseconds for the command. user: type: - string - 'null' description: Optional user to run the command as. working_directory: type: - string - 'null' description: Optional working directory to run the command in. required: - command - env - type description: Execute a shell command on the server. call_id: type: string description: The unique ID of the local shell tool call generated by the model. id: type: string description: The unique ID of the local shell call. status: type: string enum: - in_progress - completed - incomplete description: The status of the local shell call. type: type: string enum: - local_shell_call description: The type of the local shell call. Always local_shell_call. required: - action - call_id - id - status - type - type: object properties: id: type: string description: The unique ID of the list. server_label: type: string description: The label of the MCP server. tools: type: array items: type: object properties: input_schema: {} name: type: string description: The name of the tool. annotations: {} description: type: - string - 'null' description: The description of the tool. required: - name type: type: string enum: - mcp_list_tools description: The type of the item. Always mcp_list_tools. error: type: - string - 'null' description: Error message if the server could not list tools. required: - id - server_label - tools - type - type: object properties: arguments: type: string description: A JSON string of arguments for the tool. id: type: string description: The unique ID of the approval request. name: type: string server_label: type: string description: The name of the tool to run. type: type: string enum: - mcp_approval_request description: The type of the item. Always mcp_approval_request. required: - arguments - id - name - server_label - type - type: object properties: arguments: type: string description: A JSON string of the arguments passed to the tool. id: type: string description: The unique ID of the tool call. name: type: string description: The name of the tool that was run. server_label: type: string description: The label of the MCP server running the tool. type: type: string enum: - mcp_call description: The type of the item. Always mcp_call. error: type: - string - 'null' description: The error from the tool call, if any. output: type: - string - 'null' description: The output from the tool call. required: - arguments - id - name - server_label - type - type: object properties: type: type: string enum: - x_search_call required: - type description: 'An array of content items generated by the model. - The length and order of items in the output array is dependent on the model''s response. - Rather than accessing the first item in the output array and assuming it''s an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. ' example: null output_text: type: - string - 'null' description: SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs. example: Hi! How’s your day going? parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. example: false previous_response_id: type: - string - 'null' description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. example: null prompt: type: - object - 'null' properties: id: type: string description: The unique identifier of the prompt template to use. variables: type: - object - 'null' additionalProperties: {} description: Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. version: type: - string - 'null' description: Optional version of the prompt template. required: - id description: Reference to a prompt template and its variables. example: null reasoning: type: - object - 'null' properties: effort: type: - string - 'null' enum: - none - low - medium - high description: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. summary: type: - string - 'null' enum: - auto - concise - detailed description: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. description: Configuration options for reasoning models. example: null service_tier: type: - string - 'null' description: Specifies the processing type used for serving the request. example: null status: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete description: The status of the response generation. example: completed temperature: type: - number - 'null' minimum: 0 maximum: 2 description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. example: null text: type: - object - 'null' properties: format: oneOf: - type: object properties: type: type: string enum: - text description: The type of response format being defined. Always text. required: - type additionalProperties: false description: Default response format. Used to generate text responses. - type: object properties: type: type: string enum: - json_object description: The type of response format being defined. Always json_object. required: - type additionalProperties: false description: 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: object properties: name: type: string description: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: type: object additionalProperties: {} description: The schema for the response format, described as a JSON Schema object. type: type: string enum: - json_schema strict: type: - boolean - 'null' description: Whether to enable strict schema adherence when generating the output. If set to True, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is True. description: type: string description: A description of what the response format is for, used by the model to determine how to respond in the format. required: - name - schema - type description: JSON Schema response format. Used to generate structured JSON responses. description: An object specifying the format that the model must output. description: Configuration options for a text response from the model. Can be plain text or structured JSON data. tool_choice: anyOf: - type: string enum: - none - auto - required description: 'Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.' - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 - computer_use_preview - code_interpreter - mcp - file_search - image_generation required: - type description: Indicates that the model should use a built-in tool to generate a response. - type: object properties: name: type: string description: The name of the function to call. type: type: string enum: - function description: For function calling, the type is always function. required: - name - type description: Use this option to force the model to call a specific function. - {} description: How the model should select which tool (or tools) to use when generating a response. example: null tools: type: - array - 'null' items: oneOf: - type: object properties: type: type: string enum: - web_search_preview - web_search_preview_2025_03_11 description: The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. search_context_size: type: string enum: - low - medium - high description: High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. user_location: type: - object - 'null' properties: type: type: string enum: - approximate description: The type of location approximation. Always approximate. city: type: - string - 'null' description: Free text input for the city of the user, e.g. San Francisco. country: type: - string - 'null' description: The two-letter ISO country code of the user, e.g. US. region: type: - string - 'null' description: Free text input for the region of the user, e.g. California. timezone: type: - string - 'null' description: The IANA timezone of the user, e.g. America/Los_Angeles. required: - type description: The user's location required: - type description: This tool searches the web for relevant results to use in a response. - type: object properties: display_height: type: integer description: The height of the computer display. display_width: type: integer description: The width of the computer display. environment: type: string enum: - windows - mac - linux - ubuntu - browser description: The type of computer environment to control. type: type: string enum: - computer_use_preview description: The type of the computer use tool. Always computer_use_preview. required: - display_height - display_width - environment - type description: A tool that controls a virtual computer. - type: object properties: server_label: type: string description: A label for this MCP server, used to identify it in tool calls. server_url: type: string description: The URL for the MCP server. type: type: string enum: - mcp description: The type of the MCP tool. Always mcp. allowed_tools: anyOf: - type: array items: type: string description: A string array of allowed tool names. - type: object properties: tool_names: type: array items: type: string description: List of allowed tool names. description: A filter object to specify which tools are allowed. - {} description: List of allowed tool names or a filter object. headers: type: - object - 'null' additionalProperties: type: string description: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. require_approval: anyOf: - type: string enum: - always - never - type: object properties: always: type: object properties: tool_names: type: array items: type: string description: List of tools that require approval. description: A list of tools that always require approval. never: type: object properties: tool_names: type: array items: type: string description: List of tools that do not require approval. description: A list of tools that never require approval. - {} description: Specify which of the MCP server's tools require approval. required: - server_label - server_url - type description: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - type: object properties: type: type: string enum: - code_interpreter description: The type of the code interpreter tool. Always code_interpreter. container: anyOf: - type: string - type: object properties: type: type: string enum: - auto required: - type description: The container ID. required: - type - container description: A tool that runs Python code to help generate a response to a prompt. - type: object properties: type: type: string enum: - local_shell description: The type of the local shell tool. Always local_shell. required: - type description: A tool that allows the model to execute shell commands in a local environment. - type: object properties: name: type: string description: The name of the function to call. parameters: type: - object - 'null' additionalProperties: {} description: A JSON schema object describing the parameters of the function. strict: type: - boolean - 'null' description: Whether to enforce strict parameter validation. type: type: string enum: - function description: The type of the function tool. Always function. description: type: - string - 'null' description: A description of the function. Used by the model to determine whether or not to call the function. required: - name - type - type: object properties: type: type: string enum: - image_generation background: type: string enum: - transparent - opaque - auto input_image_mask: type: object properties: file_id: type: string image_url: type: string model: type: string enum: - gpt-image-1 moderation: type: string enum: - auto - low output_compression: type: number output_format: type: string enum: - png - webp - jpeg partial_images: type: integer minimum: 0 maximum: 3 quality: type: string enum: - low - medium - high - auto size: type: string enum: - 1024x1024 - 1024x1536 - 1536x1024 - auto required: - type description: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. example: null top_p: type: - number - 'null' description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.' example: null truncation: type: - string - 'null' enum: - auto - disabled description: 'The truncation strategy to use for the model response. - auto: If the context of this response and previous ones exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. ' example: null usage: type: object properties: input_tokens: type: integer description: The number of input tokens. example: 137 input_tokens_details: type: - object - 'null' properties: cached_tokens: type: integer description: The number of tokens that were retrieved from the cache. required: - cached_tokens description: A detailed breakdown of the input tokens. example: null output_tokens: type: integer description: The number of output tokens. example: 914 output_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: integer description: The number of reasoning tokens. required: - reasoning_tokens description: A detailed breakdown of the output tokens. example: null total_tokens: type: integer description: The total number of tokens used. example: 1051 required: - input_tokens - output_tokens - total_tokens description: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. citations: type: array items: type: string format: uri server_side_tool_usage: type: object additionalProperties: type: integer minimum: 0 meta: type: - object - 'null' properties: usage: type: - object - 'null' properties: credits_used: type: number description: The number of tokens consumed during generation. example: 120000 usd_spent: type: number description: The total amount of money spent by the user in USD. example: 0.06 required: - credits_used - usd_spent description: Additional details about the generation. required: - created_at - id - model - object - parallel_tool_calls tags: - Responses summary: V1 responses :response id x-summary-source: derived