GPT-5 API:开发者完全指南 (2026)
集成 OpenAI 的 GPT-5 到你的应用程序中所需的一切信息
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
GPT-5 API:开发者完全指南 (2026)
OpenAI 的 GPT-5 代表了大语言模型能力的重大飞跃。与前代模型相比,它提供了更强的推理能力、更大的上下文窗口、原生多模态处理以及更出色的指令遵循能力。本指南涵盖了开发者将 GPT-5 API 集成到应用中所需了解的所有信息,从身份验证、基础用法到高级功能和成本优化。
GPT-5 模型概览
在深入了解 API 之前,以下是 GPT-5 与前代 OpenAI 模型的主要区别:
| 特性 | GPT-5 | GPT-4o | GPT-4 Turbo |
|---|---|---|---|
| 上下文窗口 | 256K tokens | 128K tokens | 128K tokens |
| 最大输出 tokens | 32,768 | 16,384 | 4,096 |
| 多模态输入 | 文本、图像、音频、视频 | 文本、图像、音频 | 文本、图像 |
| 推理能力 | 内置高级思维链 (Chain-of-thought) | 标准 | 标准 |
| 知识截止日期 | 2025 年 10 月 | 2023 年 10 月 | 2023 年 4 月 |
| 输入成本 (每 1M tokens) | $5.00 | $2.50 | $10.00 |
| 输出成本 (每 1M tokens) | $15.00 | $10.00 | $30.00 |
| 缓存输入成本 | $2.50 | $1.25 | 不适用 |
价格为近似值并可能发生变化。请查看 OpenAI 价格页面获取当前费率。
快速上手
第 1 步:获取 API Key
- 访问 platform.openai.com。
- 登录或创建账户。
- 导航至仪表板中的 API Keys。
- 点击 Create new secret key 并复制该密钥。
请妥善保存。创建后,您将无法再次查看该密钥。
第 2 步:安装 SDK
Python:
pip install openai
Node.js:
npm install openai
验证安装:
python -c "import openai; print(openai.__version__)"
您需要 1.60 或更高版本以获得 full GPT-5 支持。
第 3 步:设置 API Key
环境变量(推荐):
export OPENAI_API_KEY="sk-proj-your-key-here"
在代码中(不推荐用于生产环境):
from openai import OpenAI
client = OpenAI(api_key="sk-proj-your-key-here")
基础聊天补全 (Chat Completion)
GPT-5 的核心端点与您可能已经熟悉的 Chat Completions API 相同。
Python 示例
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-5",
messages=[
{"role": "system", "content": "你是一位资深软件工程师。请回答得简洁且精准。"},
{"role": "user", "content": "写一个 Python 函数,在已排序的列表中实现二分查找。"}
],
temperature=0.3,
max_tokens=2048,
)
print(response.choices[0].message.content)
Node.js 示例
import OpenAI from "openai";
const openai = new OpenAI();
const response = await openai.chat.completions.create({
model: "gpt-5",
messages: [
{ role: "system", content: "你是一位资深软件工程师。请回答得简洁且精准。" },
{ role: "user", content: "写一个 TypeScript 函数,在已排序的数组中实现二分查找。" },
],
temperature: 0.3,
max_tokens: 2048,
});
console.log(response.choices[0].message.content);
cURL 示例
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5",
"messages": [
{"role": "system", "content": "你是一个得力的助手。"},
{"role": "user", "content": "用三句话解释量子计算。"}
],
"temperature": 0.7,
"max_tokens": 512
}'
流式响应 (Streaming)
对于对话界面中的实时输出或长文本生成,请使用流式传输:
from openai import OpenAI
client = OpenAI()
stream = client.chat.completions.create(
model="gpt-5",
messages=[
{"role": "user", "content": "详细解释 Go 语言中垃圾回收的工作机制。"}
],
stream=True,
)
for chunk in stream:
content = chunk.choices[0].delta.content
if content:
print(content, end="", flush=True)
多模态输入:图像
GPT-5 支持将图像作为对话的一部分。这适用于通过截图进行代码评审、架构图分析以及视觉问答。
response = client.chat.completions.create(
model="gpt-5",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "这张架构图显示了什么?列出所有服务及其连接关系。"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/architecture-diagram.png",
"detail": "high"
}
}
]
}
],
max_tokens=4096,
)
detail 参数接受 low、high 或 auto。对于简单的图像,使用 low 可以减少 token 消耗。
使用 JSON 模式生成结构化输出
GPT-5 支持保证格式的 JSON 输出,这对于构建可靠的 API 流水线至关重要。
from pydantic import BaseModel
class CodeReview(BaseModel):
issues: list[str]
severity: str
suggestion: str
confidence: float
response = client.beta.chat.completions.parse(
model="gpt-5",
messages=[
{"role": "system", "content": "你是一位代码评审员。分析代码并返回结构化反馈。"},
{"role": "user", "content": "评审这段代码: def add(a, b): return a + b + 1"}
],
response_format=CodeReview,
)
review = response.choices[0].message.parsed
print(f"缺陷: {review.issues}")
print(f"严重程度: {review.severity}")
函数调用 (Function Calling)
GPT-5 改进了函数调用功能,具有更高的准确性,并支持并行工具调用。
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定位置的当前天气",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "城市和省份/州,例如:San Francisco, CA"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["location"]
}
}
},
{
"type": "function",
"function": {
"name": "search_flights",
"description": "搜索可用航班",
"parameters": {
"type": "object",
"properties": {
"origin": {"type": "string"},
"destination": {"type": "string"},
"date": {"type": "string", "description": "YYYY-MM-DD 格式"}
},
"required": ["origin", "destination", "date"]
}
}
}
]
response = client.chat.completions.create(
model="gpt-5",
messages=[
{"role": "user", "content": "东京天气如何?并帮我查找 2026 年 3 月 15 日从纽约飞往东京的航班。"}
],
tools=tools,
tool_choice="auto",
)
# GPT-5 可以并行调用多个工具
for tool_call in response.choices[0].message.tool_calls:
print(f"函数名: {tool_call.function.name}")
print(f"参数: {tool_call.function.arguments}")
GPT-5 模型变体
OpenAI 针对不同的使用场景提供了几种 GPT-5 变体:
| 模型 | 最适合 | 速度 | 成本 |
|---|---|---|---|
gpt-5 |
通用、复杂任务 | 中等 | $5 / $15 每 1M tokens |
gpt-5-mini |
快速响应、简单任务 | 极快 | $0.50 / $1.50 每 1M tokens |
gpt-5-turbo |
速度与能力的平衡 | 快 | $2.00 / $8.00 每 1M tokens |
请选择能够胜任您任务的最小模型。对于分类、提取和简单问答,使用 gpt-5-mini。对于复杂推理、代码生成和多步分析,请使用全量版 gpt-5。
成本优化技巧
1. 使用 Prompt 缓存 (Prompt Caching)
GPT-5 支持自动 Prompt 缓存。消息中重复的前缀将被缓存,并按输入费率的一半计费。
# 下面的系统提示词在第一次请求后将被缓存
system_prompt = "你是一位医疗编码助手。你负责根据临床描述对 ICD-10 代码进行分类。请始终返回代码、描述和置信水平。"
# 第一次请求:全额输入成本
# 使用相同系统提示词的后续请求:缓存输入成本(获得 50% 折扣)
2. 设置合理的 max_tokens
不要将 max_tokens 设置得超过需求。较低的值意味着模型会更早停止,从而节省输出 token。
3. 对于确定性任务使用 Temperature 0
对于分类、提取以及希望得到一致结果的代码生成任务:
response = client.chat.completions.create(
model="gpt-5",
messages=[...],
temperature=0, # 确定性输出
)
4. 高吞吐任务使用 Batch API
对于对时间不敏感的工作负载,使用 Batch API 可节省 50% 的成本:
# 创建包含多个请求的 batch 文件
# 通过 Batch API 端点提交
# 结果将在 24 小时内返回,成本仅为一半
错误处理
对于生产级应用,稳健的错误处理至关重要:
from openai import OpenAI, APIError, RateLimitError, APITimeoutError
import time
client = OpenAI()
def call_gpt5(messages, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-5",
messages=messages,
timeout=60,
)
return response.choices[0].message.content
except RateLimitError:
wait_time = 2 ** attempt
print(f"达到频率限制。将在 {wait_time} 秒后重试...")
time.sleep(wait_time)
except APITimeoutError:
print(f"请求超时。尝试次数 {attempt + 1}/{max_retries}")
time.sleep(1)
except APIError as e:
print(f"API 错误: {e}")
raise
raise Exception("超过最大重试次数")
频率限制 (Rate Limits)
GPT-5 API 频率限制取决于您的使用层级 (Usage Tier):
| 层级 | RPM (每分钟请求数) | TPM (每分钟 Token 数) | 每日限制 |
|---|---|---|---|
| Free | 3 | 40,000 | 200 请求 |
| Tier 1 ($5 已付) | 60 | 200,000 | 无每日限制 |
| Tier 2 ($50 已付) | 200 | 1,000,000 | 无每日限制 |
| Tier 3 ($100 已付) | 500 | 2,000,000 | 无每日限制 |
| Tier 4 ($250 已付) | 1,000 | 5,000,000 | 无每日限制 |
| Tier 5 ($1,000 已付) | 5,000 | 20,000,000 | 无每日限制 |
RPM = Requests per minute. TPM = Tokens per minute.
从 GPT-4o 迁移到 GPT-5
如果您正在从 GPT-4o 升级,迁移过程非常简单:
- 将
model参数从gpt-4o更改为gpt-5。 - 检查您的
max_tokens设置。GPT-5 支持高达 32,768 个输出 tokens。 - 测试您的提示词。GPT-5 遵循指令更加精确,这可能意味着原本依赖 GPT-4o 较松散解读的提示词可能需要调整。
- 更新您的成本估算。GPT-5 的定价为每百万 token $5/$15,而 GPT-4o 为 $2.50/$10。
- 充分利用 256K 的超大上下文窗口来处理以前需要分段的任务。
结论
GPT-5 API 在保持与现有 OpenAI API 格式向后兼容的同时,在推理、多模态处理和指令遵循方面带来了显著改进。高效使用它的关键在于根据使用场景选择正确的模型变体、实施完善的错误处理,并通过缓存和合理的 token 限制来优化成本。
如果您正在构建需要 AI 生成媒体(图像、视频、数字人或音频)的应用,请查看 Hypereal AI。Hypereal 为生成式媒体模型提供统一的 API 和按需付费定价,让您可以轻松地为任何项目添加视觉和音频 AI 能力。
