--- title: "创建响应接口" method: POST path: "/responses" tags: ["Response"] --- # 创建响应接口 `POST /responses` 用于创建响应的接口，目前仅 OpenAI 支持，可配置各种参数来控制响应的生成结果。 ## Request body - CreateResponse - `metadata` Metadata, nullable — 一对可以附加到对象的 16 个键值对。这对于以结构化格式存储有关对象的附加信息以及通过 API 或仪表板查询对象非常有用。 键是长度最多为 64 个字符的字符串。值是长度最多为 512 个字符的字符串。 - `temperature` number, nullable — 要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更随机，而较低的值（如 0.2）将使其更聚焦和确定。 我们通常建议修改此项或 `top_p`，但不要同时修改两者。 - `top_p` number, nullable — 采样温度的另一种方法，称为核采样，模型会考虑具有 top_p 概率质量的 token 的结果。因此，0.1 意味着只考虑包含前 10% 概率质量的 token。 我们通常建议修改此项或 `temperature`，但不要同时修改两者。 - `user` string — 最终用户的稳定标识符。 用于通过更好地对类似请求进行分桶来提高缓存命中率，并帮助 OpenAI 检测和防止滥用。[了解更多](/docs/guides/safety-best-practices#end-user-ids)。 - `service_tier` 'auto' | 'default' | 'flex' | 'scale', nullable — 指定用于处理请求的延迟等级。此参数适用于订阅了按量计费服务的客户： - 如果设置为“auto”，并且项目启用了按量计费服务，系统将使用按量计费积分直至用尽。 - 如果设置为“auto”，但项目未启用按量计费服务，则请求将使用默认服务等级进行处理，该等级的正常运行时间服务水平协议较低，且无延迟保证。 - 如果设置为“default”，请求将使用默认服务等级进行处理，该等级的正常运行时间服务水平协议较低，且无延迟保证。 - 如果设置为“flex”，请求将使用弹性处理服务等级进行处理。[了解更多](/docs/guides/flex-processing)。 - 如果未设置，则默认行为是“auto”。 设置此参数后，响应体将包含所使用的 `service_tier`。 - `previous_response_id` string, nullable — 模型上一个响应的唯一 ID。使用此 ID 来创建多轮对话。了解有关[对话状态](/docs/guides/conversation-state)的更多信息。 - `model` union - union - string - 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'o4-mini' | 'o4-mini-2025-04-16' | 'o3' | 'o3-2025-04-16' | 'o3-mini' | 'o3-mini-2025-01-31' | 'o1' | 'o1-2024-12-17' | 'o1-preview' | 'o1-preview-2024-09-12' | 'o1-mini' | 'o1-mini-2024-09-12' | 'gpt-4o' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4o-audio-preview' | 'gpt-4o-audio-preview-2024-10-01' | 'gpt-4o-audio-preview-2024-12-17' | 'gpt-4o-audio-preview-2025-06-03' | 'gpt-4o-mini-audio-preview' | 'gpt-4o-mini-audio-preview-2024-12-17' | 'gpt-4o-search-preview' | 'gpt-4o-mini-search-preview' | 'gpt-4o-search-preview-2025-03-11' | 'gpt-4o-mini-search-preview-2025-03-11' | 'chatgpt-4o-latest' | 'codex-mini-latest' | 'gpt-4o-mini' | 'gpt-4o-mini-2024-07-18' | 'gpt-4-turbo' | 'gpt-4-turbo-2024-04-09' | 'gpt-4-0125-preview' | 'gpt-4-turbo-preview' | 'gpt-4-1106-preview' | 'gpt-4-vision-preview' | 'gpt-4' | 'gpt-4-0314' | 'gpt-4-0613' | 'gpt-4-32k' | 'gpt-4-32k-0314' | 'gpt-4-32k-0613' | 'gpt-3.5-turbo' | 'gpt-3.5-turbo-16k' | 'gpt-3.5-turbo-0301' | 'gpt-3.5-turbo-0613' | 'gpt-3.5-turbo-1106' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-16k-0613' - 'o1-pro' | 'o1-pro-2025-03-19' | 'o3-pro' | 'o3-pro-2025-06-10' | 'computer-use-preview' | 'computer-use-preview-2025-03-11' - `reasoning` Reasoning — **仅限 o 系列模型** [推理模型](https://platform.openai.com/docs/guides/reasoning)的配置选项。 - `effort` 'low' | 'medium' | 'high', nullable — **仅限 o 系列模型** 对 [推理模型](https://platform.openai.com/docs/guides/reasoning) 的推理工作量进行限制。 当前支持的值有 `low`、`medium` 和 `high`。降低推理工作量可能会导致更快的响应和更少的令牌使用。 - `summary` 'auto' | 'concise' | 'detailed', nullable — 对模型执行的推理的总结。这对于调试和理解模型的推理过程非常有用。 可能的值有 `auto`、`concise` 或 `detailed`。 - `generate_summary` 'auto' | 'concise' | 'detailed', nullable — **Deprecated:** use `summary` instead. 对模型执行的推理的总结。这对于调试和理解模型的推理过程非常有用。 可能的值有 `auto`、`concise` 或 `detailed`。 - `background` boolean, nullable — 是否在后台运行模型响应。 [了解更多](/docs/guides/background). - `max_output_tokens` integer, nullable — 可以为响应生成的 token 的上限，包括可见的输出 token 和[推理 token](/docs/guides/reasoning)。 - `text` object — 模型文本响应的配置选项。可以是纯文本或结构化 JSON 数据。了解更多： - [文本输入和输出](/docs/guides/text) - [结构化输出](/docs/guides/structured-outputs) - `format` union — 一个指定模型必须输出格式的对象。 配置 `{ "type": "json_schema" }` 可启用结构化输出，确保模型符合您提供的 JSON 架构。在[结构化输出指南](/docs/guides/structured-outputs)中了解更多信息。 默认格式为 `{ "type": "text" }`，不带任何附加选项。 **不建议用于 gpt-4o 及更新模型：** 设置为 `{ "type": "json_object" }` 可启用较旧的 JSON 模式，该模式可确保模型生成的消息是有效的 JSON。对于支持它的模型，建议使用 `json_schema`。 - ResponseFormatText — 默认响应格式。用于生成文本响应。 - `type` 'text', required — 正在定义的响应格式的类型。始终为 `text`。 - TextResponseFormatJsonSchema — JSON Schema 响应格式。用于生成结构化 JSON 响应。 详细了解[结构化输出](/docs/guides/structured-outputs)。 - `type` 'json_schema', required — 响应格式的类型。始终为 `json_schema`。 - `description` string — 响应格式的描述。用于模型确定如何以该格式进行响应。 - `name` string, required — 响应格式的名称。必须是 a-z、A-Z、0-9，或包含下划线和短横线，且最大长度为 64。 - `schema` ResponseFormatJsonSchemaSchema, required — 响应格式的模式，描述为 JSON Schema 对象。 了解有关如何构建 JSON Schema 的更多信息 [here](https://json-schema.org/)。 - `strict` boolean, nullable — 是否在生成输出时启用严格的架构遵循。 如果设置为 true，模型将始终遵循 `schema` 字段中定义的确切架构。 当 `strict` 为 `true` 时，仅支持 JSON Schema 的子集。要了解更多信息，请阅读 [结构化输出指南](/docs/guides/structured-outputs)。 - ResponseFormatJsonObject — JSON 对象响应格式。生成 JSON 响应的旧方法。 建议对支持 `json_schema` 的模型使用它。请注意，模型不会在没有系统消息或用户消息指示的情况下生成 JSON。 - `type` 'json_object', required — 正在定义的响应格式的类型。始终为 `json_object`。 - `tools` Tool[] — 模型在生成响应时可以调用的工具数组。您可以通过设置 `tool_choice` 参数来指定要使用的工具。 您可以为模型提供的两类工具是： - **内置工具**：由 OpenAI 提供、扩展模型功能的工具，例如[网页搜索](/docs/guides/tools-web-search)或[文件搜索](/docs/guides/tools-file-search)。了解更多有关[内置工具](/docs/guides/tools)的信息。 - **函数调用（自定义工具）**：由您定义的函数，使模型能够调用您自己的代码。了解更多有关[函数调用](/docs/guides/function-calling)的信息。 - union — 可用于生成响应的工具。 - FunctionTool — 定义一个模型可以选择调用的函数。了解有关 [函数调用](https://platform.openai.com/docs/guides/function-calling) 的更多信息。 - `type` 'function', required — 函数工具的类型。始终为 `function`。 - `name` string, required — 要调用的函数的名称。 - `description` string, nullable — 函数的描述。用于模型确定是否调用该函数。 - `parameters` object, nullable, required — 描述函数参数的 JSON schema 对象。 - `strict` boolean, nullable, required — 是否强制执行严格的参数验证。默认值为 `true`。 - FileSearchTool — 一个搜索已上传文件中相关内容的工具。详细了解 [文件搜索工具](https://platform.openai.com/docs/guides/tools-file-search)。 - `type` 'file_search', required — 文件搜索工具的类型。始终为 `file_search`。 - `vector_store_ids` string[], required — 要搜索的向量存储的 ID。 - `max_num_results` integer — 要返回的最大结果数。此数字应介于 1 和 50 之间（包括 1 和 50）。 - `ranking_options` RankingOptions - `ranker` 'auto' | 'default-2024-11-15' — 用于文件搜索的排名器。 - `score_threshold` number — 文件搜索的分数阈值，介于 0 和 1 之间的数字。接近 1 的数字将尝试仅返回最相关的结果，但可能返回更少的结果。 - `filters` union - unknown - unknown - WebSearchPreviewTool — 该工具在网络上搜索相关结果以用于响应。详细了解 [Web 搜索工具](https://platform.openai.com/docs/guides/tools-web-search)。 - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required — Web 搜索工具的类型。可以是 `web_search_preview` 或 `web_search_preview_2025_03_11`。 - `user_location` ApproximateLocation - `type` 'approximate', required — 位置近似的类型。始终为 `approximate`。 - `country` string, nullable — 用户的两字母 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1)，例如 `US`。 - `region` string, nullable — 用户的自由文本输入的地区，例如 `California`。 - `city` string, nullable — 用户的自由文本输入的城市，例如 `San Francisco`。 - `timezone` string, nullable — 用户的 [IANA 时区](https://timeapi.io/documentation/iana-timezones)，例如 `America/Los_Angeles`。 - `search_context_size` 'low' | 'medium' | 'high' — 有关搜索使用的上下文窗口空间量的高级指导。可以是 `low`、`medium` 或 `high`。`medium` 是默认值。 - ComputerUsePreviewTool — 一个控制虚拟计算机的工具。详细了解 [计算机使用工具](https://platform.openai.com/docs/guides/tools-computer-use)。 - `type` 'computer_use_preview', required — 计算机使用工具的类型。始终为 `computer_use_preview`。 - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required — 要控制的计算机环境的类型。 - `display_width` integer, required — 计算机显示器的宽度。 - `display_height` integer, required — 计算机显示器的高度。 - MCPTool — 通过远程模型上下文协议 (MCP) 服务器为模型提供对其他工具的访问 - `type` 'mcp', required — 项目的类型。始终为 `mcp`。 - `server_label` string, required — 此 MCP 服务器的标签，用于在工具调用中标识它。 - `server_url` string, required — MCP 服务器的 URL。 - `headers` object, nullable — 可选的 HTTP 头部，用于发送到 MCP 服务器。可用于身份验证或其他目的。 - `allowed_tools` union — 允许的工具名称列表或过滤器对象。 - string[] — 允许的工具名称的字符串数组 - object — 用于指定允许哪些工具的过滤器对象。 - `tool_names` string[] — 允许的工具名称列表。 - `require_approval` union — 指定 MCP 服务器的哪些工具需要批准。 - object - `always` object — 始终需要批准的工具列表。 - … - `never` object — 从不需要批准的工具列表。 - … - 'always' | 'never' — 为所有工具指定单一的批准策略。可以是 `always` 或 `never`。设置为 `always` 时，所有工具都将需要批准。设置为 `never` 时，所有工具都将不需要批准。 - unknown - ImageGenTool — 一个使用类似 `gpt-image-1` 的模型生成图像的工具。 - `type` 'image_generation', required — 图像生成工具的类型。始终为 `image_generation`。 - `model` 'gpt-image-1' — 要使用的图像生成模型。默认值：`gpt-image-1`。 - `quality` 'low' | 'medium' | 'high' | 'auto' — 生成图像的质量。可以是 `low`、`medium`、`high` 或 `auto`。默认值：`auto`。 - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto' — 生成图像的大小。可以是 `1024x1024`、`1024x1536`、`1536x1024` 或 `auto`。默认值：`auto`。 - `output_format` 'png' | 'webp' | 'jpeg' — 生成图像的输出格式。可以是 `png`、`webp` 或 `jpeg`。默认值：`png`。 - `output_compression` integer — 输出图像的压缩级别。默认值：100。 - `moderation` 'auto' | 'low' — 生成图像的审核级别。默认值：`auto`。 - `background` 'transparent' | 'opaque' | 'auto' — 生成图像的背景类型。可以是 `transparent`、`opaque` 或 `auto`。默认值：`auto`。 - `input_image_mask` object — 可选的蒙版图像。包含 `image_url`（字符串，可选）和 `file_id`（字符串，可选）。 - `image_url` string — Base64 编码的蒙版图像 - `file_id` string — 蒙版图像的文件 ID - `partial_images` integer — 在流式模式下生成的部分图像数量，范围从 0（默认值）到 3。 - LocalShellTool — 允许模型在本地环境中执行 shell 命令的工具。 - `type` 'local_shell', required — 本地 shell 工具的类型。始终为 `local_shell`。 - `tool_choice` union — 模型在生成响应时应如何选择使用哪个工具（或多个工具）。请参阅 `tools` 参数以了解如何指定模型可以调用的工具。 - 'none' | 'auto' | 'required' — 控制模型调用哪个（如果有）工具。 `none` 表示模型将不调用任何工具，而是生成一条消息。 `auto` 表示模型可以选择生成消息或调用一个或多个工具。 `required` 表示模型必须调用一个或多个工具。 - ToolChoiceTypes — 表示模型应使用内置工具生成响应。 [了解有关内置工具的更多信息](/docs/guides/tools)。 - `type` 'file_search' | 'web_search_preview' | 'computer_use_preview' | 'web_search_preview_2025_03_11' | 'image_generation' | 'code_interpreter' | 'mcp', required — 模型应使用的托管工具的类型。详细了解 [内置工具](/docs/guides/tools)。 允许的值为： - `file_search` - `web_search_preview` - `computer_use_preview` - `code_interpreter` - `mcp` - `image_generation` - ToolChoiceFunction — 使用此选项强制模型调用特定函数。 - `type` 'function', required — 对于函数调用，类型始终为 `function`。 - `name` string, required — 要调用的函数的名称。 - `prompt` Prompt, nullable — 对提示模板及其变量的引用。 - `id` string, required — 提示模板的唯一标识符。 - `version` string, nullable — 提示模板的可选版本。 - `variables` ResponsePromptVariables, nullable — 用于替换提示中变量的可选值映射。替换值可以是字符串，也可以是其他响应输入类型，如图像或文件。 - `truncation` 'auto' | 'disabled', nullable — 用于模型响应的截断策略。 - `auto`：如果此响应及之前的响应的上下文超出了模型的上下文窗口大小，模型将通过删除对话中间的输入项来截断响应以适应上下文窗口。 - `disabled`（默认）：如果模型响应将超出模型的上下文窗口大小，请求将失败并返回 400 错误。 - `input` union — 用于生成响应的文本、图片或文件输入 更多细节: - [文本输入输出](/docs/response/create) - [图片输入](/docs/response/image) - [联网搜索](/docs/response/web_search) - [函数调用](/docs/response/tool_calls) - string — 模型输入文本字符串 - InputItem[] — 多模态对象输入列表 — unresolved $ref - `include` Includable[], nullable — 指定模型响应中需额外包含的数据。目前支持以下值： - `file_search_call.results`: 包含文件搜索工具调用所产生的搜索结果。 - `message.input_image.image_url`: 包含输入消息中的图片链接。 - `computer_call_output.output.image_url`: 包含计算机调用（computer call）输出的图片链接。 - `reasoning.encrypted_content`: 在推理项（reasoning item）的输出中，包含对推理过程令牌（reasoning tokens）的加密版本。如此一来，当以无状态方式使用 Responses API 时（例如，当 store 参数设置为 false，或当组织加入了“零数据保留”计划时），推理项便可在多轮对话中继续使用。 - `code_interpreter_call.outputs`: 包含代码解释器工具调用项中，Python 代码的执行输出。 - `parallel_tool_calls` boolean, nullable — 是否允许模型并行执行工具调用 - `store` boolean, nullable — 是否存储生成的模型响应，以供后续通过 API 检索 - `instructions` string, nullable — 插入到模型上下文中的系统（或开发者）消息。 当与 `previous_response_id` 一同使用时，先前响应中的指令将不会被沿用至新的响应中。这使得在新响应中可以轻松地替换系统（或开发者）消息。 - `stream` boolean, nullable — 若设为 true，模型响应数据将在生成时，通过 [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) 流式传输至客户端。 [代码示例](/docs/response/streaming) ## Response `200` OK - Response - `metadata` Metadata, nullable, required — 一对可以附加到对象的 16 个键值对。这对于以结构化格式存储有关对象的附加信息以及通过 API 或仪表板查询对象非常有用。 键是长度最多为 64 个字符的字符串。值是长度最多为 512 个字符的字符串。 - `temperature` number, nullable, required — 要使用的采样温度，介于 0 和 2 之间。较高的值（如 0.8）将使输出更随机，而较低的值（如 0.2）将使其更聚焦和确定。 我们通常建议修改此项或 `top_p`，但不要同时修改两者。 - `top_p` number, nullable, required — 采样温度的另一种方法，称为核采样，模型会考虑具有 top_p 概率质量的 token 的结果。因此，0.1 意味着只考虑包含前 10% 概率质量的 token。 我们通常建议修改此项或 `temperature`，但不要同时修改两者。 - `user` string — 最终用户的稳定标识符。 用于通过更好地对类似请求进行分桶来提高缓存命中率，并帮助 OpenAI 检测和防止滥用。[了解更多](/docs/guides/safety-best-practices#end-user-ids)。 - `service_tier` 'auto' | 'default' | 'flex' | 'scale', nullable — 指定用于处理请求的延迟等级。此参数适用于订阅了按量计费服务的客户： - 如果设置为“auto”，并且项目启用了按量计费服务，系统将使用按量计费积分直至用尽。 - 如果设置为“auto”，但项目未启用按量计费服务，则请求将使用默认服务等级进行处理，该等级的正常运行时间服务水平协议较低，且无延迟保证。 - 如果设置为“default”，请求将使用默认服务等级进行处理，该等级的正常运行时间服务水平协议较低，且无延迟保证。 - 如果设置为“flex”，请求将使用弹性处理服务等级进行处理。[了解更多](/docs/guides/flex-processing)。 - 如果未设置，则默认行为是“auto”。 设置此参数后，响应体将包含所使用的 `service_tier`。 - `previous_response_id` string, nullable — 模型上一个响应的唯一 ID。使用此 ID 来创建多轮对话。了解有关[对话状态](/docs/guides/conversation-state)的更多信息。 - `model` union, required - union - string - 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'o4-mini' | 'o4-mini-2025-04-16' | 'o3' | 'o3-2025-04-16' | 'o3-mini' | 'o3-mini-2025-01-31' | 'o1' | 'o1-2024-12-17' | 'o1-preview' | 'o1-preview-2024-09-12' | 'o1-mini' | 'o1-mini-2024-09-12' | 'gpt-4o' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4o-audio-preview' | 'gpt-4o-audio-preview-2024-10-01' | 'gpt-4o-audio-preview-2024-12-17' | 'gpt-4o-audio-preview-2025-06-03' | 'gpt-4o-mini-audio-preview' | 'gpt-4o-mini-audio-preview-2024-12-17' | 'gpt-4o-search-preview' | 'gpt-4o-mini-search-preview' | 'gpt-4o-search-preview-2025-03-11' | 'gpt-4o-mini-search-preview-2025-03-11' | 'chatgpt-4o-latest' | 'codex-mini-latest' | 'gpt-4o-mini' | 'gpt-4o-mini-2024-07-18' | 'gpt-4-turbo' | 'gpt-4-turbo-2024-04-09' | 'gpt-4-0125-preview' | 'gpt-4-turbo-preview' | 'gpt-4-1106-preview' | 'gpt-4-vision-preview' | 'gpt-4' | 'gpt-4-0314' | 'gpt-4-0613' | 'gpt-4-32k' | 'gpt-4-32k-0314' | 'gpt-4-32k-0613' | 'gpt-3.5-turbo' | 'gpt-3.5-turbo-16k' | 'gpt-3.5-turbo-0301' | 'gpt-3.5-turbo-0613' | 'gpt-3.5-turbo-1106' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-16k-0613' - 'o1-pro' | 'o1-pro-2025-03-19' | 'o3-pro' | 'o3-pro-2025-06-10' | 'computer-use-preview' | 'computer-use-preview-2025-03-11' - `reasoning` Reasoning — **仅限 o 系列模型** [推理模型](https://platform.openai.com/docs/guides/reasoning)的配置选项。 - `effort` 'low' | 'medium' | 'high', nullable — **仅限 o 系列模型** 对 [推理模型](https://platform.openai.com/docs/guides/reasoning) 的推理工作量进行限制。 当前支持的值有 `low`、`medium` 和 `high`。降低推理工作量可能会导致更快的响应和更少的令牌使用。 - `summary` 'auto' | 'concise' | 'detailed', nullable — 对模型执行的推理的总结。这对于调试和理解模型的推理过程非常有用。 可能的值有 `auto`、`concise` 或 `detailed`。 - `generate_summary` 'auto' | 'concise' | 'detailed', nullable — **Deprecated:** use `summary` instead. 对模型执行的推理的总结。这对于调试和理解模型的推理过程非常有用。 可能的值有 `auto`、`concise` 或 `detailed`。 - `background` boolean, nullable — 是否在后台运行模型响应。 [了解更多](/docs/guides/background). - `max_output_tokens` integer, nullable — 可以为响应生成的 token 的上限，包括可见的输出 token 和[推理 token](/docs/guides/reasoning)。 - `text` object — 模型文本响应的配置选项。可以是纯文本或结构化 JSON 数据。了解更多： - [文本输入和输出](/docs/guides/text) - [结构化输出](/docs/guides/structured-outputs) - `format` union — 一个指定模型必须输出格式的对象。 配置 `{ "type": "json_schema" }` 可启用结构化输出，确保模型符合您提供的 JSON 架构。在[结构化输出指南](/docs/guides/structured-outputs)中了解更多信息。 默认格式为 `{ "type": "text" }`，不带任何附加选项。 **不建议用于 gpt-4o 及更新模型：** 设置为 `{ "type": "json_object" }` 可启用较旧的 JSON 模式，该模式可确保模型生成的消息是有效的 JSON。对于支持它的模型，建议使用 `json_schema`。 - ResponseFormatText — 默认响应格式。用于生成文本响应。 - `type` 'text', required — 正在定义的响应格式的类型。始终为 `text`。 - TextResponseFormatJsonSchema — JSON Schema 响应格式。用于生成结构化 JSON 响应。 详细了解[结构化输出](/docs/guides/structured-outputs)。 - `type` 'json_schema', required — 响应格式的类型。始终为 `json_schema`。 - `description` string — 响应格式的描述。用于模型确定如何以该格式进行响应。 - `name` string, required — 响应格式的名称。必须是 a-z、A-Z、0-9，或包含下划线和短横线，且最大长度为 64。 - `schema` ResponseFormatJsonSchemaSchema, required — 响应格式的模式，描述为 JSON Schema 对象。 了解有关如何构建 JSON Schema 的更多信息 [here](https://json-schema.org/)。 - `strict` boolean, nullable — 是否在生成输出时启用严格的架构遵循。 如果设置为 true，模型将始终遵循 `schema` 字段中定义的确切架构。 当 `strict` 为 `true` 时，仅支持 JSON Schema 的子集。要了解更多信息，请阅读 [结构化输出指南](/docs/guides/structured-outputs)。 - ResponseFormatJsonObject — JSON 对象响应格式。生成 JSON 响应的旧方法。 建议对支持 `json_schema` 的模型使用它。请注意，模型不会在没有系统消息或用户消息指示的情况下生成 JSON。 - `type` 'json_object', required — 正在定义的响应格式的类型。始终为 `json_object`。 - `tools` Tool[], required — 模型在生成响应时可以调用的工具数组。您可以通过设置 `tool_choice` 参数来指定要使用的工具。 您可以为模型提供的两类工具是： - **内置工具**：由 OpenAI 提供、扩展模型功能的工具，例如[网页搜索](/docs/guides/tools-web-search)或[文件搜索](/docs/guides/tools-file-search)。了解更多有关[内置工具](/docs/guides/tools)的信息。 - **函数调用（自定义工具）**：由您定义的函数，使模型能够调用您自己的代码。了解更多有关[函数调用](/docs/guides/function-calling)的信息。 - union — 可用于生成响应的工具。 - FunctionTool — 定义一个模型可以选择调用的函数。了解有关 [函数调用](https://platform.openai.com/docs/guides/function-calling) 的更多信息。 - `type` 'function', required — 函数工具的类型。始终为 `function`。 - `name` string, required — 要调用的函数的名称。 - `description` string, nullable — 函数的描述。用于模型确定是否调用该函数。 - `parameters` object, nullable, required — 描述函数参数的 JSON schema 对象。 - `strict` boolean, nullable, required — 是否强制执行严格的参数验证。默认值为 `true`。 - FileSearchTool — 一个搜索已上传文件中相关内容的工具。详细了解 [文件搜索工具](https://platform.openai.com/docs/guides/tools-file-search)。 - `type` 'file_search', required — 文件搜索工具的类型。始终为 `file_search`。 - `vector_store_ids` string[], required — 要搜索的向量存储的 ID。 - `max_num_results` integer — 要返回的最大结果数。此数字应介于 1 和 50 之间（包括 1 和 50）。 - `ranking_options` RankingOptions - `ranker` 'auto' | 'default-2024-11-15' — 用于文件搜索的排名器。 - `score_threshold` number — 文件搜索的分数阈值，介于 0 和 1 之间的数字。接近 1 的数字将尝试仅返回最相关的结果，但可能返回更少的结果。 - `filters` union - unknown - unknown - WebSearchPreviewTool — 该工具在网络上搜索相关结果以用于响应。详细了解 [Web 搜索工具](https://platform.openai.com/docs/guides/tools-web-search)。 - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required — Web 搜索工具的类型。可以是 `web_search_preview` 或 `web_search_preview_2025_03_11`。 - `user_location` ApproximateLocation - `type` 'approximate', required — 位置近似的类型。始终为 `approximate`。 - `country` string, nullable — 用户的两字母 [ISO 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1)，例如 `US`。 - `region` string, nullable — 用户的自由文本输入的地区，例如 `California`。 - `city` string, nullable — 用户的自由文本输入的城市，例如 `San Francisco`。 - `timezone` string, nullable — 用户的 [IANA 时区](https://timeapi.io/documentation/iana-timezones)，例如 `America/Los_Angeles`。 - `search_context_size` 'low' | 'medium' | 'high' — 有关搜索使用的上下文窗口空间量的高级指导。可以是 `low`、`medium` 或 `high`。`medium` 是默认值。 - ComputerUsePreviewTool — 一个控制虚拟计算机的工具。详细了解 [计算机使用工具](https://platform.openai.com/docs/guides/tools-computer-use)。 - `type` 'computer_use_preview', required — 计算机使用工具的类型。始终为 `computer_use_preview`。 - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required — 要控制的计算机环境的类型。 - `display_width` integer, required — 计算机显示器的宽度。 - `display_height` integer, required — 计算机显示器的高度。 - MCPTool — 通过远程模型上下文协议 (MCP) 服务器为模型提供对其他工具的访问 - `type` 'mcp', required — 项目的类型。始终为 `mcp`。 - `server_label` string, required — 此 MCP 服务器的标签，用于在工具调用中标识它。 - `server_url` string, required — MCP 服务器的 URL。 - `headers` object, nullable — 可选的 HTTP 头部，用于发送到 MCP 服务器。可用于身份验证或其他目的。 - `allowed_tools` union — 允许的工具名称列表或过滤器对象。 - string[] — 允许的工具名称的字符串数组 - object — 用于指定允许哪些工具的过滤器对象。 - `tool_names` string[] — 允许的工具名称列表。 - `require_approval` union — 指定 MCP 服务器的哪些工具需要批准。 - object - `always` object — 始终需要批准的工具列表。 - … - `never` object — 从不需要批准的工具列表。 - … - 'always' | 'never' — 为所有工具指定单一的批准策略。可以是 `always` 或 `never`。设置为 `always` 时，所有工具都将需要批准。设置为 `never` 时，所有工具都将不需要批准。 - unknown - ImageGenTool — 一个使用类似 `gpt-image-1` 的模型生成图像的工具。 - `type` 'image_generation', required — 图像生成工具的类型。始终为 `image_generation`。 - `model` 'gpt-image-1' — 要使用的图像生成模型。默认值：`gpt-image-1`。 - `quality` 'low' | 'medium' | 'high' | 'auto' — 生成图像的质量。可以是 `low`、`medium`、`high` 或 `auto`。默认值：`auto`。 - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto' — 生成图像的大小。可以是 `1024x1024`、`1024x1536`、`1536x1024` 或 `auto`。默认值：`auto`。 - `output_format` 'png' | 'webp' | 'jpeg' — 生成图像的输出格式。可以是 `png`、`webp` 或 `jpeg`。默认值：`png`。 - `output_compression` integer — 输出图像的压缩级别。默认值：100。 - `moderation` 'auto' | 'low' — 生成图像的审核级别。默认值：`auto`。 - `background` 'transparent' | 'opaque' | 'auto' — 生成图像的背景类型。可以是 `transparent`、`opaque` 或 `auto`。默认值：`auto`。 - `input_image_mask` object — 可选的蒙版图像。包含 `image_url`（字符串，可选）和 `file_id`（字符串，可选）。 - `image_url` string — Base64 编码的蒙版图像 - `file_id` string — 蒙版图像的文件 ID - `partial_images` integer — 在流式模式下生成的部分图像数量，范围从 0（默认值）到 3。 - LocalShellTool — 允许模型在本地环境中执行 shell 命令的工具。 - `type` 'local_shell', required — 本地 shell 工具的类型。始终为 `local_shell`。 - `tool_choice` union, required — 模型在生成响应时应如何选择使用哪个工具（或多个工具）。请参阅 `tools` 参数以了解如何指定模型可以调用的工具。 - 'none' | 'auto' | 'required' — 控制模型调用哪个（如果有）工具。 `none` 表示模型将不调用任何工具，而是生成一条消息。 `auto` 表示模型可以选择生成消息或调用一个或多个工具。 `required` 表示模型必须调用一个或多个工具。 - ToolChoiceTypes — 表示模型应使用内置工具生成响应。 [了解有关内置工具的更多信息](/docs/guides/tools)。 - `type` 'file_search' | 'web_search_preview' | 'computer_use_preview' | 'web_search_preview_2025_03_11' | 'image_generation' | 'code_interpreter' | 'mcp', required — 模型应使用的托管工具的类型。详细了解 [内置工具](/docs/guides/tools)。 允许的值为： - `file_search` - `web_search_preview` - `computer_use_preview` - `code_interpreter` - `mcp` - `image_generation` - ToolChoiceFunction — 使用此选项强制模型调用特定函数。 - `type` 'function', required — 对于函数调用，类型始终为 `function`。 - `name` string, required — 要调用的函数的名称。 - `prompt` Prompt, nullable — 对提示模板及其变量的引用。 - `id` string, required — 提示模板的唯一标识符。 - `version` string, nullable — 提示模板的可选版本。 - `variables` ResponsePromptVariables, nullable — 用于替换提示中变量的可选值映射。替换值可以是字符串，也可以是其他响应输入类型，如图像或文件。 - `truncation` 'auto' | 'disabled', nullable — 用于模型响应的截断策略。 - `auto`：如果此响应及之前的响应的上下文超出了模型的上下文窗口大小，模型将通过删除对话中间的输入项来截断响应以适应上下文窗口。 - `disabled`（默认）：如果模型响应将超出模型的上下文窗口大小，请求将失败并返回 400 错误。 - `id` string, required — 此响应的唯一标识符 - `object` 'response', required — 该资源的对象类型 - 始终设置为 `response`。 - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete' — 响应生成的状态。可能的值有 `completed`、`failed`、 `in_progress`、`cancelled`、`queued` 或 `incomplete`。 - `created_at` number, required — 此响应创建时的 Unix 时间戳（以秒为单位）。 - `error` ResponseError, nullable, required — 当模型未能生成响应时返回的错误对象。 - `code` 'server_error' | 'rate_limit_exceeded' | 'invalid_prompt' | 'vector_store_timeout' | 'invalid_image' | 'invalid_image_format' | 'invalid_base64_image' | 'invalid_image_url' | 'image_too_large' | 'image_too_small' | 'image_parse_error' | 'image_content_policy_violation' | 'invalid_image_mode' | 'image_file_too_large' | 'unsupported_image_media_type' | 'empty_image_file' | 'failed_to_download_image' | 'image_file_not_found', required — 响应的错误代码。 - `message` string, required — 错误的易读描述。 - `incomplete_details` object, nullable, required — 响应不完整的详细信息。 - `reason` 'max_output_tokens' | 'content_filter' — 响应不完整的原因。 - `output` OutputItem[], required — 由模型生成的内容项数组。 - `output` 数组中项目的长度和顺序取决于模型的响应。 - 与其访问 `output` 数组中的第一个项目并假设它是包含模型生成内容的 `assistant` 消息，不如考虑在 SDK 中使用 `output_text` 属性（如果支持）。 - union - OutputMessage — 来自模型的输出消息。 - `id` string, required — 输出消息的唯一 ID。 - `type` 'message', required — 输出消息的类型。始终为 `message`。 - `role` 'assistant', required — 输出消息的角色。始终为 `assistant`。 - `content` OutputContent[], required — 输出消息的内容。 - union - OutputTextContent — 模型文本输出 - … - RefusalContent — 来自模型的拒绝。 - … - `status` 'in_progress' | 'completed' | 'incomplete', required — 输出消息的状态。可能的值有 `in_progress`、`completed` 或 `incomplete`。当通过 API 返回输入项时填充此字段。 - unknown - FunctionToolCall — 用于运行函数的工具调用。更多信息请参见[函数调用代码示例](/docs/response/tool_calls)。 - `id` string — 函数工具调用的唯一 ID。 - `type` 'function_call', required — 函数工具调用的类型。始终为 `function_call`。 - `call_id` string, required — 由模型生成的函数工具调用的唯一 ID。 - `name` string, required — 要运行的函数的名称。 - `arguments` string, required — 要传递给函数的参数的 JSON 字符串。 - `status` 'in_progress' | 'completed' | 'incomplete' — 项目的状态。可以是 `in_progress`、`completed` 或 `incomplete`。当通过 API 返回项目时填充。 - WebSearchToolCall — 网页搜索工具调用的结果。有关更多信息，请参阅 [网页搜索指南](/docs/guides/tools-web-search)。 - `id` string, required — 网页搜索工具调用的唯一 ID。 - `type` 'web_search_call', required — 网页搜索工具调用的类型。始终为 `web_search_call`。 - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required — 网页搜索工具调用的状态。 - unknown - ReasoningItem — 对推理模型在生成响应时使用的思维链的描述。确保在手动 [管理上下文](/docs/guides/conversation-state) 时将这些项目包含在对 Responses API 的 `input` 中，以便在对话的后续轮次中使用。 - `type` 'reasoning', required — 对象的类型。始终为 `reasoning`。 - `id` string, required — 推理内容的唯一标识符。 - `encrypted_content` string, nullable — 推理项的加密内容 - 在生成响应时填充 `reasoning.encrypted_content` 的 `include` 参数。 - `summary` object[], required — 推理文本内容。 - `type` 'summary_text', required — 对象的类型。始终为 `summary_text`。 - `text` string, required — 对模型生成响应时使用的推理的简短总结。 - `status` 'in_progress' | 'completed' | 'incomplete' — 项目的状态。可能的值有 `in_progress`、`completed` 或 `incomplete`。当通过 API 返回项目时填充。 - ImageGenToolCall — 由模型发起的图像生成请求。 - `type` 'image_generation_call', required — 图像生成调用的类型。始终为 `image_generation_call`。 - `id` string, required — 图像生成调用的唯一 ID。 - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required — 图像生成调用的状态。 - `result` string, nullable, required — 生成的图像的 Base64 编码。 - unknown - LocalShellToolCall — 一个在本地 shell 上运行命令的工具调用。 - `type` 'local_shell_call', required — 本地 shell 调用的类型。始终为 `local_shell_call`。 - `id` string, required — 本地 shell 调用的唯一 ID。 - `call_id` string, required — 由模型生成的本地 shell 工具调用的唯一 ID。 - `action` LocalShellExecAction, required — 在服务器上执行一条 shell 命令 - `type` 'exec', required — 本地 shell 操作的类型。始终为 `exec`。 - `command` string[], required — 要运行的命令。 - `timeout_ms` integer, nullable — 可选的命令超时时间 - `working_directory` string, nullable — 可选的命令工作目录 - `env` object, required — 要设置的环境变量。 - `user` string, nullable — 可选的用户，以该用户身份运行命令。 - `status` 'in_progress' | 'completed' | 'incomplete', required — 本地 shell 调用的状态。 - MCPToolCall — 在 MCP 服务器上调用工具。 - `type` 'mcp_call', required — 项目的类型。始终为 `mcp_call`。 - `id` string, required — 工具调用的唯一 ID。 - `server_label` string, required — 运行该工具的 MCP 服务器的标签。 - `name` string, required — 运行的工具的名称。 - `arguments` string, required — 传递给工具的参数的 JSON 字符串。 - `output` string, nullable — 工具调用的输出。 - `error` string, nullable — 工具调用的错误（如果有）。 - MCPListTools — MCP 服务器上可用工具的列表。 - `type` 'mcp_list_tools', required — 项目的类型。始终为 `mcp_list_tools`。 - `id` string, required — 列表的唯一 ID。 - `server_label` string, required — MCP 服务器的标签。 - `tools` MCPListToolsTool[], required — 服务器上可用的工具。 - `name` string, required — 工具的名称。 - `description` string, nullable — 工具的描述。 - `input_schema` object, required — 描述工具输入的 JSON 架构。 - `annotations` object, nullable — 有关工具的其他注释。 - `error` string, nullable — 如果服务器无法列出工具，则为错误消息。 - MCPApprovalRequest — 对工具调用的人类批准请求。 - `type` 'mcp_approval_request', required — 项目的类型。始终为 `mcp_approval_request`。 - `id` string, required — 批准请求的唯一 ID。 - `server_label` string, required — 发起请求的 MCP 服务器的标签。 - `name` string, required — 要运行的工具的名称。 - `arguments` string, required — 用于工具的参数的 JSON 字符串。 - `instructions` union, required — 插入到模型上下文中的系统（或开发者）消息。 当与 `previous_response_id` 一起使用时，前一个响应中的指令不会延续到下一个响应。这使得在新的响应中轻松替换系统（或开发者）消息变得容易。 - string — 发送给模型的文本输入，相当于具有 `developer` 角色的文本输入。 - InputItem[] — 发送给模型的一个或多个输入项的列表，包含不同的内容类型。 — unresolved $ref - `output_text` string, nullable — 仅限 SDK 的便利属性，包含 `output` 数组中所有 `output_text` 项的聚合文本输出（如果存在）。 在 Python 和 JavaScript SDK 中支持。 - `usage` ResponseUsage — 表示令牌使用详情，包括输入令牌、输出令牌、输出令牌的明细以及使用的总令牌。 - `input_tokens` integer, required — 输入令牌的数量。 - `input_tokens_details` object, required — 输入令牌的详细明细。 - `cached_tokens` integer, required — 从缓存中检索的令牌数量。 [有关提示缓存的更多信息](/docs/chat/prompt_caching)。 - `output_tokens` integer, required — 输出令牌的数量。 - `output_tokens_details` object, required — 输出令牌的详细明细。 - `reasoning_tokens` integer, required — 推理令牌的数量。 - `total_tokens` integer, required — 使用的总令牌数量。 - `parallel_tool_calls` boolean, required — 是否允许模型并行运行工具调用。 --- [API](https://skmtc.dev/geekai/apis/api.md) · [All operations](https://skmtc.dev/geekai/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/geekai/api/revisions/2bf0c8f70a39/schema)