JICHANG AIR · 2026机场推荐 | 梯子推荐与机场梯子评测

外观

调用 AI API 只需要三样配套的东西：API Key、Base URL 和模型名，三者必须来自同一服务商，并以该服务商的官方文档为准。结论先说：Key 放在环境变量或密钥管理工具里，不写进代码、不放进前端；优先用官方接口，第三方中转可能记录数据或替换模型；长回复用流式输出；出错先看状态码（401 查 Key，403 查权限与地区，429 区分限流与额度，5xx 退避重试，400 不要重试）；网页订阅不含 API 额度，两者分开计费。

本页适合第一次在程序里调用大模型的开发者和进阶用户。下面先给一张速查表，再讲 Key 管理、官方与第三方接口辨识、curl 与 Python SDK 示例、流式输出与超时、代理与证书、错误码与限流、计费核对；页面末尾的「官方资格入口」列出 OpenAI、Anthropic 与 Google 的支持地区页面。示例以三家官方接口为例，按 2026-10-07 的官方文档核对，模型名统一用占位符 MODEL_ID 表示。

核心结论 ​

核心结论

  • 三件套要配套：API Key、Base URL、模型名必须来自同一服务商，并以该服务商的官方文档为准。
  • Key 等同于密码：放在环境变量或密钥管理工具中，不写进代码、不提交到仓库、不放进前端、不发给他人。
  • 优先官方接口：第三方中转可能记录你的数据、替换模型或随时停服，生产环境慎用。
  • 长回复用流式：流式输出比单纯调大超时更可靠；官方 Python SDK 默认超时 10 分钟、自动重试 2 次。
  • 看懂错误码再处理：401 查 Key，403 查权限与地区，429 区分限流与额度，5xx 退避重试，400 不要重试。
  • 代理与证书用标准变量：HTTPS_PROXY、NO_PROXY、SSL_CERT_FILE 等，或在 SDK 中显式配置。
  • 订阅与 API 分开计费：网页订阅不含 API 额度，价格以各家 API 定价页为准，并设置消费上限。

AI API 速查表 ​

你要做的事怎么做本页章节
拿到 API KeyOpenAI 开发者平台、Claude Console、Google AI Studio「API Key、Base URL 和模型名称」
安全保存 Key环境变量或 .env（加入 .gitignore），不放前端「安全保存与管理 API Key」
发第一个请求先用 curl 发最小请求，再换官方 SDK「第一次调用：curl 与 Python SDK 示例」
长回复超时或中断改用流式输出，再调整超时与重试「请求、响应、流式输出和超时」
需要走代理或公司证书HTTPS_PROXY、NO_PROXY、SSL_CERT_FILE，或在 SDK 中显式配置「代理、证书与网络环境配置」
返回 401 / 403 / 429 / 5xx先看状态码含义，再决定是否重试「身份验证、限流和常见错误码」
核对价格与账单看各家 API 定价页和控制台账单，设置消费上限「网页订阅与 API 计费信息的分别核对」
确认所在地区能否调用各家官方支持地区页面「官方资格入口」

AI API 是怎么工作的 ​

AI API 是服务商提供的编程接口：你的程序通过 HTTPS 把一段输入（提示、对话历史、文件等）发送到服务器，服务器调用模型生成结果后以 JSON 返回。和在网页上聊天不同，API 不会替你保存对话，每一次请求都是独立的。

几个必须理解的概念 ​

概念一句话定义为什么重要
请求（request）程序发给接口的一次 HTTP 调用，包含认证头和 JSON 请求体格式错误会直接返回 400
响应（response）接口返回的 JSON，包含输出内容、停止原因和用量需要读取停止原因判断是否被截断
token模型处理文本的计量单位，一个汉字或一个英文单词可能对应一到多个 tokenAPI 按 token 计费，限流也常按 token 计算
上下文窗口单次请求中模型能处理的输入与输出 token 总量上限超出会报错，需要截断或总结历史
无状态服务器不记得上一次请求多轮对话需要你每次把历史消息一起发送
流式输出模型边生成边返回，而不是全部生成完再返回改善体验，减少长请求超时

一次调用的完整流程 ​

  1. 程序从环境变量读取 API Key。
  2. 拼出完整地址：Base URL + 接口路径（例如 /responses、/messages）。
  3. 在请求头中放入认证信息，在请求体中写明模型名和输入。
  4. 通过网络（可能经过代理）发送到服务商。
  5. 服务商校验 Key、权限、地区和额度，任一不通过就返回对应的错误码。
  6. 校验通过后模型生成结果，以普通 JSON 或流式事件返回。
  7. 程序读取输出、停止原因和用量，记录请求 ID 以便排查。

出错时，按这个流程倒推，就能快速定位是哪一环的问题：认证头错了是第 3 步，代理不通是第 4 步，额度不足是第 5 步。

API 适合做什么 ​

适合说明
批量处理文本摘要、分类、翻译、信息抽取，可写脚本一次处理大量数据
嵌入自己的产品在网站、App、内部系统中提供问答、写作辅助等功能
自动化流程与工单、邮件、文档系统对接，自动生成草稿供人审核
开发工具与代理编程代理、代码审查、测试生成等工具本身就是通过 API 调用模型

