结构化输出

POST  v1/chat/completions

这是 OpenAI 较新的功能（GPT-4o 及以上版本支持），用于强制模型返回结构化的 JSON 数据，解决了大模型自由文本回复格式不统一、难以被程序解析的问题

请求参数

Authorization

在 Header 添加参数 Authorization，其值为在 Bearer 之后拼接 Token。

Authorization: Bearer ******************

Header 参数

参数	类型	必填	说明	示例
Content-Type	string	可选	请求体的数据格式类型	application/json
Accept	string	可选	客户端期望接收的响应数据格式	application/json

Body 参数

Content-Type: application/json

参数名	类型	必填项	说明
model	string	必需	要使用的模型 ID。有关哪些模型适用于 Chat API 的详细信息，请参阅模型端点兼容性表。
messages	array [object]	必需	模型聊天记录
└─role	string	可选	角色类型：user / assistant / system
└─content	string	可选	文本内容
response_format	object	必需	指定模型必须输出的格式对象。
└─type	string	必需	格式类型： 1. "json_schema"：启用结构化输出，模型将严格匹配提供的 JSON Schema。 2. "json_object"：启用普通 JSON 模式，确保输出是有效的 JSON。
└─json_schema	object	必需	当 type 为 "json_schema" 时必须提供，定义具体的 Schema 结构。
store	boolean	可选	是否存储此聊天补全请求的输出以用于模型蒸馏或评估产品。
reasoning_effort	string	可选	仅适用于 o 系列的模型。 约束推理模型的推理工作。当前支持的值为 low、medium 和 high。减少推理工作可以加快响应速度并减少响应中用于推理的标记数。
metadata	object	可选	可以附加到对象的 16 个键值对集合。这对于以结构化格式存储对象的其他信息很有用，并可以通过 API 或仪表板查询对象。 - 键：最大长度为 64 个字符的字符串。 - 值：最大长度为 512 个字符的字符串。
modalities	array[string]	可选	您希望模型为此请求生成的输出类型。大多数模型都能生成文本，这是默认设置：["text"]。 该模型还可以用于生成音频。要请求此模型同时生成文本和音频响应，您可以使用：["text", "audio"]
prediction	object	可选	预测输出的配置。当提前知道模型响应的大部分内容时，可以大大提高响应时间。这在您只对文件进行微小更改时最常见。
audio	object	可选	音频输出的参数。当使用 modalities: ["audio"] 请求音频输出时需要。
temperature	number	可选	要使用的采样温度，介于 0 和 2 之间。 - 较高值（如 0.8）：使输出更加随机。 - 较低值（如 0.2）：使其更加集中和确定性。 建议：通常建议更改此值或 top_p，但不要同时更改。
top_p	number	可选	一种替代采样温度的方法，称为核采样，其中模型考虑具有 top_p 概率质量的标记结果。因此，0.1 意味着只考虑包含前 10% 概率质量的标记。 建议：通常建议更改此值或 temperature，但不要同时更改。
n	integer	可选	为每个输入消息生成多少个聊天补全选择。请注意，您将根据所有选择生成的标记数量收费。保持 n 为 1 可最大限度地降低成本。
stop	string	可选	不支持最新的推理模型和 .o3、o4-mini。 API 将停止生成更多标记的最多 4 个序列。返回的文本不会包含停止序列。
max_completion_tokens	integer	可选	补全中可以生成的标记数的上限，包括可见输出标记和推理标记。
presence_penalty	number	可选	介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中出现的情况来惩罚它们，从而增加模型讨论新主题的可能性。
frequency_penalty	number	可选	介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中的现有频率来惩罚它们，从而降低模型逐字重复同一行的可能性。
logit_bias	string	可选	修改指定标记出现在补全中的可能性。 接受一个 JSON 对象，该对象将标记（由分词器中的标记 ID 指定）映射到从 -100 到 100 的关联偏差值。在数学上，偏差被添加到模型在采样之前生成的对数中。确切的效果会因模型而异，但介于 -1 和 1 之间的值应该会减少或增加选择的可能性；像 -100 或 100 这样的值应该导致相关标记被禁止或独占选择。
logprobs	boolean	可选	是否在响应中包含对数概率。
user	string	可选	表示最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。

请求示例 (JSON)

{
    "model": "gpt-4.1-mini",
    "messages": [
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
}

返回响应

200 成功

Content-Type: application/json

响应参数

参数	类型	必填	说明
id	string	必需	聊天补全对象的唯一标识符。
object	string	必需	对象类型，通常为 "chat.completion"。
created	integer	必需	补全创建时的 Unix 时间戳（秒）。
model	string	必需	用于生成此补全的模型。
choices	array [object]	必需	模型生成的补全列表。
└─index	integer	可选	此补全在其列表中的索引。
└─message	object	可选	包含模型生成的响应消息的对象。
└─logprobs	null	可选	如果请求中设置了 logprobs，则包含标记的对数概率。
└─finish_reason	string	可选	模型停止生成补全的原因。可能是 "stop"、"length" 或 "tool_calls"。
usage	object	必需	此补全请求使用的令牌统计信息。
└─prompt_tokens	integer	必需	提示中使用的令牌数量。
└─completion_tokens	integer	必需	补全中生成的令牌数量。
└─total_tokens	integer	必需	使用的总令牌数（提示 + 补全）。

响应示例

{
    "id": "chatcmpl-CQne0GUFU3glJ6vgbwByj0RbKVTxJ",
    "object": "chat.completion",
    "created": 1760503396,
    "model": "gpt-4.1-mini-2025-04-14",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! How can I assist you today?",
                "refusal": null,
                "annotations": []
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 9,
        "total_tokens": 18,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "audio_tokens": 0
        },
        "completion_tokens_details": {
            "reasoning_tokens": 0,
            "audio_tokens": 0,
            "accepted_prediction_tokens": 0,
            "rejected_prediction_tokens": 0
        }
    },
    "service_tier": "default",
    "system_fingerprint": "fp_c064fdde7c"
}

示例代码

import http.client
import json

conn = http.client.HTTPSConnection("nxaiapp.com")
payload = json.dumps({
   "model": "gpt-4.1-mini",
   "messages": [
      {
         "role": "user",
         "content": "Hello!"
      }
   ]
})
headers = {
   'Accept': 'application/json',
   'Authorization': 'Bearer <token>',
   'Content-Type': 'application/json'
}
conn.request("POST", "/v1/chat/completions", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))