OpenAI API 接口协议完全指南
作为配套《ChatGPT提示工程》学习笔记的技术文档，本文详细解析课程中用到的所有OpenAI API接口，帮助开发者深入理解底层调用机制。
📚 目录
- 1. API概述
- 2. 认证机制
- 3. Chat Completions API（核心接口）
- 4. 消息角色系统
- 5. 关键参数详解
- 6. 响应格式
- 7. 流式响应
- 8. 错误处理
- 9. 速率限制与配额
- 10. 成本计算
- 11. 最佳实践
- 12. 国内替代方案
1. API概述
1.1 课程中使用的核心API
在《ChatGPT Prompt Engineering for Developers》课程中，唯一使用的API是：
Chat Completions API
端点：https://api.openai.com/v1/chat/completions
方法：POST
用途：对话生成、文本处理、任务执行
1.2 API版本
当前稳定版本：v1
课程使用模型：gpt-3.5-turbo, gpt-4
官方文档：https://platform.openai.com/docs/api-reference
1.3 API的演变历史
2020年 - GPT-3 Completions API
└─ 单次文本补全，无对话上下文
2022年 - Chat Completions API (课程使用)
└─ 支持多轮对话，消息角色系统
2023年 - Function Calling
└─ 支持工具调用
2024年 - Assistants API
└─ 完整的AI助手框架
💡 课程聚焦：课程中所有示例都基于 Chat Completions API，这是最核心、最常用的接口。
2. 认证机制
2.1 API Key获取
# 环境变量方式（推荐）
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv('OPENAI_API_KEY') # 从.env文件加载
.env 文件格式：
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
2.2 认证方式
HTTP请求头：
Authorization: Bearer sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
完整cURL示例：
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
2.3 Python SDK封装
import openai
# 方式1：全局设置（旧版SDK）
openai.api_key = "sk-proj-xxxx"
# 方式2：客户端实例（新版SDK v1.0+）
from openai import OpenAI
client = OpenAI(api_key="sk-proj-xxxx")
3. Chat Completions API（核心接口）
3.1 基础调用结构
这是课程中所有示例的基础：
import openai
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo", # 必需：模型名称
messages=[ # 必需：消息列表
{"role": "user", "content": "Hello!"}
],
temperature=0, # 可选：随机性控制
max_tokens=100, # 可选：最大输出长度
top_p=1, # 可选：核采样
frequency_penalty=0, # 可选：频率惩罚
presence_penalty=0, # 可选：存在惩罚
stop=None, # 可选：停止序列
n=1, # 可选：返回结果数量
stream=False # 可选：是否流式返回
)
# 提取回复
answer = response.choices[0].message.content
3.2 接口协议详解
请求体（Request Body）
{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "What is the capital of France?"
}
],
"temperature": 0.7,
"max_tokens": 150,
"top_p": 1,
"frequency_penalty": 0,
"presence_penalty": 0,
"stop": null,
"n": 1,
"stream": false,
"logit_bias": null,
"user": "user-12345"
}
字段说明表
| 字段 | 类型 | 必需 | 说明 | 课程使用频率 |
|---|---|---|---|---|
model | string | ✅ | 模型ID | ⭐⭐⭐⭐⭐ |
messages | array | ✅ | 对话消息列表 | ⭐⭐⭐⭐⭐ |
temperature | number | ❌ | 0-2，控制随机性 | ⭐⭐⭐⭐⭐ |
max_tokens | integer | ❌ | 最大生成token数 | ⭐⭐⭐ |
top_p | number | ❌ | 0-1，核采样 | ⭐ |
n | integer | ❌ | 返回结果数量 | ⭐ |
stream | boolean | ❌ | 流式输出 | ⭐⭐ |
stop | string/array | ❌ | 停止序列 | ⭐⭐ |
frequency_penalty | number | ❌ | -2到2，降低重复 | ⭐ |
presence_penalty | number | ❌ | -2到2，鼓励新话题 | ⭐ |
logit_bias | object | ❌ | Token倾向调整 | ❌ |
user | string | ❌ | 用户标识 | ⭐⭐ |
4. 消息角色系统
4.1 三种角色类型
这是课程中最核心的概念：
messages = [
# 1. system - 系统消息（设定AI行为）
{
"role": "system",
"content": "You are a professional customer service representative."
},
# 2. user - 用户消息（用户输入）
{
"role": "user",
"content": "How can I return a product?"
},
# 3. assistant - 助手消息（AI回复/历史记录）
{
"role": "assistant",
"content": "You can return products within 30 days..."
}
]
4.2 角色详解
System Role（系统角色）
# 作用：设定AI的身份、能力、行为规范
{
"role": "system",
"content": """
你是一位专业的Python编程导师。
职责：
- 解答编程问题
- 提供代码示例
- 解释技术概念
要求：
- 使用中文
- 代码带注释
- 循序渐进
"""
}
课程中的实际使用：
# 示例1：客服机器人
system_message = {
"role": "system",
"content": "你是一名电商客服，礼貌专业，使用'您'称呼客户。"
}
# 示例2：订餐机器人
system_message = {
"role": "system",
"content": """
你是OrderBot，为披萨店收集订单。
流程：问候 → 收集订单 → 确认配送 → 总结
"""
}
# 示例3：文本分析器
system_message = {
"role": "system",
"content": "你是情感分析专家，只返回：正面、负面或中性。"
}
User Role（用户角色）
# 作用：表示用户输入
{
"role": "user",
"content": "帮我总结这段文本：[文本内容]"
}
课程中的使用场景：
# 场景1：单次任务
user_message = {
"role": "user",
"content": f"总结以下评论：```{review_text}```"
}
# 场景2：多轮对话
user_messages = [
{"role": "user", "content": "我想买一个披萨"},
{"role": "assistant", "content": "好的，请问要什么口味？"},
{"role": "user", "content": "意式辣香肠"} # 新的用户输入
]
Assistant Role（助手角色）
# 作用1：对话历史记录
# 作用2：Few-shot示例
# 用途1：维护对话上下文
conversation = [
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "您好！有什么可以帮您？"}, # 之前的回复
{"role": "user", "content": "我上一句说了什么？"}
]
# 用途2：提供示例（Few-shot）
messages = [
{"role": "system", "content": "你是一位诗人，用古诗风格回答"},
{"role": "user", "content": "描述春天"},
{"role": "assistant", "content": "春风拂面柳依依"}, # 示例
{"role": "user", "content": "描述夏天"} # 实际问题
]
4.3 消息顺序规则
# ✅ 正确的消息顺序
messages = [
{"role": "system", "content": "..."}, # 1. system（可选）
{"role": "user", "content": "..."}, # 2. user
{"role": "assistant", "content": "..."}, # 3. assistant
{"role": "user", "content": "..."}, # 4. user
{"role": "assistant", "content": "..."}, # 5. assistant
{"role": "user", "content": "..."} # 6. user（最后必须是user）
]
# ❌ 错误：最后不是user
messages = [
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "您好"} # ❌ 最后是assistant
]
# ❌ 错误：连续两个user
messages = [
{"role": "user", "content": "第一个问题"},
{"role": "user", "content": "第二个问题"} # ❌ 应该有assistant在中间
]
4.4 课程中的典型模式
模式1：单次任务（无上下文）
# 用于：摘要、分类、提取
def get_completion(prompt):
messages = [
{"role": "user", "content": prompt}
]
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=messages,
temperature=0
)
return response.choices[0].message["content"]
模式2：带系统提示的任务
# 用于：特定角色的任务
def get_completion_with_role(prompt, system_message):
messages = [
{"role": "system", "content": system_message},
{"role": "user", "content": prompt}
]
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=messages,
temperature=0
)
return response.choices[0].message["content"]
模式3：多轮对话
# 用于：聊天机器人
class ChatBot:
def __init__(self, system_message):
self.messages = [
{"role": "system", "content": system_message}
]
def chat(self, user_input):
# 添加用户消息
self.messages.append({
"role": "user",
"content": user_input
})
# 调用API
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=self.messages,
temperature=0.5
)
# 提取回复
assistant_message = response.choices[0].message["content"]
# 添加到历史
self.messages.append({
"role": "assistant",
"content": assistant_message
})
return assistant_message
5. 关键参数详解
5.1 Temperature（温度）
💡 课程中最重要的参数之一
temperature = 0 # 最确定（用于分类、提取）
temperature = 0.7 # 平衡（用于对话）
temperature = 1.0 # 最随机（用于创作）
工作原理
Temperature控制输出的随机性：
低温度（0-0.3）：
├─ AI选择概率最高的词
├─ 输出确定、一致
└─ 适合：分类、信息提取、客服
中温度（0.4-0.7）：
├─ AI在高概率词中随机选择
├─ 输出平衡、自然
└─ 适合：对话、问答
高温度（0.8-2.0）：
├─ AI考虑更多低概率词
├─ 输出多样、创意
└─ 适合：写作、头脑风暴
课程示例
# 示例：温度对比
prompt = "写一个关于AI的标语"
# Temperature = 0（运行3次，结果相同）
responses_temp0 = []
for _ in range(3):
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}],
temperature=0
)
responses_temp0.append(response.choices[0].message["content"])
# 输出：
# ["AI赋能未来", "AI赋能未来", "AI赋能未来"]
# Temperature = 0.9（运行3次，结果不同）
responses_temp09 = []
for _ in range(3):
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}],
temperature=0.9
)
responses_temp09.append(response.choices[0].message["content"])
# 输出：
# ["智能引领未来", "AI点亮生活", "科技改变世界"]
5.2 Max Tokens（最大令牌数）
max_tokens = 100 # 最多生成100个token
Token计算
1 token ≈ 4个字符（英文）
1 token ≈ 1.5个汉字（中文）
示例：
"Hello, world!" ≈ 4 tokens
"你好，世界！" ≈ 5 tokens
课程中的使用
# 示例1：限制摘要长度
def summarize(text, max_words=30):
prompt = f"用最多{max_words}个词总结：```{text}```"
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}],
temperature=0,
max_tokens=100 # 确保不超过字数限制
)
return response.choices[0].message["content"]
# 示例2：防止超长输出
def classify_sentiment(text):
prompt = f"情感分析（只回答：正面/负面/中性）：{text}"
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}],
temperature=0,
max_tokens=10 # 只需要一个词，限制token
)
return response.choices[0].message["content"]
5.3 其他参数
top_p（核采样）
top_p = 0.1 # 只考虑累计概率前10%的词
top_p = 1 # 考虑所有词（默认）
⚠️ 注意：不要同时使用temperature和top_p，选择其一。
n（返回数量）
# 生成多个结果
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "写一个标语"}],
n=3 # 返回3个不同的结果
)
for choice in response.choices:
print(choice.message["content"])
stop（停止序列）
# 遇到特定字符串时停止生成
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "列举水果："}],
stop=["\n\n", "结束"] # 遇到两个换行或"结束"时停止
)
6. 响应格式
6.1 标准响应结构
{
"id": "chatcmpl-8xYzABC123xyz",
"object": "chat.completion",
"created": 1704096000,
"model": "gpt-3.5-turbo-0613",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 9,
"total_tokens": 19
}
}
6.2 响应字段详解
| 字段路径 | 类型 | 说明 |
|---|---|---|
id | string | 唯一请求ID |
object | string | 固定值："chat.completion" |
created | integer | Unix时间戳 |
model | string | 实际使用的模型 |
choices | array | 返回结果数组 |
choices[0].index | integer | 结果索引 |
choices[0].message | object | AI回复消息 |
choices[0].message.role | string | 固定值："assistant" |
choices[0].message.content | string | AI的回复内容（最重要） |
choices[0].finish_reason | string | 停止原因（见下表） |
usage | object | Token使用统计 |
usage.prompt_tokens | integer | 输入token数 |
usage.completion_tokens | integer | 输出token数 |
usage.total_tokens | integer | 总token数（计费依据） |
6.3 finish_reason详解
| 值 | 含义 | 处理方式 |
|---|---|---|
stop | 正常结束 | ✅ 正常使用 |
length | 达到max_tokens限制 | ⚠️ 可能未完成，增加max_tokens |
content_filter | 内容被过滤 | ❌ 修改输入，避免违规内容 |
null | 正在生成中（流式） | 🔄 继续接收 |
6.4 课程中的提取模式
# 模式1：提取回复内容
response = openai.ChatCompletion.create(...)
answer = response.choices[0].message["content"]
# 模式2：提取并检查
response = openai.ChatCompletion.create(...)
choice = response.choices[0]
if choice.finish_reason == "stop":
answer = choice.message["content"]
elif choice.finish_reason == "length":
print("⚠️ 回复被截断，请增加max_tokens")
answer = choice.message["content"]
# 模式3：提取token使用量
response = openai.ChatCompletion.create(...)
print(f"输入tokens: {response.usage.prompt_tokens}")
print(f"输出tokens: {response.usage.completion_tokens}")
print(f"总计tokens: {response.usage.total_tokens}")
7. 流式响应
7.1 为什么需要流式响应
普通模式：
用户输入 → 等待30秒 → 完整回复
流式模式：
用户输入 → 逐字显示（类似ChatGPT网页版）
7.2 流式调用方式
# 启用流式响应
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "写一首诗"}],
stream=True # 关键参数
)
# 逐块接收
for chunk in response:
if chunk.choices[0].delta.get("content"):
content = chunk.choices[0].delta.content
print(content, end="", flush=True)
7.3 流式响应格式
// 第一块
{
"id": "chatcmpl-xxx",
"object": "chat.completion.chunk",
"created": 1704096000,
"model": "gpt-3.5-turbo-0613",
"choices": [
{
"index": 0,
"delta": {
"role": "assistant",
"content": "春"
},
"finish_reason": null
}
]
}
// 第二块
{
"choices": [
{
"delta": {
"content": "风"
},
"finish_reason": null
}
]
}
// 最后一块
{
"choices": [
{
"delta": {},
"finish_reason": "stop"
}
]
}
7.4 完整流式示例
def stream_chat(prompt):
"""流式聊天，实时显示"""
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}],
stream=True,
temperature=0.7
)
full_response = ""
for chunk in response:
# 提取内容
if chunk.choices[0].delta.get("content"):
content = chunk.choices[0].delta.content
full_response += content
print(content, end="", flush=True)
# 检查是否结束
if chunk.choices[0].finish_reason == "stop":
break
print() # 换行
return full_response
# 使用
result = stream_chat("给我讲一个故事")
8. 错误处理
8.1 常见错误码
| 状态码 | 错误类型 | 含义 | 解决方案 |
|---|---|---|---|
| 401 | invalid_api_key | API Key无效 | 检查密钥是否正确 |
| 429 | rate_limit_exceeded | 超过速率限制 | 降低请求频率或升级套餐 |
| 429 | insufficient_quota | 配额不足 | 充值或等待配额刷新 |
| 400 | invalid_request_error | 请求参数错误 | 检查请求格式 |
| 500 | api_error | 服务器错误 | 重试或联系支持 |
| 503 | service_unavailable | 服务不可用 | 稍后重试 |
8.2 错误响应格式
{
"error": {
"message": "You exceeded your current quota, please check your plan and billing details.",
"type": "insufficient_quota",
"param": null,
"code": "insufficient_quota"
}
}
8.3 课程推荐的错误处理
import openai
import time
def get_completion_with_retry(prompt, max_retries=3):
"""带重试机制的API调用"""
for attempt in range(max_retries):
try:
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": prompt}],
temperature=0
)
return response.choices[0].message["content"]
except openai.error.RateLimitError:
# 速率限制，等待后重试
if attempt < max_retries - 1:
wait_time = (attempt + 1) * 2 # 指数退避
print(f"速率限制，等待{wait_time}秒后重试...")
time.sleep(wait_time)
else:
raise
except openai.error.APIError as e:
# API错误，短暂等待后重试
if attempt < max_retries - 1:
print(f"API错误：{e}，1秒后重试...")
time.sleep(1)
else:
raise
except openai.error.InvalidRequestError as e:
# 请求参数错误，不重试
print(f"请求错误：{e}")
raise
except openai.error.AuthenticationError as e:
# 认证错误，不重试
print(f"认证错误：请检查API Key")
raise
return None
# 使用
try:
result = get_completion_with_retry("Hello!")
print(result)
except Exception as e:
print(f"最终失败：{e}")
9. 速率限制与配额
9.1 速率限制规则
| 限制类型 | 免费用户 | 付费用户（Tier 1） | 付费用户（Tier 5） |
|---|---|---|---|
| RPM (每分钟请求数) | 3 | 3,500 | 10,000 |
| TPM (每分钟tokens) | 40,000 | 90,000 | 10,000,000 |
| RPD (每天请求数) | 200 | 10,000 | 无限制 |
💡 RPM = Requests Per Minute, TPM = Tokens Per Minute
9.2 检查当前限制
# 响应头中包含限制信息
import openai
response = openai.ChatCompletion.create(...)
# 查看响应头（需要访问底层HTTP响应）
headers = response._previous_response.headers
print(f"每分钟请求限制: {headers.get('x-ratelimit-limit-requests')}")
print(f"剩余请求: {headers.get('x-ratelimit-remaining-requests')}")
print(f"重置时间: {headers.get('x-ratelimit-reset-requests')}")
9.3 应对速率限制
import time
from collections import deque
class RateLimiter:
"""简单的速率限制器"""
def __init__(self, max_requests_per_minute=60):
self.max_requests = max_requests_per_minute
self.requests = deque()
def wait_if_needed(self):
"""如果需要，等待直到可以发送请求"""
now = time.time()
# 移除1分钟前的请