如果你只是想自己和模型聊天、偶尔处理几份文件，网页或应用订阅通常更省心；只有需要「让程序去调用」时，才需要 API。

API Key、Base URL 和模型名称 ​

API Key、Base URL 和模型名是调用任何 AI API 的三件套，三者必须来自同一服务商并相互匹配。

三个概念 ​

概念是什么类比
API Key调用接口的身份凭证，决定请求记在哪个账号上门禁卡
Base URL接口服务器地址，所有请求路径都拼接在它后面大楼地址
模型名（Model ID）请求体中的 model 字段，指定使用哪个模型要找的房间号

官方入口一览 ​

服务商创建 API Key 的地方常用 Base URL认证请求头常用环境变量
OpenAIOpenAI 开发者平台（platform.openai.com）https://api.openai.com/v1Authorization: Bearer <Key>OPENAI_API_KEY
Anthropic（Claude）Claude Console（platform.claude.com）https://api.anthropic.com/v1x-api-key: <Key>，并带 anthropic-versionANTHROPIC_API_KEY
Google GeminiGoogle AI Studio（aistudio.google.com）https://generativelanguage.googleapis.com/v1betax-goog-api-key: <Key>GEMINI_API_KEY

模型名以官方模型列表为准

各家模型更新很快，本站不列具体模型名。请到服务商文档的「Models」页面复制准确的模型 ID，也可以调用服务商提供的模型列表接口查询当前账号可用的模型。模型名拼写错误或账号无权使用该模型，通常会返回 400 或 404。

Base URL 的环境变量覆盖 ​

官方 Python SDK 支持用环境变量覆盖默认地址：OpenAI SDK 读取 OPENAI_BASE_URL，Anthropic SDK 读取 ANTHROPIC_BASE_URL。这在使用公司内部网关时有用，但也意味着：如果你的环境里残留了这些变量，请求可能被悄悄发到别的地址。调用结果异常时，先用 env | grep BASE_URL 检查一下。

安全保存与管理 API Key ​

API Key 一旦泄露，他人就能以你的账号调用接口并产生费用，所以它的保管标准应当与密码相同：只放在服务端的环境变量或密钥管理工具里。

bash
# 在当前终端会话中设置（示例值请替换为你自己的 Key）
export OPENAI_API_KEY="your-api-key-here"

# 推荐：写入项目的 .env 文件，并确保 .env 已加入 .gitignore
echo ".env" >> .gitignore

Python 项目可以用 python-dotenv 从 .env 加载变量，这也是 Anthropic 官方 SDK 文档建议的做法：

python
# pip install python-dotenv
from dotenv import load_dotenv

load_dotenv()  # 把 .env 中的变量加载到环境变量，SDK 会自动读取

管理原则 ​

  • 一个用途一个 Key：便于单独吊销和统计用量。
  • 不放在前端：网页或移动应用的代码可以被任何人提取，正确做法是由自己的后端保存 Key 并代为调用。
  • 不出现在日志和截图中：打印请求调试信息时注意遮盖认证头。
  • 定期轮换：吊销不再使用的 Key，降低长期泄露的风险。
  • 使用工作区 / 项目隔离：在控制台中按项目划分，并为每个项目设置消费上限。

多环境下的 Key 管理 ​

开发、测试和生产环境应使用不同的 Key，并分别设置消费上限：开发环境的 Key 权限和预算最小，即使不小心泄露损失也有限；生产环境的 Key 只保存在部署平台的密钥管理功能中，开发者本地不保存。团队成员离职或调岗时，及时吊销其使用过的 Key。CI 流水线中的 Key 通过平台提供的加密变量注入，不写在流水线配置文件里，也不在构建日志中打印。

怀疑泄露时的处理步骤 ​

  1. 立即在官方控制台吊销（删除）该 Key。
  2. 生成新 Key，更新到服务端环境变量或密钥管理工具。
  3. 查看控制台的用量页面，确认是否有异常调用。
  4. 如果 Key 曾被提交到 Git 仓库，仅删除文件不够，历史记录中仍然存在，应视为已泄露。
  5. 排查泄露途径（公开仓库、日志、聊天记录），避免再次发生。

地区限制

OpenAI、Anthropic、Google 的 API 都只在各自支持的国家和地区提供，从不受支持的地区访问可能直接返回 403 或类似错误。名单以各家官方页面为准。网络问题可参考 常见问题 与 AI 机场推荐，并请遵守所在地法律法规与服务条款。

官方 API 与第三方接口的来源辨识 ​

除官方 API 外，还有两类常见来源：大型云平台提供的托管服务（例如在 Amazon Bedrock、Google Cloud 上使用 Claude），以及各种第三方「中转 / 代理 / 聚合」接口；三者在数据安全和稳定性上差别很大。

来源特征风险
官方 API域名属于服务商本身，Key 在官方控制台创建最低，受官方服务条款与隐私政策约束
正规云平台通过云厂商账号开通，按云厂商规则计费较低，需了解云平台自己的配置与计费方式
第三方中转域名与服务商无关，Key 由第三方发放，常宣称「兼容」「低价」数据可能被记录、模型可能被替换、随时停服、可能违反服务条款

