GPT-5 聊天 API(Responses)技术对接分享
本文基于 6AI 中转服务与 Apifox 文档,覆盖了 GPT-5 聊天 API(Responses)的全流程对接要点。开发人员可根据业务需求调整 temperature、stream、tools 等参数,建议先通过 cURL 验证接口连通性,再基于 Python/Java 等语言实现生产级集成,同时严格遵循 Token 安全管理与 Token 长度管控规范,确保接口稳定运行。
1. 引言
本文基于 API 中转网站 https://api.6ai.chat/ 及 Apifox 对接文档(https://six-ai.apifox.cn/333592455e0),详细拆解 GPT-5 聊天接口(Responses 模块)的技术对接规范,包括认证方式、请求参数配置、实战代码示例、响应解析及风险注意事项,适用于开发人员快速完成 GPT-5 接口集成。
2. 前置准备:API 授权 Token 获取与管理
GPT-5 接口对接的核心前提是 授权 Token,所有请求需通过 Authorization 头携带 Token 完成身份验证,步骤如下:
- 从 6AI 中转服务控制台获取专属 API Token(格式为 32 位或更长字符组合);
- 存储 Token 时需遵循安全规范:避免硬编码到前端代码,后端需通过环境变量或加密配置管理;
- 授权格式要求:Token 需拼接在 Bearer 后,形成完整请求头值(示例:Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)。
3. 核心对接规范:请求结构与参数详解
GPT-5 聊天接口采用 POST 方法,请求端点为 http://prod-cn.your-api-server.com/v1/responses,需严格遵循以下请求结构(含必选 / 可选参数)。
3.1 请求头参数(Header)
所有请求必须包含以下头信息,确保协议兼容性与身份验证:
参数名 |
类型 |
必需性 |
说明 |
示例值 |
Content-Type |
string |
是 |
请求体格式,固定为 JSON |
application/json |
Accept |
string |
是 |
响应格式,固定为 JSON |
application/json |
Authorization |
string |
是 |
身份授权,Bearer + Token 组合 |
Bearer sk-xxxxxxxxxxxxxx |
3.2 请求体参数(Body)
请求体为 JSON 格式,包含 必选参数 与 可选参数,需根据业务场景配置。其中 model、messages、tools、tool_choice 为核心必选参数,缺一不可。
3.2.1 必选参数详解
参数名 |
类型 |
说明 |
示例值 |
model |
string |
GPT-5 模型 ID(需与中转服务支持的模型匹配) |
gpt-5 |
messages |
array[object] |
对话历史列表,每个对象含 role(角色)与 content(内容) |
[{"role":"user","content":"写一个独角兽的睡前故事"}] |
tools |
array[string] |
模型可调用的工具列表(当前仅支持函数工具,需传入函数名) |
["get_weather_data"] |
tool_choice |
object |
工具调用控制策略,支持 none/auto/ 指定函数 |
{"type":"function","function":{"name":"get_weather_data"}} |
3.2.2 可选参数详解(核心配置)
参数名 |
类型 |
取值范围 |
说明 |
stream |
boolean |
true/false |
是否启用流式返回(如 ChatGPT 实时输出),true 时需处理 SSE 事件 |
temperature |
number |
0~2 |
采样随机性:值越高越随机(如 0.8),值越低越确定(如 0.2) |
top_p |
number |
0~1 |
核采样:仅考虑前 top_p 概率质量的 token,与 temperature 二选一 |
max_tokens |
integer |
≥1 |
生成内容的最大 token 数(含输入 + 输出,需符合模型上下文限制) |
presence_penalty |
number |
-2.0~2.0 |
主题新颖性:正值减少重复主题,负值增加重复主题 |
frequency_penalty |
number |
-2.0~2.0 |
内容重复性:正值减少重复文本,负值增加重复文本 |
response_format |
object |
- |
强制输出格式,如 {"type":"json_object"} 启用 JSON 模式 |
seen |
integer |
- |
测试阶段参数:种子值,用于确定性采样(相同参数可能返回相同结果) |
4. 实战代码示例:多语言请求实现
以下提供 cURL(快速测试)与 Python(流式返回处理)两种常见场景的代码示例,均基于 GPT-5 核心配置。
4.1 cURL 示例(快速验证接口连通性)
适用于开发初期快速测试接口是否可用,需替换 {{YOUR_API_KEY}} 为实际 Token:
curl --location --request POST 'http://prod-cn.your-api-server.com/v1/responses' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"model": "gpt-5",
"stream": true,
"messages": [
{
"role": "user",
"content": "Write a one-sentence bedtime story about a unicorn."
}
],
"tools": ["format_story_output"],
"tool_choice": {
"type": "function",
"function": {"name": "format_story_output"}
},
"temperature": 0.6,
"max_tokens": 512
}'
4.2 Python 示例(流式返回处理)
适用于生产环境,通过 requests 库处理流式响应(需先安装 pip install requests):
import requests
import json
# 1. 配置基础参数
API_URL = "http://prod-cn.your-api-server.com/v1/responses"
API_KEY = "Bearer {{YOUR_API_KEY}}" # 替换为实际Token
HEADERS = {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": API_KEY
}
# 2. 构造请求体
PAYLOAD = {
"model": "gpt-5",
"stream": True, # 启用流式返回
"messages": [
{"role": "user", "content": "Write a one-sentence bedtime story about a unicorn."}
],
"tools": ["format_story_output"],
"tool_choice": {
"type": "function",
"function": {"name": "format_story_output"}
},
"temperature": 0.6,
"max_tokens": 512
}
# 3. 发送请求并处理流式响应
try:
response = requests.post(
API_URL,
headers=HEADERS,
json=PAYLOAD,
stream=True # 关键:启用流式接收
)
response.raise_for_status() # 捕获HTTP错误(如401授权失败)
# 迭代处理每一条流式数据
for chunk in response.iter_lines(decode_unicode=True):
if chunk:
# 检查是否为结束信号
if chunk == "data: [DONE]":
print("\n流式返回结束")
break
# 解析JSON数据(需去除前缀"data: ",若存在)
if chunk.startswith("data: "):
chunk = chunk[6:]
data = json.loads(chunk)
# 提取助手回复内容
if "choices" in data and len(data["choices"]) > 0:
content = data["choices"][0]["message"].get("content", "")
if content:
print(content, end="", flush=True) # 实时输出
# 解析最终使用的Token统计
usage = data.get("usage", {})
print(f"\nToken使用统计:")
print(f"请求Token: {usage.get('prompt_tokens', 0)}")
print(f"响应Token: {usage.get('completion_tokens', 0)}")
print(f"总Token: {usage.get('total_tokens', 0)}")
except requests.exceptions.RequestException as e:
print(f"请求异常:{e}")
except json.JSONDecodeError as e:
print(f"JSON解析异常:{e}")
5. 响应数据解析:结构与字段说明
GPT-5 接口返回 HTTP 200 OK 时,响应体为 JSON 格式,包含 顶层元数据、结果列表(choices) 与 Token 统计(usage) 三部分。
5.1 响应体结构示例
5.2 核心字段说明
字段路径 |
类型 |
说明 |
id |
string |
请求唯一 ID(用于问题排查) |
object |
string |
响应类型,固定为 chat.completion |
created |
integer |
响应生成时间戳(Unix 秒级) |
choices[0].index |
integer |
结果索引(多结果时用,默认 n=1) |
choices[0].message |
object |
助手回复内容,含 role(assistant)、content(文本)、function_call(工具调用) |
choices[0].finish_reason |
string |
结束原因:- stop:正常完成- length:超 max_tokens- function_call:触发工具调用 |
usage.prompt_tokens |
integer |
请求(对话历史)消耗的 Token 数 |
usage.completion_tokens |
integer |
响应(生成内容)消耗的 Token 数 |
usage.total_tokens |
integer |
总 Token 数(需 ≤ 模型上下文长度) |
6. 关键注意事项与风险规避
- JSON 模式使用限制
当 response_format: {"type":"json_object"} 时,必须在 messages 中通过用户 / 系统消息明确指示模型生成 JSON(如 “输出格式为标准 JSON”),否则可能导致流式返回 “卡住”(无限空白流)。
- 确定性采样(seen 参数)的局限性
seen 参数处于测试阶段,仅 “尽最大努力” 保证相同参数返回相同结果,不承诺 100% 确定性;需通过 system_fingerprint 响应字段监控后端模型版本变化。
- Token 长度管控
输入(messages)与输出(max_tokens)的总 Token 数不得超过 GPT-5 上下文限制(需参考中转服务文档),否则会触发 finish_reason: "length",导致响应内容被截断。
- 工具调用配置正确性
-
- tools 数组需传入实际可用的函数名,不可为空;
-
- tool_choice 设为 none 时,模型仅生成文本,不调用工具;设为 auto 时,模型自主决定是否调用工具。
7. 常见问题排查(Troubleshooting)
问题现象 |
可能原因 |
解决方案 |
401 未授权错误 |
Token 错误 / 过期 / 未携带 Bearer 前缀 |
验证 Token 有效性,确认请求头格式为 Bearer {{Token}} |
流式返回无内容 |
未配置 JSON 模式提示 /max_tokens 过小 |
补充 JSON 生成指示,增大 max_tokens 至合理值(如 1024) |
工具调用未触发 |
tools 函数名错误 /tool_choice 设为 none |
核对函数名,将 tool_choice 改为 auto 或指定函数 |
响应内容重复率高 |
frequency_penalty 取值过低 |
调整 frequency_penalty 至 0.5~1.0 区间 |
8. 结语
本文基于 6AI 中转服务与 Apifox 文档,覆盖了 GPT-5 聊天 API(Responses)的全流程对接要点。开发人员可根据业务需求调整 temperature、stream、tools 等参数,建议先通过 cURL 验证接口连通性,再基于 Python/Java 等语言实现生产级集成,同时严格遵循 Token 安全管理与 Token 长度管控规范,确保接口稳定运行。
更多推荐
所有评论(0)