--- title: "Get input token counts" method: POST path: "/responses/input_tokens" --- # Get input token counts `POST /responses/input_tokens` Returns input token counts of the request. Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. ## Request body - TokenCountsBody - `model` string, nullable — Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `input` union - string — A text input to the model, equivalent to a text input with the `user` role. - InputItem[] — A list of one or many input items to the model, containing different content types. - union - EasyInputMessage — 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. - `role` 'user' | 'assistant' | 'system' | 'developer', required — The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `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. - InputContent[] — A list of one or many input items to the model, containing different content types. - … - `phase` 'commentary' | 'final_answer' — Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `type` 'message' — The type of the message input. Always `message`. - union — Content item used to generate a response. - 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 set to `message`. - `role` 'user' | 'system' | 'developer', required — The role of the message input. One of `user`, `system`, or `developer`. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `content` InputContent[], required — A list of one or many input items to the model, containing different content types. - … - object — An output message from the model. - `id` string, required — The unique ID of the output message. - `type` 'message', required — The type of the output message. Always `message`. - `role` 'assistant', required — The role of the output message. Always `assistant`. - `content` OutputMessageContent[], required — The content of the output message. - … - `phase` 'commentary' | 'final_answer' — Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - object — The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id` string, required — The unique ID of the file search tool call. - `type` 'file_search_call', required — The type of the file search tool call. Always `file_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required — The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `queries` string[], required — The queries used to search for files. - `results` object[], nullable — The results of the file search tool call. - … - object — A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `type` 'computer_call', required — The type of the computer call. Always `computer_call`. - `id` string, required — The unique ID of the computer call. - `call_id` string, required — An identifier used when responding to the tool call with output. - `action` union - … - `actions` ComputerAction[] — Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - … - `pending_safety_checks` ComputerCallSafetyCheckParam[], required — The pending safety checks for the computer call. - … - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object — The output of a computer tool call. - `id` string, nullable — The ID of the computer tool call output. - `call_id` string, required — The ID of the computer tool call that produced the output. - `type` 'computer_call_output', required — The type of the computer tool call output. Always `computer_call_output`. - `output` ComputerScreenshotImage, required — A computer screenshot image used with the computer use tool. - … - `acknowledged_safety_checks` ComputerCallSafetyCheckParam[], nullable — The safety checks reported by the API that have been acknowledged by the developer. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object — The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id` string, required — The unique ID of the web search tool call. - `type` 'web_search_call', required — The type of the web search tool call. Always `web_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required — The status of the web search tool call. - `action` union, required — An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - … - object — A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `id` string — The unique ID of the function tool call. - `type` 'function_call', required — The type of the function tool call. Always `function_call`. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `namespace` string — The namespace of the function to run. - `name` string, required — The name of the function to run. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object — The output of a function tool call. - `id` string, nullable — The unique ID of the function tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `type` 'function_call_output', required — The type of the function tool call output. Always `function_call_output`. - `output` union, required — Text, image, or file output of the function tool call. - … - `caller` union — The execution context that produced this tool call. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable — The unique ID of this tool search call. - `call_id` string, nullable — The unique ID of the tool search call generated by the model. - `type` 'tool_search_call', required — The item type. Always `tool_search_call`. - `execution` 'server' | 'client' - `arguments` EmptyModelParam, required - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable — The unique ID of this tool search output. - `call_id` string, nullable — The unique ID of the tool search call generated by the model. - `type` 'tool_search_output', required — The item type. Always `tool_search_output`. - `execution` 'server' | 'client' - `tools` Tool[], required — The loaded tool definitions returned by the tool search output. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable — The unique ID of this additional tools item. - `type` 'additional_tools', required — The item type. Always `additional_tools`. - `role` 'developer', required — The role that provided the additional tools. Only `developer` is supported. - `tools` Tool[], required — A list of additional tools made available at this item. - … - object — A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - `type` 'reasoning', required — The type of the object. Always `reasoning`. - `id` string, required — The unique identifier of the reasoning content. - `encrypted_content` string, nullable — The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. - `summary` Summary[], required — Reasoning summary content. - … - `content` ReasoningTextContent[] — Reasoning text content. - … - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object — A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id` string, nullable — The ID of the compaction item. - `type` 'compaction', required — The type of the item. Always `compaction`. - `encrypted_content` string, required — The encrypted content of the compaction summary. - object — An image generation request made by the model. - `type` 'image_generation_call', required — The type of the image generation call. Always `image_generation_call`. - `id` string, required — The unique ID of the image generation call. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required — The status of the image generation call. - `result` string, nullable, required — The generated image encoded in base64. - object — A tool call to run code. - `type` 'code_interpreter_call', required — The type of the code interpreter tool call. Always `code_interpreter_call`. - `id` string, required — The unique ID of the code interpreter tool call. - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required — The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `container_id` string, required — The ID of the container used to run the code. - `code` string, nullable, required — The code to run, or null if not available. - `outputs` union[], nullable, required — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - … - object — A tool call to run a command on the local shell. - `type` 'local_shell_call', required — The type of the local shell call. Always `local_shell_call`. - `id` string, required — The unique ID of the local shell call. - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `action` LocalShellExecAction, required — Execute a shell command on the server. - … - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the local shell call. - object — The output of a local shell tool call. - `type` 'local_shell_call_output', required — The type of the local shell tool call output. Always `local_shell_call_output`. - `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. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the item. One of `in_progress`, `completed`, or `incomplete`. - object — A tool representing a request to execute one or more shell commands. - `id` string, nullable — The unique ID of the shell tool call. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `type` 'shell_call', required — The type of the item. Always `shell_call`. - `action` FunctionShellActionParam, required — Commands and limits describing how to run the shell tool call. - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status values reported for shell tool calls. - `environment` union - … - object — The streamed output items emitted by a shell tool call. - `id` string, nullable — The unique ID of the shell tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `type` 'shell_call_output', required — The type of the item. Always `shell_call_output`. - `output` FunctionShellCallOutputContentParam[], required — Captured chunks of stdout and stderr output, along with their associated outcomes. - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status values reported for shell tool calls. - `max_output_length` integer, nullable — The maximum number of UTF-8 characters captured for this shell call's combined output. - object — A tool call representing a request to create, delete, or update files using diff patches. - `type` 'apply_patch_call', required — The type of the item. Always `apply_patch_call`. - `id` string, nullable — The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `status` 'in_progress' | 'completed', required — Status values reported for apply_patch tool calls. - `operation` union, required — One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - … - object — The streamed output emitted by an apply patch tool call. - `type` 'apply_patch_call_output', required — The type of the item. Always `apply_patch_call_output`. - `id` string, nullable — The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `status` 'completed' | 'failed', required — Outcome values reported for apply_patch tool call outputs. - `output` string, nullable — Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - object — A list of tools available on an MCP server. - `type` 'mcp_list_tools', required — The type of the item. Always `mcp_list_tools`. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` MCPListToolsTool[], required — The tools available on the server. - … - `error` string, nullable — Error message if the server could not list tools. - object — A request for human approval of a tool invocation. - `type` 'mcp_approval_request', required — The type of the item. Always `mcp_approval_request`. - `id` string, required — The unique ID of the approval request. - `server_label` string, required — The label of the MCP server making the request. - `name` string, required — The name of the tool to run. - `arguments` string, required — A JSON string of arguments for the tool. - object — A response to an MCP approval request. - `type` 'mcp_approval_response', required — The type of the item. Always `mcp_approval_response`. - `id` string, nullable — The unique ID of the approval response - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `reason` string, nullable — Optional reason for the decision. - object — An invocation of a tool on an MCP server. - `type` 'mcp_call', required — The type of the item. Always `mcp_call`. - `id` string, required — The unique ID of the tool call. - `server_label` string, required — The label of the MCP server running the tool. - `name` string, required — The name of the tool that was run. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `output` string, nullable — The output from the tool call. - `error` string, nullable — The error from the tool call, if any. - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `approval_request_id` string, nullable — Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - object — The output of a custom tool call from your code, being sent back to the model. - `type` 'custom_tool_call_output', required — The type of the custom tool call output. Always `custom_tool_call_output`. - `id` string — The unique ID of the custom tool call output in the OpenAI platform. - `call_id` string, required — The call ID, used to map this custom tool call output to a custom tool call. - `caller` union — The execution context that produced this tool call. - … - `output` union, required — The output from the custom tool call generated by your code. Can be a string or an list of output content. - … - object — A call to a custom tool created by the model. - `type` 'custom_tool_call', required — The type of the custom tool call. Always `custom_tool_call`. - `id` string — The unique ID of the custom tool call in the OpenAI platform. - `call_id` string, required — An identifier used to map this custom tool call to a tool call output. - `caller` union — The execution context that produced this tool call. - … - `namespace` string — The namespace of the custom tool being called. - `name` string, required — The name of the custom tool being called. - `input` string, required — The input for the custom tool call generated by the model. - CompactionTriggerItemParam — Compacts the current context. Must be the final input item. - `type` 'compaction_trigger', required — The type of the item. Always `compaction_trigger`. - ItemReferenceParam — An internal identifier for an item to reference. - `type` 'item_reference', nullable — The type of item to reference. Always `item_reference`. - `id` string, required — The ID of the item to reference. - ProgramItemParam - `id` string, required — The unique ID of this program item. - `type` 'program', required — The item type. Always `program`. - `call_id` string, required — The stable call ID of the program item. - `code` string, required — The JavaScript source executed by programmatic tool calling. - `fingerprint` string, required — Opaque program replay fingerprint that must be round-tripped. - ProgramOutputItemParam - `id` string, required — The unique ID of this program output item. - `type` 'program_output', required — The item type. Always `program_output`. - `call_id` string, required — The call ID of the program item. - `result` string, required — The result produced by the program item. - `status` 'completed' | 'incomplete', required - `previous_response_id` string, nullable — The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `tools` Tool[], 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 — A tool that can be used to generate a response. - FunctionTool — Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `type` 'function', required — The type of the function tool. Always `function`. - `name` string, required — The name of the function to call. - `description` string, nullable — A description of the function. Used by the model to determine whether or not to call the function. - `parameters` object, nullable, required — A JSON schema object describing the parameters of the function. - `output_schema` object, nullable — A JSON schema object describing the JSON value encoded in string outputs for this function. - `strict` boolean, nullable, required — Whether strict parameter validation is enforced for this function tool. - `defer_loading` boolean — Whether this function is deferred and loaded via tool search. - `allowed_callers` CallableToolAllowedCaller[], nullable — The tool invocation context(s). - FileSearchTool — A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `type` 'file_search', required — The type of the file search tool. Always `file_search`. - `vector_store_ids` string[], required — The IDs of the vector stores to search. - `max_num_results` integer — The maximum number of results to return. This number should be between 1 and 50 inclusive. - `ranking_options` RankingOptions - `ranker` 'auto' | 'default-2024-11-15' - `score_threshold` number — The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - `hybrid_search` HybridSearchOptions - `embedding_weight` number, required — The weight of the embedding in the reciprocal ranking fusion. - `text_weight` number, required — The weight of the text in the reciprocal ranking fusion. - `filters` union - ComparisonFilter — A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin', required — Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in - `key` string, required — The key to compare against the value. - `value` union, required — The value to compare against the attribute key; supports string, number, or boolean types. - … - CompoundFilter — Combine multiple filters using `and` or `or`. - `type` 'and' | 'or', required — Type of operation: `and` or `or`. - `filters` union[], required — Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - … - ComputerTool — A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type` 'computer', required — The type of the computer tool. Always `computer`. - ComputerUsePreviewTool — A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type` 'computer_use_preview', required — The type of the computer use tool. Always `computer_use_preview`. - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required - `display_width` integer, required — The width of the computer display. - `display_height` integer, required — The height of the computer display. - WebSearchTool — Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type` 'web_search' | 'web_search_2025_08_26', required — The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - `filters` object, nullable — Filters for the search. - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `user_location` WebSearchApproximateLocation, nullable — The approximate location of the user. - `type` 'approximate' — The type of location approximation. Always `approximate`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `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. - MCPTool — Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `type` 'mcp', required — The type of the MCP tool. Always `mcp`. - `server_label` string, required — A label for this MCP server, used to identify it in tool calls. - `server_url` string, uri — The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint' — Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` - `tunnel_id` string — The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `authorization` string — An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. - `server_description` string — Optional description of the MCP server, used to provide more context. - `headers` object, nullable — Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `allowed_tools` union - string[] — A string array of allowed tool names - MCPToolFilter — A filter object to specify which tools are allowed. - `tool_names` string[] — List of allowed tool names. - `read_only` boolean — Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `allowed_callers` CallableToolAllowedCaller[], nullable — The tool invocation context(s). - `require_approval` union - object — Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval. - `always` MCPToolFilter — A filter object to specify which tools are allowed. - … - `never` MCPToolFilter — A filter object to specify which tools are allowed. - … - 'always' | 'never' — Specify a single approval policy for all tools. One of `always` or `never`. When set to `always`, all tools will require approval. When set to `never`, all tools will not require approval. - `defer_loading` boolean — Whether this MCP tool is deferred and discovered via tool search. - CodeInterpreterTool — 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 code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting. - string — The container ID. - CodeInterpreterContainerAuto — Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `type` 'auto', required — Always `auto`. - `file_ids` string[] — An optional list of uploaded files to make available to your code. - `memory_limit` '1g' | '4g' | '16g' | '64g' - `network_policy` union — Network access policy for the container. - … - `allowed_callers` CallableToolAllowedCaller[], nullable — The tool invocation context(s). - ProgrammaticToolCallingParam - `type` 'programmatic_tool_calling', required — The type of the tool. Always `programmatic_tool_calling`. - ImageGenTool — A tool that generates images using the GPT image models. - `type` 'image_generation', required — The type of the image generation tool. Always `image_generation`. - `model` union - string - 'gpt-image-1' | 'gpt-image-1-mini' | 'gpt-image-2' | 'gpt-image-2-2026-04-21' | 'gpt-image-1.5' | 'chatgpt-image-latest' — The image generation model to use. Default: `gpt-image-1`. - `quality` 'low' | 'medium' | 'high' | 'auto' — The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. - `size` union — The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - string - '1024x1024' | '1024x1536' | '1536x1024' | 'auto' - `output_format` 'png' | 'webp' | 'jpeg' — The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `output_compression` integer — Compression level for the output image. Default: 100. - `moderation` 'auto' | 'low' — Moderation level for the generated image. Default: `auto`. - `background` 'transparent' | 'opaque' | 'auto' — Allows to set transparency for the background of the generated image(s). This parameter is only supported for GPT image models that support transparent backgrounds. Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds. Requests with `background` set to `transparent` will return an error for these models; use `opaque` or `auto` instead. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`. - `input_fidelity` 'high' | 'low' — Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - `input_image_mask` object — Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `image_url` string — Base64-encoded mask image. - `file_id` string — File ID for the mask image. - `partial_images` integer — Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `action` 'generate' | 'edit' | 'auto' - LocalShellToolParam — 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`. - FunctionShellToolParam — A tool that allows the model to execute shell commands. - `type` 'shell', required — The type of the shell tool. Always `shell`. - `environment` union - ContainerAutoParam - `type` 'container_auto', required — Automatically creates a container for this request - `file_ids` string[] — An optional list of uploaded files to make available to your code. - `memory_limit` '1g' | '4g' | '16g' | '64g' - `network_policy` union — Network access policy for the container. - … - `skills` union[] — An optional list of skills referenced by id or inline data. - … - LocalEnvironmentParam - `type` 'local', required — Use a local computer environment. - `skills` LocalSkillParam[] — An optional list of skills. - … - ContainerReferenceParam - `type` 'container_reference', required — References a container created with the /v1/containers endpoint - `container_id` string, required — The ID of the referenced container. - `allowed_callers` CallableToolAllowedCaller[], nullable — The tool invocation context(s). - CustomToolParam — A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `type` 'custom', required — The type of the custom tool. Always `custom`. - `name` string, required — The name of the custom tool, used to identify it in tool calls. - `description` string — Optional description of the custom tool, used to provide more context. - `format` union — The input format for the custom tool. Default is unconstrained text. - CustomTextFormatParam — Unconstrained free-form text. - `type` 'text', required — Unconstrained text format. Always `text`. - CustomGrammarFormatParam — A grammar defined by the user. - `type` 'grammar', required — Grammar format. Always `grammar`. - `syntax` 'lark' | 'regex', required - `definition` string, required — The grammar definition. - `defer_loading` boolean — Whether this tool should be deferred and discovered via tool search. - `allowed_callers` CallableToolAllowedCaller[], nullable — The tool invocation context(s). - NamespaceToolParam — Groups function/custom tools under a shared namespace. - `type` 'namespace', required — The type of the tool. Always `namespace`. - `name` string, required — The namespace name used in tool calls (for example, `crm`). - `description` string, required — A description of the namespace shown to the model. - `tools` union[], required — The function/custom tools available inside this namespace. - union — A function or custom tool that belongs to a namespace. - FunctionToolParam - … - CustomToolParam — A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - … - ToolSearchToolParam — Hosted or BYOT tool search configuration for deferred tools. - `type` 'tool_search', required — The type of the tool. Always `tool_search`. - `execution` 'server' | 'client' - `description` string, nullable — Description shown to the model for a client-executed tool search tool. - `parameters` EmptyModelParam - WebSearchPreviewTool — This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `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`. - `user_location` ApproximateLocation - `type` 'approximate', required — The type of location approximation. Always `approximate`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `search_context_size` 'low' | 'medium' | 'high' - `search_content_types` SearchContentType[] - ApplyPatchToolParam — Allows the assistant to create, delete, or update files using unified diffs. - `type` 'apply_patch', required — The type of the tool. Always `apply_patch`. - `allowed_callers` CallableToolAllowedCaller[], nullable — The tool invocation context(s). - `text` ResponseTextParam — Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - `format` union — An object specifying the format that the model must output. Configuring `{ "type": "json_schema" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). The default format is `{ "type": "text" }` with no additional options. **Not recommended for gpt-4o and newer models:** Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. - ResponseFormatText — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always `text`. - TextResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`. - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, 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` ResponseFormatJsonSchemaSchema, required — The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). - `strict` boolean, 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`. To learn more, read the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always `json_object`. - `verbosity` 'low' | 'medium' | 'high', nullable — Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are `low`, `medium`, and `high`. The default is `medium`. - `reasoning` Reasoning — **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - `mode` union - string - 'standard' | 'pro' - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable — Constrains effort on reasoning for reasoning models. Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not all reasoning models support every value. See the [reasoning guide](https://platform.openai.com/docs/guides/reasoning) for model-specific support. - `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. One of `auto`, `concise`, or `detailed`. `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - `context` 'auto' | 'current_turn' | 'all_turns', nullable — Controls which reasoning items are rendered back to the model on later turns. If omitted or set to `auto`, the model determines the context mode. The `gpt-5.6` model family defaults to `all_turns`; earlier models default to `current_turn`. When returned on a response, this is the effective reasoning context mode used for the response. - `generate_summary` 'auto' | 'concise' | 'detailed', nullable — **Deprecated:** use `summary` instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`. - `truncation` 'auto' | 'disabled' - `instructions` string, nullable — A system (or developer) message inserted into the model's context. When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - `personality` union - string - 'friendly' | 'pragmatic' - `conversation` union — The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. Input items and output items from this response are automatically added to this conversation after this response completes. - string — The unique ID of the conversation. - ConversationParam2 — The conversation that this response belongs to. - `id` string, required — The unique ID of the conversation. - `tool_choice` union — How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools the model can call. - '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. - ToolChoiceAllowed — Constrains the tools available to the model to a pre-defined set. - `type` 'allowed_tools', required — Allowed tool configuration type. Always `allowed_tools`. - `mode` 'auto' | 'required', required — Constrains the tools available to the model to a pre-defined set. `auto` allows the model to pick from among the allowed tools and generate a message. `required` requires the model to call one or more of the allowed tools. - `tools` object[], required — A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: ```json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ] ``` - ToolChoiceTypes — Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - `type` 'file_search' | 'web_search_preview' | 'computer' | 'computer_use_preview' | 'computer_use' | 'web_search_preview_2025_03_11' | 'image_generation' | 'code_interpreter', required — The type of hosted tool the model should to use. Learn more about [built-in tools](https://platform.openai.com/docs/guides/tools). Allowed values are: - `file_search` - `web_search_preview` - `computer` - `computer_use_preview` - `computer_use` - `code_interpreter` - `image_generation` - ToolChoiceFunction — Use this option to force the model to call a specific function. - `type` 'function', required — For function calling, the type is always `function`. - `name` string, required — The name of the function to call. - ToolChoiceMCP — Use this option to force the model to call a specific tool on a remote MCP server. - `type` 'mcp', required — For MCP tools, the type is always `mcp`. - `server_label` string, required — The label of the MCP server to use. - `name` string, nullable — The name of the tool to call on the server. - ToolChoiceCustom — Use this option to force the model to call a specific custom tool. - `type` 'custom', required — For custom tool calling, the type is always `custom`. - `name` string, required — The name of the custom tool to call. - SpecificProgrammaticToolCallingParam - `type` 'programmatic_tool_calling', required — The tool to call. Always `programmatic_tool_calling`. - SpecificApplyPatchParam — Forces the model to call the apply_patch tool when executing a tool call. - `type` 'apply_patch', required — The tool to call. Always `apply_patch`. - SpecificFunctionShellParam — Forces the model to call the shell tool when a tool call is required. - `type` 'shell', required — The tool to call. Always `shell`. - `parallel_tool_calls` boolean, nullable — Whether to allow the model to run tool calls in parallel. ## Response `200` Success - TokenCountsResource - `object` 'response.input_tokens', required - `input_tokens` integer, required --- [API](https://skmtc.net/openai/apis/openai-api.md) · [All operations](https://skmtc.net/openai/apis/openai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openai/openai-api/versions/dcd35773a322/schema)