辨识清单 ​

  1. 看域名：Base URL 的域名是否属于服务商或其公布的云合作方。
  2. 看 Key 的来源：是否在官方控制台中创建、能否在官方控制台查看用量和吊销。
  3. 看文档：官方文档是否提到这个地址；第三方页面的「官方合作」说法不能作为依据。
  4. 看响应：官方响应头中通常带有可追踪的请求 ID（OpenAI 为 x-request-id，Anthropic 为 request-id），便于向官方支持反馈。
  5. 看价格：明显低于官方定价的服务，需要想清楚差价从哪里来。

如何选择接入方式 ​

你的情况建议的接入方式
个人学习、原型验证直接使用服务商官方 API，在官方控制台创建 Key
公司已有某个云平台的账号与合规流程通过该云平台的托管模型服务接入，账单与权限沿用公司现有体系
需要同时使用多家模型分别接入各家官方 API，在自己的代码中做一层统一封装；或使用该服务商官方提供的兼容端点
处理敏感数据或受监管业务官方 API 或正规云平台，并阅读其数据处理条款，必要时签署企业协议
只因为「便宜」或「不需要注册」而考虑第三方中转先评估数据泄露、模型被替换和违反服务条款的风险，生产环境不建议

示例场景：某个第三方接口宣称「完全兼容、价格低廉」，你按说明把 Base URL 换成它的地址后请求成功了。但这只能说明它实现了相同的接口格式，并不能证明背后真的是你指定的模型，也不能保证你的数据不会被保存。用上文的辨识清单逐项核对，凡是无法在官方控制台看到用量、无法拿到官方请求 ID 的接口，都不应用于处理真实业务数据。

不要把敏感数据交给来源不明的接口

请求中的全部内容（包括你的代码、文档和用户数据）都会经过接口提供方的服务器。处理敏感或商业数据时，请使用官方 API 或正规云平台。

第一次调用：curl 与 Python SDK 示例 ​

发出第一个请求最快的方式是用 curl 直接调用 REST 接口，确认 Key、地址和模型名都正确后，再改用官方 SDK 写进程序。以下示例中 MODEL_ID 请替换为官方模型列表中的 ID，Key 从环境变量读取。

用 curl 发最小请求 ​

OpenAI Responses API：

bash
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "MODEL_ID",
    "input": "用一句话解释什么是 API。"
  }'

Anthropic Messages API 需要 x-api-key、anthropic-version 请求头和 max_tokens 参数：

bash
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话解释什么是 API。"}
    ]
  }'

Gemini 官方文档目前推荐使用 Interactions API：

bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "input": "用一句话解释什么是 API。"}'

用官方 Python SDK ​

bash
pip install openai anthropic google-genai
python
# OpenAI：客户端自动读取 OPENAI_API_KEY
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="MODEL_ID",
    input="用一句话解释什么是 API。",
)
print(response.output_text)
print(response._request_id)  # 排查问题时提供给官方支持
python
# Anthropic：客户端自动读取 ANTHROPIC_API_KEY
import anthropic

client = anthropic.Anthropic()
message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话解释什么是 API。"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)
print(message.stop_reason, message.usage)
python
# Gemini：客户端自动读取 GEMINI_API_KEY
from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="MODEL_ID",
    input="用一句话解释什么是 API。",
)
print(interaction.output_text)

第一次调用最常见的卡点 ​

  • 环境变量没生效：在一个终端里 export 的变量，换一个终端或在编辑器里运行程序时并不存在；用 echo $OPENAI_API_KEY | wc -c 之类的方式确认变量非空，而不是把 Key 打印出来。
  • Windows 命令行引号不同：上面的 curl 示例按 macOS / Linux 的 shell 写法编写，在 Windows 的 PowerShell 或 CMD 中，单引号和换行符的写法不同，建议改用 Python 示例或 WSL。
  • 复制了占位符：MODEL_ID 必须替换为官方模型列表中的真实 ID，否则会返回 400 或 404。
  • Python 版本过旧：官方 SDK 对 Python 版本有最低要求，安装或导入失败时先检查 Python 版本，具体要求以 SDK 文档为准。
  • 装错了包：Gemini 的新版 Python SDK 包名是 google-genai，导入方式为 from google import genai。

先 curl，后 SDK

curl 成功而 SDK 失败，问题在代码或 SDK 配置；curl 也失败，问题在 Key、网络或账号。这个简单的对照能省掉大量猜测。

请求、响应、流式输出和超时 ​

响应里最值得关注的是输出内容、停止原因、用量和请求 ID；长回复应使用流式输出，并合理设置超时与重试。

响应里要关注什么 ​

字段 / 信息用途
输出内容模型生成的文本或结构化结果
停止原因判断是正常结束还是被长度上限截断
用量（usage）输入、输出 token 数，用于估算费用
请求 ID排查问题、联系官方支持时提供

流式输出 ​

流式输出（streaming）让模型边生成边返回，通常通过 SSE（Server-Sent Events，一种服务器持续推送事件的 HTTP 机制）实现，适合聊天界面和长回复，也能降低长请求因空闲连接被网络设备中断的概率。

python
from openai import OpenAI

