本文以 OpenAI 平台最常用的聊天完成接口（Chat Completions API）为例，详细介绍该接口的调用方式。内容涵盖请求（Request）与响应（Response）的具体示例，以及关键字段的说明。

1. 接口基本信息

  • 接口地址：https://api.openai.com/v1/chat/completions
  • 请求方法：POST
  • 认证方式：需在请求头（Header）中设置 Authorization 字段，值为 Bearer YOUR_API_KEY。其中 YOUR_API_KEY 为您在 OpenAI 平台获取的 API 密钥。

2. 请求（Request）示例

以下 Python 代码展示了如何使用 requests 库发送请求：

import requests

url = "https://api.openai.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "gpt-3.5-turbo",
    "messages": [
        {
            "role": "system",
            "content": "你是一个知识渊博的助手"
        },
        {
            "role": "user",
            "content": "请介绍一下人工智能的发展历史"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 200
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

上述代码中，headers 包含了认证信息与内容类型，data 字典则定义了请求的具体参数：

  • model：指定使用的模型，示例中为 gpt-3.5-turbo。
  • messages：对话历史数组。第一个元素为系统消息（system），用于设定助手角色；第二个元素为用户消息（user），即用户的提问。
  • temperature：设置为 0.7，控制生成文本的随机性。
  • max_tokens：限制生成文本的最大令牌数（Token）为 200。

3. 请求字段说明

字段名类型是否必填描述
model字符串是要使用的模型名称，如 gpt-3.5-turbo、gpt-4 等
messages数组是对话消息数组，每个元素是一个包含 role（system、user、assistant）和 content 的对象
temperature浮点数否控制生成文本的随机性，取值范围 0 - 2，默认值为 1
max_tokens整数否生成文本的最大令牌数，默认值由模型决定
top_p浮点数否另一种控制生成文本多样性的方式，与 temperature 类似，取值范围 0 - 1，默认值为 1
n整数否生成的回复数量，默认值为 1
stop字符串或数组否遇到指定的字符串或数组中的元素时，停止生成文本
presence_penalty浮点数否控制新生成内容中引入新话题的惩罚系数，取值范围 -2.0 - 2.0，默认值为 0
frequency_penalty浮点数否控制新生成内容中重复内容的惩罚系数，取值范围 -2.0 - 2.0，默认值为 0

4. 响应（Response）示例

接口成功调用后，将返回如下 JSON 格式数据：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "人工智能的发展历史可以追溯到 20 世纪中叶。1956 年，达特茅斯会议被广泛认为是人工智能诞生的标志，在这次会议上，“人工智能”这一术语正式被提出。此后，人工智能经历了多个发展阶段。在早期，研究主要集中在符号推理和专家系统方面。到了 20 世纪 80 年代，专家系统得到了广泛应用，但也暴露出一些局限性。随着计算机技术的不断发展，尤其是计算能力的大幅提升和数据的大量积累，机器学习逐渐成为人工智能的核心领域。特别是在 21 世纪初，深度学习的兴起，使得人工智能在图像识别、语音识别、自然语言处理等领域取得了突破性进展。如今，人工智能已经广泛应用于各个行业，如医疗、金融、交通等，对社会产生了深远的影响。"
            }
        }
    ],
    "created": 1695371246,
    "id": "chatcmpl-7O6x24y1G7V5c1234567890abcdef",
    "model": "gpt-3.5-turbo-0613",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 186,
        "prompt_tokens": 30,
        "total_tokens": 216
    }
}

5. 响应字段说明

字段名类型描述
choices数组包含生成的回复选项，通常只有一个元素，除非 n 参数设置大于 1
choices[].finish_reason字符串表示生成结束的原因，常见值有 stop（达到停止条件）、length（达到 max_tokens 限制）等
choices[].index整数回复在 choices 数组中的索引，通常为 0
choices[].message对象包含生成的回复消息，role 为 assistant，content 是具体的回复内容
created整数响应创建的时间戳（以秒为单位）
id字符串此次请求的唯一标识符
model字符串实际使用的模型名称
object字符串固定值 chat.completion，表示响应的对象类型
usage对象包含使用的令牌数量信息。completion_tokens 是生成回复使用的令牌数，prompt_tokens 是输入提示使用的令牌数，total_tokens 是两者之和
说明：本文基于 OpenAI Chat Completions API 通用规范编写。模型名称（如 gpt-3.5-turbo）及具体参数细节可能随平台更新而变化，请以官方最新文档为准。