--- title: "POST /v1/responses" method: POST path: "/v1/responses" --- # POST /v1/responses `POST /v1/responses` ## Request body - object - `model` 'openai/gpt-5-4', required - `input` union, required — Text, image, or file inputs to the model, used to generate a response. - string — A text input to the model, equivalent to a text input with the user role. - union[] - union - object — 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` 'message' — The type of the message input. Always message. - `role` 'user' | 'assistant' | 'system' | 'developer', required — The role of the message input. - `content` union, required — Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - string — A text input to the model. - union[] — A list of one or many input items to the model, containing different content types. - … - object — 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` 'message' — The type of the message input. Always message. - `role` 'user' | 'system' | 'developer', required — The role of the message input. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of item. - `content` union[], required — A list of one or many input items to the model, containing different content types. - union - … - object — An output message from the model. - `id` string, required — The unique ID of the output message. - `role` 'assistant', required — The role of the output message. Always assistant. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the message input. - `type` 'message', required — The type of the output message. Always message. - `content` union[], required - union — The content of the output message. - … - object — The results of a web search tool call. - `id` string, required — The unique ID of the web search tool call. - `status` 'in_progress' | 'completed' | 'searching' | 'failed', required — The status of the web search tool call. - `type` 'web_search_call', required — The type of the web search tool call. Always web_search_call. - object — A tool call to run a function. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `name` string, required — The name of the function to run. - `type` 'function_call', required — The type of the function tool call. Always function_call. - `id` string — The unique ID of the function tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - object — The output of a function tool call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `output` string, required — A JSON string of the output of the function tool call. - `type` 'function_call_output', required — The type of the function tool call output. Always function_call_output. - `id` string, nullable — The unique ID of the function tool call output. Populated when this item is returned via API. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the item. - object — A description of the chain of thought used by a reasoning model while generating a response. - `id` string, required — The unique identifier of the reasoning content. - `summary` object[], required — Reasoning text contents. - `text` string, required — A short summary of the reasoning used by the model when generating the response. - `type` 'summary_text', required — The type of the object. Always summary_text. - `type` 'reasoning', required — The type of the object. Always reasoning. - `encrypted_content` string, nullable — The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - object — A tool call to run code. - `code` string, required — The code to run, or null if not available. - `id` string, required — The unique ID of the code interpreter tool call. - `outputs` union[], nullable, required — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - union - … - `status` 'in_progress' | 'completed' | 'interpreting', required — The status of the code interpreter tool call. - `type` 'code_interpreter_call', required — The type of the code interpreter tool call. Always code_interpreter_call. - `container_id` string, required — The ID of the container used to run the code. - object — A list of tools available on an MCP server. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` object[], required — The tools available on the server. - `input_schema` object, required — The JSON schema describing the tool's input. - `name` string, required — The name of the tool. - `annotations` object, nullable — Additional annotations about the tool. - `description` string, nullable — The description of the tool. - `type` 'mcp_list_tools', required — The type of the item. Always mcp_list_tools. - `error` string, nullable — Error message if the server could not list tools. - object — A request for human approval of a tool invocation. - `arguments` string, required — A JSON string of arguments for the tool. - `id` string, required — The unique ID of the approval request. - `name` string, required - `server_label` string, required — The name of the tool to run. - `type` 'mcp_approval_request', required — The type of the item. Always mcp_approval_request. - object — A response to an MCP approval request. - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `type` 'mcp_approval_response', required — The type of the item. Always mcp_approval_response. - `id` string, nullable — The unique ID of the approval response. - `reason` string, nullable — Optional reason for the decision. - object — An invocation of a tool on an MCP server. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `id` string, required — The unique ID of the tool call. - `name` string, required — The name of the tool that was run. - `server_label` string, required — The label of the MCP server running the tool. - `type` 'mcp_call', required — The type of the item. Always mcp_call. - `error` string, nullable — The error from the tool call, if any. - `output` string, nullable — The output from the tool call. - object — An internal identifier for an item to reference. - `id` string, required — The ID of the item to reference. - `type` 'item_reference', nullable — The type of item to reference. Always item_reference. - `background` boolean — Whether to run the model response in the background. - `instructions` string, nullable — 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` string[], nullable — 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` integer — 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` string, nullable — The unique ID of the previous response to the model. Use this to create multi-turn conversations. - `prompt` object, nullable — Reference to a prompt template and its variables. - `id` string, required — The unique identifier of the prompt template to use. - `variables` object, nullable — 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` string, nullable — Optional version of the prompt template. - `store` boolean, nullable — Whether to store the generated model response for later retrieval via API. - `stream` boolean, nullable — If set to true, the model response data will be streamed to the client as it is generated using server-sent events. - `text` object — Configuration options for a text response from the model. Can be plain text or structured JSON data. - `format` union, required — An object specifying the format that the model must output. - object — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always text. - object — An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always json_object. - object — JSON Schema response format. Used to generate structured JSON responses. - `name` string, required — 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` object, required — The schema for the response format, described as a JSON Schema object. - `type` 'json_schema', required - `strict` boolean, nullable — 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` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `truncation` 'auto' | 'disabled' — 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` union[] — 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. - union - object — Defines a function in your own code the model can choose to call. - `name` string, required — The name of the function to call. - `parameters` object, required — A JSON schema object describing the parameters of the function. - `strict` boolean, required — Whether to enforce strict parameter validation. - `type` 'function', required — The type of the function tool. Always function. - `description` string — A description of the function. Used by the model to determine whether or not to call the function. - object — This tool searches the web for relevant results to use in a response. - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required — The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. - `search_context_size` 'low' | 'medium' | 'high' — High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. - `user_location` object, nullable — The user's location - `type` 'approximate', required — The type of location approximation. Always approximate. - `city` string, nullable — Free text input for the city of the user, e.g. San Francisco. - `country` string, nullable — The two-letter ISO country code of the user, e.g. US. - `region` string, nullable — Free text input for the region of the user, e.g. California. - `timezone` string, nullable — The IANA timezone of the user, e.g. America/Los_Angeles. - object — Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - `server_label` string, required — A label for this MCP server, used to identify it in tool calls. - `server_url` string, required — The URL for the MCP server. - `type` 'mcp', required — The type of the MCP tool. Always mcp. - `allowed_tools` union — List of allowed tool names or a filter object. - string[] — A string array of allowed tool names. - object — A filter object to specify which tools are allowed. - `tool_names` string[] — List of allowed tool names. - unknown - `headers` object, nullable — Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `require_approval` union — Specify which of the MCP server's tools require approval. - 'always' | 'never' - object - `always` object — A list of tools that always require approval. - … - `never` object — A list of tools that never require approval. - … - unknown - object — A tool that runs Python code to help generate a response to a prompt. - `type` 'code_interpreter', required — The type of the code interpreter tool. Always code_interpreter. - `container` union, required — The container ID. - string - object - `type` 'auto', required - `tool_choice` union — How the model should select which tool (or tools) to use when generating a response. - 'none' | 'auto' | 'required' — 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. - object — Indicates that the model should use a built-in tool to generate a response. - `type` 'web_search_preview' | 'web_search_preview_2025_03_11' | 'computer_use_preview' | 'code_interpreter' | 'mcp', required - object - `name` string, required — The name of the function to call. - `type` 'function', required — For function calling, the type is always function. - `parallel_tool_calls` boolean, nullable — Whether to allow the model to run tool calls in parallel. - `reasoning` object, nullable — o-series models only Configuration options for reasoning models. - `effort` 'low' | 'medium' | 'high', nullable — 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` 'auto' | 'concise' | 'detailed', nullable — A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. - `temperature` number, nullable — 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` number — 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. ## Response `200` - object - `background` boolean, nullable — Whether to run the model response in the background. - `created_at` number, required — Unix timestamp (in seconds) of when this Response was created. - `error` object, nullable — An error object returned when the model fails to generate a Response. - `code` string, required — The error code for the response. - `message` string, required — A human-readable description of the error. - `id` string, required — Unique identifier for this Response. - `incomplete_details` object, nullable — Details about why the response is incomplete. - `reason` string — The reason why the response is incomplete. - `instructions` union — A system (or developer) message inserted into the model's context. - string — A text input to the model, equivalent to a text input with the developer role. - union[] — A list of one or many input items to the model, containing different content types. - union - object — 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` 'message' — The type of the message input. Always message. - `role` 'user' | 'assistant' | 'system' | 'developer', required — The role of the message input. - `content` union, required — Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - string — A text input to the model. - union[] — A list of one or many input items to the model, containing different content types. - … - object - `type` 'message' — The type of the message input. Always message. - `role` 'user' | 'system' | 'developer', required — The role of the message input. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of item. - `content` union[], required — A list of one or many input items to the model, containing different content types. - union - … - object - `id` string, required — The unique ID of the output message. - `role` 'assistant', required — The role of the output message. Always assistant. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the message input. - `type` 'message', required — The type of the output message. Always message. - `content` union[], required - union — The content of the output message. - … - object - `id` string, required - `queries` string[], required - `status` 'in_progress' | 'searching' | 'incomplete' | 'failed' | 'completed', required - `type` 'file_search_call', required - `results` object[], nullable - `attributes` object, nullable - `file_id` string - `filename` string - `score` number - `text` string - object - `action` union, required - object — A click action. - … - object — A double click action. - … - object — A drag action. - … - object — A collection of keypresses the model would like to perform. - … - object — A mouse move action. - … - object — A screenshot action. - … - object — A scroll action. - … - object — An action to type in text. - … - object — A wait action. - … - `call_id` string, required — An identifier used when responding to the tool call with output. - `id` string, required — The unique ID of the computer call. - `pending_safety_checks` object[], required — The pending safety checks for the computer call. - `code` string, required — The type of the pending safety check. - `id` string, required — The ID of the pending safety check. - `message` string, required — Details about the pending safety check. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the item. - `type` 'computer_call', required — The type of the computer call. Always computer_call. - object - `call_id` string, required — The ID of the computer tool call that produced the output. - `output` object, required — A computer screenshot image used with the computer use tool. - `type` 'computer_screenshot', required — Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. - `image_url` string, uri — The URL of the screenshot image. - `type` 'computer_call_output', required — The type of the computer tool call output. Always computer_call_output. - `acknowledged_safety_checks` object[], nullable — The safety checks reported by the API that have been acknowledged by the developer. - `id` string, required — The ID of the pending safety check. - `code` string, nullable — The type of the pending safety check. - `message` string, nullable — Details about the pending safety check. - `id` string, nullable — The ID of the computer tool call output. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the message input. - object - `id` string, required — The unique ID of the web search tool call. - `status` 'in_progress' | 'completed' | 'searching' | 'failed', required — The status of the web search tool call. - `type` 'web_search_call', required — The type of the web search tool call. Always web_search_call. - object - `arguments` string, required — A JSON string of the arguments to pass to the function. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `name` string, required — The name of the function to run. - `type` 'function_call', required — The type of the function tool call. Always function_call. - `id` string — The unique ID of the function tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - object - `call_id` string, required — The unique ID of the function tool call generated by the model. - `output` string, required — A JSON string of the output of the function tool call. - `type` 'function_call_output', required — The type of the function tool call output. Always function_call_output. - `id` string, nullable — The unique ID of the function tool call output. Populated when this item is returned via API. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the item. - object - `id` string, required — The unique identifier of the reasoning content. - `summary` object[], required — Reasoning text contents. - `text` string, required — A short summary of the reasoning used by the model when generating the response. - `type` 'summary_text', required — The type of the object. Always summary_text. - `type` 'reasoning', required — The type of the object. Always reasoning. - `encrypted_content` string, nullable — The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - object - `id` string, required - `result` string, nullable, required - `status` 'in_progress' | 'completed' | 'failed' | 'generating', required - `type` 'image_generation_call', required - object - `code` string, nullable — The code to run, or null if not available. - `id` string, required — The unique ID of the code interpreter tool call. - `outputs` union[], nullable — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - union - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required — The status of the code interpreter tool call. - `type` 'code_interpreter_call', required — The type of the code interpreter tool call. Always code_interpreter_call. - `container_id` string, required — The ID of the container used to run the code. - object - `action` object, required — Execute a shell command on the server. - `command` string[], required — The command to run. - `env` object, required — Environment variables to set for the command. - `type` 'exec', required — The type of the local shell action. Always exec. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the command. - `user` string, nullable — Optional user to run the command as. - `working_directory` string, nullable — Optional working directory to run the command in. - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `id` string, required — The unique ID of the local shell call. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the local shell call. - `type` 'local_shell_call', required — The type of the local shell call. Always local_shell_call. - object - `id` string, required — The unique ID of the local shell tool call generated by the model. - `output` string, required — A JSON string of the output of the local shell tool call. - `type` 'local_shell_call_output', required — The type of the local shell tool call output. Always local_shell_call_output. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the item. - object - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` object[], required - `input_schema` unknown - `name` string, required — The name of the tool. - `annotations` unknown - `description` string, nullable — The description of the tool. - `type` 'mcp_list_tools', required — The type of the item. Always mcp_list_tools. - `error` string, nullable — Error message if the server could not list tools. - object - `arguments` string, required — A JSON string of arguments for the tool. - `id` string, required — The unique ID of the approval request. - `name` string, required - `server_label` string, required — The name of the tool to run. - `type` 'mcp_approval_request', required — The type of the item. Always mcp_approval_request. - object - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `type` 'mcp_approval_response', required — The type of the item. Always mcp_approval_response. - `id` string, nullable — The unique ID of the approval response. - `reason` string, nullable — Optional reason for the decision. - object - `arguments` string, required — A JSON string of the arguments passed to the tool. - `id` string, required — The unique ID of the tool call. - `name` string, required — The name of the tool that was run. - `server_label` string, required — The label of the MCP server running the tool. - `type` 'mcp_call', required — The type of the item. Always mcp_call. - `error` string, nullable — The error from the tool call, if any. - `output` string, nullable — The output from the tool call. - object — An internal identifier for an item to reference. - `id` string, required — The ID of the item to reference. - `type` 'item_reference', nullable — The type of item to reference. Always item_reference. - unknown - `max_output_tokens` integer, nullable — An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. - `metadata` object, nullable — 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. - `model` string, required — Model ID used to generate the response. - `object` 'response', required — The object type of this resource - always set to response. - `output` union[], nullable — 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. - union - object - `role` 'assistant', required — The role of the output message. Always assistant. - `type` 'message', required — The type of the output message. Always message. - `content` union[], required - union — The content of the output message. - object - … - object - … - object - `id` string, required - `queries` string[], required - `status` 'in_progress' | 'searching' | 'incomplete' | 'failed' | 'completed', required - `type` 'file_search_call', required - `results` object[], nullable - `attributes` object, nullable - `file_id` string - `filename` string - `score` number - `text` string - object - `action` union, required - object — A click action. - `button` 'left' | 'right' | 'wheel' | 'back' | 'forward', required — Indicates which mouse button was pressed during the click. - `type` 'click', required — Specifies the event type. For a click action, this property is always set to click. - `x` integer, required — The x-coordinate where the click occurred. - `y` integer, required — The y-coordinate where the click occurred. - object — A double click action. - `type` 'double_click', required — Specifies the event type. For a double click action, this property is always set to double_click. - `x` integer, required — The x-coordinate where the double click occurred. - `y` integer, required — The y-coordinate where the double click occurred. - object — A drag action. - `path` object[], required — An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - … - `type` 'drag', required — Specifies the event type. For a drag action, this property is always set to drag. - object — A collection of keypresses the model would like to perform. - `keys` string[], required — The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `type` 'keypress', required — Specifies the event type. For a keypress action, this property is always set to keypress. - object — A mouse move action. - `type` 'move', required — Specifies the event type. For a move action, this property is always set to move. - `x` integer, required — The x-coordinate to move to. - `y` integer, required — The y-coordinate to move to. - object — A screenshot action. - `type` 'screenshot', required — Specifies the event type. For a screenshot action, this property is always set to screenshot. - object — A scroll action. - `type` 'scroll', required — Specifies the event type. For a scroll action, this property is always set to scroll. - `scroll_x` integer, required — The horizontal scroll distance. - `scroll_y` integer, required — The vertical scroll distance. - `x` integer, required — The x-coordinate where the scroll occurred. - `y` integer, required — The y-coordinate where the scroll occurred. - object — An action to type in text. - `type` 'type', required — Specifies the event type. For a type action, this property is always set to type. - `text` string, required — The text to type. - object — A wait action. - `type` 'wait', required — Specifies the event type. For a wait action, this property is always set to wait. - `call_id` string, required — An identifier used when responding to the tool call with output. - `id` string, required — The unique ID of the computer call. - `pending_safety_checks` object[], required — The pending safety checks for the computer call. - `code` string, required — The type of the pending safety check. - `id` string, required — The ID of the pending safety check. - `message` string, required — Details about the pending safety check. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the item. - `type` 'computer_call', required — The type of the computer call. Always computer_call. - object - `call_id` string, required — The ID of the computer tool call that produced the output. - `output` object, required — A computer screenshot image used with the computer use tool. - `type` 'computer_screenshot', required — Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. - `image_url` string, uri — The URL of the screenshot image. - `type` 'computer_call_output', required — The type of the computer tool call output. Always computer_call_output. - `acknowledged_safety_checks` object[], nullable — The safety checks reported by the API that have been acknowledged by the developer. - `id` string, required — The ID of the pending safety check. - `code` string, nullable — The type of the pending safety check. - `message` string, nullable — Details about the pending safety check. - `id` string, nullable — The ID of the computer tool call output. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the message input. - object - `id` string, required — The unique ID of the web search tool call. - `status` 'in_progress' | 'completed' | 'searching' | 'failed', required — The status of the web search tool call. - `type` 'web_search_call', required — The type of the web search tool call. Always web_search_call. - object - `arguments` string, required — A JSON string of the arguments to pass to the function. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `name` string, required — The name of the function to run. - `type` 'function_call', required — The type of the function tool call. Always function_call. - `id` string — The unique ID of the function tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - object - `id` string, required — The unique identifier of the reasoning content. - `summary` object[], required — Reasoning text contents. - `text` string, required — A short summary of the reasoning used by the model when generating the response. - `type` 'summary_text', required — The type of the object. Always summary_text. - `type` 'reasoning', required — The type of the object. Always reasoning. - `encrypted_content` string, nullable — The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. - object - `id` string, required - `result` string, nullable, required - `status` 'in_progress' | 'completed' | 'failed' | 'generating', required - `type` 'image_generation_call', required - object - `code` string, nullable — The code to run, or null if not available. - `id` string, required — The unique ID of the code interpreter tool call. - `outputs` union[], nullable — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - union - object - … - object - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required — The status of the code interpreter tool call. - `type` 'code_interpreter_call', required — The type of the code interpreter tool call. Always code_interpreter_call. - `container_id` string, required — The ID of the container used to run the code. - object - `action` object, required — Execute a shell command on the server. - `command` string[], required — The command to run. - `env` object, required — Environment variables to set for the command. - `type` 'exec', required — The type of the local shell action. Always exec. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the command. - `user` string, nullable — Optional user to run the command as. - `working_directory` string, nullable — Optional working directory to run the command in. - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `id` string, required — The unique ID of the local shell call. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the local shell call. - `type` 'local_shell_call', required — The type of the local shell call. Always local_shell_call. - object - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` object[], required - `input_schema` unknown - `name` string, required — The name of the tool. - `annotations` unknown - `description` string, nullable — The description of the tool. - `type` 'mcp_list_tools', required — The type of the item. Always mcp_list_tools. - `error` string, nullable — Error message if the server could not list tools. - object - `arguments` string, required — A JSON string of arguments for the tool. - `id` string, required — The unique ID of the approval request. - `name` string, required - `server_label` string, required — The name of the tool to run. - `type` 'mcp_approval_request', required — The type of the item. Always mcp_approval_request. - object - `arguments` string, required — A JSON string of the arguments passed to the tool. - `id` string, required — The unique ID of the tool call. - `name` string, required — The name of the tool that was run. - `server_label` string, required — The label of the MCP server running the tool. - `type` 'mcp_call', required — The type of the item. Always mcp_call. - `error` string, nullable — The error from the tool call, if any. - `output` string, nullable — The output from the tool call. - `output_text` string, nullable — 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. - `parallel_tool_calls` boolean, required — Whether to allow the model to run tool calls in parallel. - `previous_response_id` string, nullable — The unique ID of the previous response to the model. Use this to create multi-turn conversations. - `prompt` object, nullable — Reference to a prompt template and its variables. - `id` string, required — The unique identifier of the prompt template to use. - `variables` object, nullable — 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` string, nullable — Optional version of the prompt template. - `reasoning` object, nullable — Configuration options for reasoning models. - `effort` 'low' | 'medium' | 'high', nullable — 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` 'auto' | 'concise' | 'detailed', nullable — A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. - `service_tier` string, nullable — Specifies the processing type used for serving the request. - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete' — The status of the response generation. - `temperature` number, nullable — 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. - `text` object, nullable — Configuration options for a text response from the model. Can be plain text or structured JSON data. - `format` union — An object specifying the format that the model must output. - object — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always text. - object — An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always json_object. - object — JSON Schema response format. Used to generate structured JSON responses. - `name` string, required — 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` object, required — The schema for the response format, described as a JSON Schema object. - `type` 'json_schema', required - `strict` boolean, nullable — 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` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `tool_choice` union — How the model should select which tool (or tools) to use when generating a response. - 'none' | 'auto' | 'required' — 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. - object — Indicates that the model should use a built-in tool to generate a response. - `type` 'web_search_preview' | 'web_search_preview_2025_03_11' | 'computer_use_preview' | 'code_interpreter' | 'mcp' | 'file_search' | 'image_generation', required - object — Use this option to force the model to call a specific function. - `name` string, required — The name of the function to call. - `type` 'function', required — For function calling, the type is always function. - unknown - `tools` union[], nullable — 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. - union - object — This tool searches the web for relevant results to use in a response. - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required — The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11. - `search_context_size` 'low' | 'medium' | 'high' — High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. - `user_location` object, nullable — The user's location - `type` 'approximate', required — The type of location approximation. Always approximate. - `city` string, nullable — Free text input for the city of the user, e.g. San Francisco. - `country` string, nullable — The two-letter ISO country code of the user, e.g. US. - `region` string, nullable — Free text input for the region of the user, e.g. California. - `timezone` string, nullable — The IANA timezone of the user, e.g. America/Los_Angeles. - object — A tool that controls a virtual computer. - `display_height` integer, required — The height of the computer display. - `display_width` integer, required — The width of the computer display. - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required — The type of computer environment to control. - `type` 'computer_use_preview', required — The type of the computer use tool. Always computer_use_preview. - object — Give the model access to additional tools via remote Model Context Protocol (MCP) servers. - `server_label` string, required — A label for this MCP server, used to identify it in tool calls. - `server_url` string, required — The URL for the MCP server. - `type` 'mcp', required — The type of the MCP tool. Always mcp. - `allowed_tools` union — List of allowed tool names or a filter object. - string[] — A string array of allowed tool names. - object — A filter object to specify which tools are allowed. - `tool_names` string[] — List of allowed tool names. - unknown - `headers` object, nullable — Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `require_approval` union — Specify which of the MCP server's tools require approval. - 'always' | 'never' - object - `always` object — A list of tools that always require approval. - … - `never` object — A list of tools that never require approval. - … - unknown - object — A tool that runs Python code to help generate a response to a prompt. - `type` 'code_interpreter', required — The type of the code interpreter tool. Always code_interpreter. - `container` union, required — The container ID. - string - object - `type` 'auto', required - object — A tool that allows the model to execute shell commands in a local environment. - `type` 'local_shell', required — The type of the local shell tool. Always local_shell. - object - `name` string, required — The name of the function to call. - `parameters` object, nullable — A JSON schema object describing the parameters of the function. - `strict` boolean, nullable — Whether to enforce strict parameter validation. - `type` 'function', required — The type of the function tool. Always function. - `description` string, nullable — A description of the function. Used by the model to determine whether or not to call the function. - object - `type` 'image_generation', required - `background` 'transparent' | 'opaque' | 'auto' - `input_image_mask` object - `file_id` string - `image_url` string - `model` 'gpt-image-1' - `moderation` 'auto' | 'low' - `output_compression` number - `output_format` 'png' | 'webp' | 'jpeg' - `partial_images` integer - `quality` 'low' | 'medium' | 'high' | 'auto' - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto' - `top_p` number, nullable — 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. - `truncation` 'auto' | 'disabled', nullable — 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. - `usage` object — Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. - `input_tokens` integer, required — The number of input tokens. - `input_tokens_details` object, nullable — A detailed breakdown of the input tokens. - `cached_tokens` integer, required — The number of tokens that were retrieved from the cache. - `output_tokens` integer, required — The number of output tokens. - `output_tokens_details` object, nullable — A detailed breakdown of the output tokens. - `reasoning_tokens` integer, required — The number of reasoning tokens. - `total_tokens` integer, required — The total number of tokens used. - `meta` object, nullable — Additional details about the generation. - `usage` object, nullable - `credits_used` number, required — The number of tokens consumed during generation. - `usd_spent` number, required — The total amount of money spent by the user in USD. --- [API](https://skmtc.dev/aimlapi/apis/aiml-api.md) · [All operations](https://skmtc.dev/aimlapi/apis/aiml-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aimlapi/aiml-api/revisions/6d578b39a9ec/schema)