client = OpenAI()  # 自动读取 OPENAI_API_KEY

stream = client.responses.create(
    model="MODEL_ID",
    input="写一段 100 字左右的产品介绍。",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
场景是否建议流式原因
聊天界面、需要即时反馈建议用户能立刻看到输出，体验更好
生成长文档、长代码建议避免长时间无数据导致连接被网络设备切断
后台批量处理短文本可不用非流式代码更简单，结果一次性拿到
需要完整 JSON 再解析视情况可流式接收后拼接完整再解析，或使用非流式

Anthropic SDK 提供了更方便的流式辅助方法，可以直接逐段拿到文本：

python
import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一段 100 字左右的产品介绍。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()
    print()
    print(final.usage)

流式过程中也可能出错

流式响应可能在已经返回 HTTP 200 之后才出现错误事件，因此不能只检查状态码，还要处理流中的错误事件和意外断开。OpenAI SDK 文档还说明，读取流的过程不会自动重试，因为重放请求可能导致重复输出，需要由你的程序决定如何处理。

超时与重试 ​

OpenAI 和 Anthropic 的官方 Python SDK 默认请求超时都是 10 分钟，并对连接错误、408、409、429 和 5xx 自动重试 2 次（短暂的指数退避）。可以按需调整：

python
import anthropic

client = anthropic.Anthropic(
    timeout=60.0,     # 单次请求超时（秒）
    max_retries=2,    # 对连接错误、429 和 5xx 自动重试
)
  • 生成长内容时，优先使用流式输出，而不是把超时设得极长；Anthropic SDK 在预计非流式请求会超过约 10 分钟时会直接报错，提示改用流式。
  • 重试使用指数退避并加入随机抖动，遵守响应头中的 retry-after。
  • 对 400、401、403 这类客户端错误不要重试，重试不会改变结果。

多轮对话、停止原因与输出控制 ​

因为 API 是无状态的，多轮对话需要由你的程序保存历史并在每次请求中带上；同时要检查每次响应的停止原因，避免把被截断的半截回复当成完整结果。

多轮对话怎么发 ​

以 Anthropic Messages API 为例，messages 数组按时间顺序交替放入用户和模型的消息，每次请求都带上完整历史：

python
import anthropic

client = anthropic.Anthropic()
history = []


def chat(user_text: str) -> str:
    history.append({"role": "user", "content": user_text})
    msg = client.messages.create(
        model="MODEL_ID",
        max_tokens=1024,
        system="你是一名简洁的技术助理，用中文回答。",
        messages=history,
    )
    reply = "".join(b.text for b in msg.content if b.type == "text")
    history.append({"role": "assistant", "content": reply})
    return reply


print(chat("什么是 HTTP 状态码？"))
print(chat("那 429 属于哪一类？"))

system 参数是系统提示（system prompt），用来设定模型在整段对话中的角色和规则，它不属于某一轮用户消息。

历史越来越长怎么办 ​

做法说明适合
截断只保留最近若干轮闲聊类、早先内容不重要的场景
总结把早先对话总结成一段摘要放在前面需要保留关键结论的长对话
检索把资料存起来，每次只取与当前问题相关的片段知识库问答
缓存使用服务商的提示缓存功能复用不变的长前缀系统提示或参考资料很长且反复使用

历史越长，每次请求的输入 token 越多，费用和延迟都会上升，也更容易触发按 token 计算的限流。

检查停止原因 ​

停止原因告诉你模型为什么停止输出。以 Anthropic 为例，stop_reason 为 end_turn 表示正常结束，为 max_tokens 表示达到了你设置的输出上限而被截断。OpenAI Responses API 在输出未完成时会把响应状态标记为未完成并给出原因。处理原则是：

  • 被长度上限截断时，不要直接把结果交给用户，可以调高输出上限，或让模型分段输出；
  • 需要机器解析的输出（如 JSON），截断后几乎一定解析失败，应在解析前先检查停止原因；
  • 把停止原因和用量一起记入日志，便于分析哪些请求经常被截断。

代理、证书与网络环境配置 ​

在公司代理、TLS 解密网关或需要代理才能访问外网的环境中调用 API，核心是让你的 HTTP 客户端知道「走哪个代理」和「信任哪个根证书」；curl 和官方 SDK 都支持通过标准环境变量完成配置。

用环境变量配置代理（示例） ​

bash
# 地址请替换为你实际使用的代理
export HTTPS_PROXY=http://127.0.0.1:7890
export https_proxy=$HTTPS_PROXY
# 本地服务和内网地址不走代理
export NO_PROXY=localhost,127.0.0.1
工具读取方式
curl读取 https_proxy / HTTPS_PROXY 等变量；也可用 -x 参数为单条命令指定代理
OpenAI / Anthropic Python SDK默认 HTTP 客户端启用 trust_env，读取环境中的代理与证书变量
其他语言 SDK以各自 SDK 文档为准，部分运行时需要显式配置代理

用 curl 验证代理是否生效的最小检查：

bash
# -v 显示连接过程，可以看到是否连到了代理以及 TLS 握手结果
curl -v -x http://127.0.0.1:7890 https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

在 SDK 中显式指定代理 ​

不希望依赖环境变量时，可以在创建客户端时传入自定义 HTTP 客户端。以 Anthropic 官方文档的写法为例：

python
import anthropic
from anthropic import DefaultHttpxClient

client = anthropic.Anthropic(
    http_client=DefaultHttpxClient(proxy="http://127.0.0.1:7890"),
)

OpenAI Python SDK 的对应类名在新版本中为 DefaultHttpx2Client（底层 HTTP 库已切换为 httpx2），旧版本为 DefaultHttpxClient。类名随 SDK 版本变化，请以你所安装版本的 README 为准。

企业根证书 ​

企业 TLS 解密网关会用公司私有根证书重新签发 HTTPS 证书，程序未信任该根证书时会报证书校验失败。OpenAI Python SDK 的迁移说明指出，新版底层 HTTP 库默认使用操作系统证书库；如果根证书未安装到系统证书库，可以显式指定：

bash
export SSL_CERT_FILE=/path/to/ca-bundle.pem
# 或指定一个证书目录
export SSL_CERT_DIR=/path/to/ca-directory

根证书请向公司 IT 部门索取，不要从网上下载来源不明的证书。不要用关闭证书校验的方式「解决」问题，那会让中间人可以读取你的 Key 和数据。

网络问题对照 ​

现象可能原因处理
连接超时、APIConnectionError代理未生效或网络不通用 curl -v 确认代理；检查变量是否设置在运行程序的同一环境
certificate verify failed根证书未被信任安装根证书到系统证书库，或设置 SSL_CERT_FILE
本地服务也被转发到代理缺少 NO_PROXY把本地和内网地址加入 NO_PROXY
长请求中途断开代理或网关切断长时间空闲连接改用流式输出
偶发 403 且信息提示地区出口地区不在支持名单参考官方支持地区名单，并遵守服务条款

示例场景：一段脚本在个人电脑上运行正常，部署到公司服务器后报 certificate verify failed。原因通常是公司网关对 HTTPS 流量做了解密，而服务器上的 Python 环境不信任公司的根证书。正确的处理是向 IT 部门获取根证书，安装到服务器的系统证书库或用 SSL_CERT_FILE 指定，然后用 curl -v 和最小请求分别验证；同时确认该服务器访问外部 AI 服务符合公司的数据安全规定。错误的处理是在代码中关闭证书校验，这会让 Key 和请求内容暴露在中间人面前。

更多网络排查思路可参考 TLS 与证书问题 和 代理冲突排查，并请遵守所在地法律法规与服务条款。

自己验证的顺序 ​

第一次调用失败、或原本正常的调用突然出错时，按下面的顺序逐步排除，每一步确认没问题再进入下一步：

  1. 确认资格：打开下文「官方资格入口」中对应服务商的 API 支持地区页面，确认你所在的国家或地区在名单内；不受支持的地区可能直接返回 403。
  2. 确认三件套：API Key、Base URL、模型名来自同一服务商；用 env | grep BASE_URL 检查是否有残留的 Base URL 环境变量。
  3. 用 curl 发最小请求：只带必需的请求头和一条短消息，排除 SDK 与业务代码的影响。
  4. 确认网络与证书：用 curl -v 看是否连到了预期的代理、TLS 握手是否成功；本地与内网地址写进 NO_PROXY。
  5. 再换 SDK 和真实请求：确认 SDK 读取到了正确的 Key 和代理配置，再逐步加长输入、打开流式输出。
  6. 按状态码处理：记下状态码、错误信息和请求 ID，按下一节的对照表处理，400 类错误先改请求再重试。

怎样记录一次有效测试

每次只改一个变量，并写下：时间（含时区）、使用的入口或命令、网络环境（家庭宽带 / 手机网络 / 公司网络）、做了什么操作、结果与报错原文。连续几次记录都指向同一环节，再去对应章节处理或向官方支持反馈，比凭印象判断可靠得多。

身份验证、限流和常见错误码 ​

不同服务商的错误类型名称略有差异，但 HTTP 状态码的含义大体一致；先看状态码判断大类，再看错误信息中的具体类型决定处理方式。

状态码含义常见原因处理方法
400请求无效参数格式错误、缺少必填字段、模型名拼写错误对照官方 API 参考检查请求体
401身份验证失败Key 错误、已吊销或过期；请求头写错检查 Key 和认证头格式，必要时重新生成
402计费问题付款信息异常、预付额度不足（部分服务商使用）到控制台检查付款方式与余额
403无权限Key 无权访问该资源；从不受支持的地区访问检查项目 / 工作区权限与地区支持情况
404资源不存在路径错误、Base URL 拼接错误、模型名不可用核对完整 URL 与模型 ID
413请求过大一次发送的内容超过大小上限拆分内容或改用文件接口
429请求过多 / 额度受限超过速率限制；余额耗尽；达到消费上限限流则降速并退避重试；额度问题去控制台处理
500服务端内部错误服务商侧异常稍后退避重试，持续出现时查看官方状态页
503 / 529服务暂时不可用 / 过载高峰期容量不足退避重试，必要时降低并发
504网关超时请求处理时间过长改用流式输出或缩短单次任务

401 与 403 的快速自查 ​

401 和 403 是新手最常遇到的两类错误，区别在于：401 是「服务器不认识你」，403 是「服务器认识你，但不允许你做这件事」。

遇到 401 时依次检查：环境变量是否真的被程序读到（在代码里打印 Key 的前几位和长度，不要打印完整 Key）；Key 是否有多余的空格、换行或引号；认证请求头是否写对（OpenAI 用 Authorization: Bearer，Anthropic 用 x-api-key，Gemini 用 x-goog-api-key）；Key 是否已被吊销；是否把一家的 Key 发到了另一家的地址。

遇到 403 时依次检查：Key 所属的项目或工作区是否有权使用该模型或功能；组织是否设置了 IP 允许列表；请求的出口地区是否在服务商支持名单内。

5xx 与过载怎么应对 ​

5xx 表示问题出在服务商一侧，你的请求本身可能没有错。偶发的 500、503 或 529 用指数退避重试即可；如果持续出现，先查看服务商的官方状态页确认是否有故障公告，再考虑降低并发、错峰执行批量任务，或在业务允许时临时切换到同一服务商的其他模型。对用户可见的产品，应准备友好的降级提示，而不是让请求无限重试、拖垮自己的服务。

各家的具体说明 ​

服务商值得注意的细节
OpenAI401 细分为认证无效、Key 错误、不是组织成员、IP 不在允许列表等；403 包括国家或地区不受支持；503 可能表示模型暂时过载，有 Retry-After 时按其等待
Anthropic529 表示服务过载；达到所在层级的月度消费上限时返回 429，错误详情中的 error_code 为 enforced_spend_limit_reached，且没有 retry-after；达到你自己设置的消费上限时返回 400
Gemini429 包括速率限制和配额用尽；402 表示预付余额不足；503 为服务暂时过载，504 为请求超过截止时间

SDK 中的异常类型 ​

官方 Python SDK 把状态码映射为异常类，便于按类型处理：

状态码异常类（OpenAI 与 Anthropic SDK 相同）
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
429RateLimitError
5xxInternalServerError
无法连接APIConnectionError（超时为其子类 APITimeoutError）

限流响应头 ​

速率限制（rate limit）是服务商对单位时间内请求数和 token 数的上限，常见指标为每分钟请求数和每分钟 token 数。响应头会告诉你还剩多少：

服务商主要响应头
OpenAIx-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests，以及对应的 -tokens 版本，Retry-After
Anthropicretry-after、anthropic-ratelimit-requests-remaining、anthropic-ratelimit-input-tokens-remaining、anthropic-ratelimit-output-tokens-remaining 等，重置时间为 RFC 3339 格式

Anthropic 文档还提到，限流按令牌桶算法持续补充，短时间的突发请求也可能触发限流；组织用量骤增时还可能遇到加速限制，应平稳地逐步提升流量。

一个带退避的重试示例 ​

SDK 自带的重试已能应对多数情况；需要自定义策略时，可以关闭内置重试并按 retry-after 等待：

python
import random
import time

import anthropic

client = anthropic.Anthropic(max_retries=0)  # 关闭内置重试，改用下方逻辑


def ask(prompt: str, attempts: int = 5) -> str:
    for i in range(attempts):
        try:
            msg = client.messages.create(
                model="MODEL_ID",
                max_tokens=512,
                messages=[{"role": "user", "content": prompt}],
            )
            return "".join(b.text for b in msg.content if b.type == "text")
        except anthropic.RateLimitError as e:
            retry_after = e.response.headers.get("retry-after")
            if retry_after is None:
                raise  # 没有 retry-after 可能是额度或消费上限问题，重试无用
            time.sleep(float(retry_after))
        except (anthropic.InternalServerError, anthropic.APIConnectionError):
            time.sleep(min(2 ** i + random.random(), 30))  # 指数退避加随机抖动
    raise RuntimeError("多次重试后仍失败")


print(ask("用一句话解释什么是限流。"))

429 要分两种情况

同样是 429，「请求太快」等一会儿就好；「余额用完」或「达到消费上限」则会一直失败，直到你在控制台充值或调整限额。看错误信息里的具体说明，以及有没有 retry-after，再决定怎么处理。

排查顺序 ​

  1. 打印完整的状态码和错误信息（不要只看「请求失败」）；
  2. 确认 Key、Base URL、模型名三者来自同一服务商，并检查是否有残留的 *_BASE_URL 环境变量；
  3. 用 curl 发一个最小请求，排除代码问题；
  4. 网络类错误用 curl -v 检查代理和证书；
  5. 查看控制台中的余额、限额和用量；
  6. 查看服务商官方状态页，确认是否为服务端故障；
  7. 联系官方支持时附上请求 ID 和发生时间。

网页订阅与 API 计费信息的分别核对 ​

最常见的误解是「我已经订阅了网页版，为什么 API 还要付费」；实际上二者是完全独立的两套计费体系。

对比项网页 / 应用订阅API
面向在网页、桌面和手机上直接使用的人在程序中调用的开发者
计费方式按方案周期付费按用量（通常按 token）计费，部分有免费层
管理位置产品内的账号 / 订阅设置开发者控制台的账单与用量页面
额度是否互通不包含 API 额度不包含网页订阅权益

去哪里核对价格与账单 ​

服务商订阅价格API 价格API 用量与账单
OpenAIChatGPT 官方定价页OpenAI API 定价页OpenAI 开发者平台的 Usage 与 Billing 页面
AnthropicClaude 官方定价页（claude.com/pricing）Claude API 定价页Claude Console 的用量与账单页面
GoogleGemini 官方订阅方案页面Gemini API 定价页（ai.google.dev）Google AI Studio 与 Google Cloud 账单

本站不列具体价格和额度，均以上述官方页面为准。

该用订阅还是 API ​

  • 只是自己日常使用：网页、桌面或手机应用的订阅更合适，无需关心 token 计量和 Key 管理。
  • 要把模型能力接进自己的程序、网站或自动化脚本：必须使用 API，订阅无法用于程序调用。
  • 两者都需要：分别开通、分别付费，在各自的管理页面核对账单，不要指望其中一方的额度抵扣另一方。
  • 团队使用：订阅侧一般有团队方案，API 侧通过组织、项目或工作区划分权限和预算，两套管理入口互不影响。

核对账单时最常见的问题，是把「订阅扣费记录」和「API 用量账单」混在一起看。建议在记账时分成两类：订阅按周期固定支出，API 按月份统计实际用量，并对照控制台中按项目或 Key 拆分的用量明细。

编程工具的计费方式

Codex 和 Claude Code 既可以用订阅账号登录，也可以用 API Key 或 API 控制台账号登录，后者按 API 用量计费。注意在终端里设置了 ANTHROPIC_API_KEY 时，Claude Code 会改用 API Key 计费。详见 Codex 使用教程 与 Claude Code 教程。

API 接入配置、兼容性和用量管理 ​

把 Key、地址、模型名、超时等配置集中管理，并为每个项目设置消费上限，是 API 接入从「能跑」到「可维护」的关键。

配置项清单 ​

配置项说明
API Key从环境变量读取，不硬编码
Base URL默认使用 SDK 内置的官方地址；只有在使用官方兼容端点或云平台时才修改
模型名集中放在配置文件中，便于统一替换
超时与重试根据任务长度设置，长任务配合流式输出
最大输出长度控制成本，也避免回复被意外截断时毫无察觉
代理与证书通过环境变量或 SDK 的 HTTP 客户端参数配置，不同部署环境分别设置

关于「OpenAI 兼容」接口 ​

不少服务提供与 OpenAI 接口格式兼容的端点，只需修改 Base URL 和 Key 即可复用代码。例如 Gemini 官方提供了 OpenAI 兼容端点：

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

需要注意：

  • 「兼容」通常只覆盖常用参数，部分高级功能、参数或返回字段可能不一致；
  • 模型名仍须使用该服务商自己的模型 ID；
  • 兼容端点的限制和行为以该服务商自己的文档为准。

用量管理 ​

  1. 设置消费上限与提醒：在控制台为组织或项目设置月度预算和告警。
  2. 按项目分 Key：不同应用使用不同 Key 或项目，账单一目了然。
  3. 记录每次请求的用量：从响应中的 usage 字段累计，定期与控制台账单对照。
  4. 控制输入长度：不要每次都附带全部历史对话和资料，只发送必要的上下文。
  5. 定期轮换和清理 Key：吊销不再使用的 Key，降低泄露风险。

日志里应该记录什么 ​

字段用途
请求 ID与官方支持沟通、在控制台中对照具体请求
时间与耗时发现变慢的时间段，区分网络问题与服务端问题
模型名换模型后对比效果与成本
输入 / 输出 token 数估算成本，发现异常的超长请求
停止原因统计被截断的比例
状态码与错误类型统计限流、超时、服务端错误的频率

日志中不要记录 API Key，也尽量不要完整记录用户输入的敏感内容；需要排查时，记录请求 ID 通常已经足够定位问题。

示例场景：给内部工具接入 API ​

示例场景：团队想做一个内部的「会议纪要整理」工具。合理的架构是：前端只调用自己的后端接口；后端从密钥管理工具读取 API Key，统一设置超时、重试和最大输出长度；每次调用记录请求 ID、用量和耗时；在控制台为这个项目单独建 Key 并设置月度消费上限。上线前用少量真实样例测试输出质量和用量，再逐步放开使用范围。这样即使出现异常调用或费用增长，也能快速定位到具体项目并止损。

上线前检查清单 ​

把 API 调用放进正式产品之前，逐项确认以下内容，可以避免大部分安全和稳定性事故。

  • [ ] API Key 只存在于服务端环境变量或密钥管理工具中，前端代码与仓库中搜索不到；
  • [ ] Base URL 是官方地址或正规云平台地址，环境中没有残留的覆盖变量；
  • [ ] 模型名集中配置，并已在官方模型列表中核对；
  • [ ] 设置了合理的超时，长输出使用流式；
  • [ ] 对 429 和 5xx 有退避重试，对 400、401、403 不重试；
  • [ ] 区分了速率限制与额度耗尽，后者会触发告警而不是无限重试；
  • [ ] 记录了请求 ID、状态码和用量，日志中不包含 Key 和敏感用户数据；
  • [ ] 在控制台设置了消费上限和用量告警；
  • [ ] 代理和证书配置在每个部署环境中都验证过；
  • [ ] 已阅读服务商的使用政策，确认业务场景符合条款与所在地法律法规。

官方资格入口 ​

OpenAI、Anthropic、Google 的 API 都只在各自支持的国家和地区提供，名单与网页产品分开列出。下面只列官方页面：

产品官方页面说明
OpenAI APIOpenAI 开发者文档：API 支持的国家和地区与 ChatGPT 名单分开列出，两份不一定相同
Claude（claude.ai、Claude Code、Claude API）Anthropic：支持的国家和地区claude.ai 与 API 的名单在同一页面分别列出
Gemini API 与 Google AI StudioGoogle AI for Developers：Gemini API 可用地区与 Gemini 应用名单不一定相同

以官方页面为准

名单会随时调整，本站只提供官方页面的入口，不代为判断某个账号能否使用，请以官方页面当前内容为准，并遵守所在地法律法规与各服务的使用条款。

依据与来源 ​

信息来源核验时间
OpenAI Responses API 端点、Bearer 认证、OPENAI_API_KEYOpenAI API 快速入门 developers.openai.com/api/docs/quickstart2026-10-07
OpenAI 错误码含义（401 细分、403 地区、429、500、503）与 Python 异常类OpenAI 错误码指南 developers.openai.com/api/docs/guides/error-codes2026-10-07
OpenAI 限流响应头与指数退避建议developers.openai.com/api/docs/guides/rate-limits2026-10-07
OpenAI Python SDK 超时、重试、OPENAI_BASE_URL、_request_id、DefaultHttpx2Client、SSL_CERT_FILEgithub.com/openai/openai-python 的 README.md 与 httpx2.md2026-10-07
Anthropic Messages API 端点、x-api-key 与 anthropic-versionClaude API 快速入门 platform.claude.com/docs/en/get-started2026-10-07
Anthropic 错误码（400–529）、请求 ID、流式中途错误Claude API 错误文档 platform.claude.com/docs/en/api/errors2026-10-07
Anthropic Python SDK 超时、重试、流式辅助方法、异常类、代理配置、ANTHROPIC_BASE_URLplatform.claude.com/docs/en/api/sdks/python2026-10-07
Anthropic 限流响应头、消费上限 429 与 400 的区别platform.claude.com/docs/en/api/rate-limits2026-10-07
Gemini API Key、x-goog-api-key、GEMINI_API_KEY、Interactions API 示例ai.google.dev/gemini-api/docs/api-key 与 ai.google.dev/gemini-api/docs/quickstart2026-10-07
Gemini OpenAI 兼容端点ai.google.dev/gemini-api/docs/openai2026-10-07
Gemini 错误码ai.google.dev/gemini-api/docs/api-errors2026-10-07

常见问题 ​

API Key、Base URL 和模型名分别是什么？

API Key 是调用接口的身份凭证；Base URL 是接口服务器的地址；模型名是请求里指定要使用哪个模型的标识。三者需要来自同一个服务商并相互匹配，请求才能成功。

ChatGPT、Claude 的网页订阅能抵扣 API 费用吗？

不能。网页或应用订阅与 API 是两套独立的计费体系，API 需要在开发者平台单独开通并按用量计费，价格以各自的官方定价页为准。

429 错误是什么意思？

429 表示请求过多或额度受限，可能是触发了速率限制，也可能是余额或消费上限已用完。前者降低频率并按 retry-after 退避重试即可，后者需要到控制台检查账单与限额。

第三方中转接口可靠吗？

第三方接口不是官方服务，存在数据经过第三方服务器、模型名与实际不符、服务突然中断和违反服务条款等风险。处理敏感数据或生产业务时，建议使用官方 API 或正规云平台。

API Key 可以写在前端网页或 App 里吗？

不可以。前端和移动应用的代码可以被任何人提取，Key 一旦暴露就会被他人盗用。正确做法是由自己的后端保存 Key 并代为调用，前端只请求你的后端。

调用 API 时需要走代理，Python SDK 怎么配置？

官方 Python SDK 默认会读取环境中的代理与证书变量，也可以在创建客户端时通过 http_client 参数显式指定代理。企业 TLS 解密网关环境下，可用 SSL_CERT_FILE 指定根证书。

长回复总是超时或中途断开怎么办？

优先改用流式输出，让数据持续返回，而不是把超时设得极长；同时检查代理是否会切断长时间空闲的连接。官方 SDK 默认超时为 10 分钟，并对连接错误、429 和 5xx 自动重试。

调用失败时应该先查什么？

先打印完整的状态码和错误信息，再确认 Key、Base URL、模型名来自同一服务商，然后用 curl 发一个最小请求排除代码问题，最后查看控制台余额限额和官方状态页。

延伸阅读 ​

更新记录 ​

日期变更
2026-10-07首次发布完整内容
2026-10-07扩写为深度指南
2026-10-08按搜索结果页结构调整：开头直接回答、增加速查表、「自己验证的顺序」与「官方资格入口」（仅链接官方页面）

本专题文章 ​

暂无文章，敬请期待。