OpenAI API 协议学习

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

API 路径格式

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

认证方式

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

Authorization: Bearer <your-api-key>

输入参数

核心参数详解

1. messages（消息列表）

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

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

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

角色类型详细说明：

2. temperature（温度系数）

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

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

3. stream（流式输出）

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

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 } }

非流式输出参数表格

流式输出结构

当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]

流式输出参数表格

finish_reason 完整说明

Anthropic Claude 的独立体系

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

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