OpenAI API 协议学习

OpenAI API 协议是 OpenAI 公司定义的一套与大语言模型交互的 HTTP API 接口规范。由于其先发优势和广泛的应用场景，这套协议已经成为事实上的行业标准。

API 路径格式

https://域名地址/v1/chat/completions

认证方式

所有请求都需要在 HTTP 请求头中携带 API Key：

Authorization: Bearer <your-api-key>

输入参数

参数名称	是否必填	数据类型	默认值	取值范围	作用	参数说明
model	✅ 必填	String	-	-	指定模型	确定使用哪一个具体的大模型，如 gpt-4、qwen-plus、deepseek-chat
messages	✅ 必填	Array	-	-	消息列表	传递给模型的对话历史或指令，包含 role 和 content
temperature	❌ 选填	Float	1.0	0.0 - 2.0	温度系数	控制输出随机性，低值稳定，高值创意
top_p	❌ 选填	Float	1.0	0.0 - 1.0	核采样	与 temperature 类似但算法不同，建议只调其一
max_tokens	❌ 选填	Integer	模型最大	-	最大输出长度	限定单次响应最大 Token 数
n	❌ 选填	Integer	1	1-N	生成次数	为同一 Prompt 生成 n 个不同回应
stream	❌ 选填	Boolean	false	true/false	流式输出	是否流式返回 Token
stop	❌ 选填	String/Array	null	-	停止标记	遇到指定字符串立即停止生成
presence_penalty	❌ 选填	Float	0	-2.0 - 2.0	出现惩罚	正值鼓励新话题，负值减少新话题
frequency_penalty	❌ 选填	Float	0	-2.0 - 2.0	频率惩罚	正值减少重复，负值增加连贯
seed	❌ 选填	Integer	null	-	复现种子	提高结果可复现性（非 100% 保证）
tools	❌ 选填	Array	null	-	工具定义	定义可调用的外部工具/函数
tool_choice	❌ 选填	String/Object	auto	-	工具选择	控制工具调用行为
response_format	❌ 选填	Object	null	-	响应格式	指定输出格式如 JSON
user	❌ 选填	String	null	-	用户标识	用于追踪和识别终端用户

核心参数详解

1. messages（消息列表）

这是最重要的参数，定义了与模型的完整对话上下文。messages 是一个数组，每个元素都是一个消息对象，包含 role（角色）和 content（内容）两个核心字段。

role 字段：用来标识一段消息是谁说的、以及它在对话中的作用。最常见的三个角色是 system、user、assistant。

{
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "你好！"},
    {"role": "assistant", "content": "你好！有什么可以帮助你的吗？"},
    {"role": "user", "content": "请介绍一下你自己。"}
  ]
}

角色类型详细说明：

角色	作用	使用场景	示例
system	设定模型的行为、角色和约束	放在 messages 第一位，定义 AI 的"人设"和回答风格	"你是一个专业的Python编程助手，回答时请给出代码示例。"
user	用户的输入或问题	每次用户提问时添加到 messages 末尾	"请帮我写一个快速排序算法。"
assistant	模型的历史回复	多轮对话时保存之前的 AI 回复，保持上下文连贯	"好的，这是快速排序的Python实现..."
tool	工具调用的返回结果	⚠️ 仅用于 Function Calling，必须紧跟在包含 tool_calls 的 assistant 消息之后	{"role": "tool", "tool_call_id": "xxx", "content": "北京今天晴，25℃"}

2. temperature（温度系数）

这是控制输出多样性的关键参数：

温度值	适用场景	特点
0.1 - 0.3	代码生成、事实问答、法律文本	高确定性、可预测
0.5 - 0.7	通用对话、翻译、摘要	平衡创意与准确
0.8 - 1.0	创意写作、头脑风暴、营销文案	高创意、多样性
> 1.0	极端创意场景	输出可能不可预测

建议：通常默认 0.7 即可，需要更稳定输出可设 0.3。

3. stream（流式输出）

这个参数对用户体验至关重要：

值	行为	适用场景
false	等待完整响应后一次性返回	批量处理、后台任务
true	逐 Token 流式返回	实时对话、提升用户体验

4. tools / tool_choice（工具调用）

这是 AI Agent 开发的核心参数，用于 Function Calling：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

