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 完成身份验证,步骤如下:

  1. 从 6AI 中转服务控制台获取专属 API Token(格式为 32 位或更长字符组合);
  1. 存储 Token 时需遵循安全规范:避免硬编码到前端代码,后端需通过环境变量或加密配置管理;
  1. 授权格式要求: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. 关键注意事项与风险规避

  1. JSON 模式使用限制

当 response_format: {"type":"json_object"} 时,必须在 messages 中通过用户 / 系统消息明确指示模型生成 JSON(如 “输出格式为标准 JSON”),否则可能导致流式返回 “卡住”(无限空白流)。

  1. 确定性采样(seen 参数)的局限性

seen 参数处于测试阶段,仅 “尽最大努力” 保证相同参数返回相同结果,不承诺 100% 确定性;需通过 system_fingerprint 响应字段监控后端模型版本变化。

  1. Token 长度管控

输入(messages)与输出(max_tokens)的总 Token 数不得超过 GPT-5 上下文限制(需参考中转服务文档),否则会触发 finish_reason: "length",导致响应内容被截断。

  1. 工具调用配置正确性
    • 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 长度管控规范,确保接口稳定运行。

Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