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 能力。