tool_choice 选项：

• auto：模型自动决定是否调用工具（默认）
• none：不调用任何工具
• required：必须调用工具
• {"type": "function", "function": {"name": "xxx"}}：强制调用指定工具

输出参数详解

非流式输出结构

当 stream: false 时，API 会返回完整的 JSON 响应：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699000000,
  "model": "qwen-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个AI助手...",
        "tool_calls": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 50,
    "total_tokens": 70
  }
}

非流式输出参数表格

参数名称	数据类型	作用	参数说明
id	String	唯一标识符	本次 API 请求的唯一 ID
object	String	响应对象类型	固定为 chat.completion
model	String	模型名称	实际使用的模型名称
created	Integer	时间戳	API 响应创建的 Unix 时间戳
choices	Array	输出列表	包含模型生成的所有回复选项
choices[i].index	Integer	选项索引	从 0 开始的索引
choices[i].message	Object	消息内容	包含完整的回复信息
choices[i].message.role	String	角色	固定为 assistant
choices[i].message.content	String	生成文本	模型生成的全部文本内容
choices[i].message.tool_calls	Array	工具调用	AI Agent 核心：包含要调用的函数名和参数
choices[i].finish_reason	String	停止原因	stop（正常结束）、length（达到 max_tokens）、tool_calls（调用工具）
usage	Object	Token 统计	计费的核心依据
usage.prompt_tokens	Integer	输入 Token	输入消息消耗的 Token 数
usage.completion_tokens	Integer	输出 Token	模型输出消耗的 Token 数
usage.total_tokens	Integer	总 Token	总消耗 Token 数

流式输出结构

当 stream: true 时，API 会通过 SSE (Server-Sent Events) 流式返回数据块：

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699000000,"model":"qwen-plus","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699000000,"model":"qwen-plus","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699000000,"model":"qwen-plus","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699000000,"model":"qwen-plus","choices":[{"index":0,"delta":{"content":"！"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699000000,"model":"qwen-plus","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":20,"completion_tokens":3,"total_tokens":23}}

data: [DONE]

流式输出参数表格

参数名称	数据类型	作用	参数说明
id	String	唯一标识符	每个 chunk 中相同，标识同一次请求
object	String	响应对象类型	固定为 chat.completion.chunk
model	String	模型名称	实际使用的模型名称
created	Integer	时间戳	API 响应创建的 Unix 时间戳
choices	Array	分块输出列表	包含本次增量内容
choices[i].index	Integer	选项索引	从 0 开始的索引
choices[i].delta	Object	增量内容	本次数据块新增的内容
choices[i].delta.role	String	角色	仅在第一个 chunk 出现
choices[i].delta.content	String	增量文本	本次新增的极小部分文本，需拼接
choices[i].delta.tool_calls	Array	工具调用增量	流式工具调用，增量式返回
choices[i].finish_reason	String	停止原因	仅在最后一个 chunk 返回
usage	Object	Token 统计	通常在最后一个 chunk 返回

finish_reason 完整说明

值	含义	处理建议
stop	正常完成	输出完整，可直接使用
length	达到 max_tokens 限制	输出被截断，可能需要继续
tool_calls	模型请求调用工具	AI Agent 核心，需要执行工具并返回结果
content_filter	内容被安全过滤	输入或输出触发了安全策略
function_call	旧版函数调用（已废弃）	使用 tool_calls 替代

Anthropic Claude 的独立体系

值得注意的是，Anthropic 的 Claude 系列模型采用了自成一体的 API 协议，与 OpenAI 协议存在差异：

对比项	OpenAI API	Anthropic API
端点	/v1/chat/completions	/v1/messages
消息格式	messages 数组	messages + system 分离
系统提示	放在 messages 中	单独的 system 参数
流式字段	choices[0].delta.content	delta.text
工具调用	tool_calls	content 中的 tool_use 块

Anthropic API 示例：

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "你是一个有帮助的AI助手。",
  "messages": [
    {"role": "user", "content": "你好！"}
  ]
}

兼容方案：

大多数中转站（如 New API）会自动转换协议，让你可以用 OpenAI 协议调用 Claude。但如果你直接调用 Anthropic 官方 API，需要遵循其原生协议。

参考链接：https://juejin.cn/post/7624184992536952867#heading-34