API 文档 · 术语表
AI API 术语表
接入 AI API 时最常遇到的概念，一处讲清楚。面向开发者，从鉴权、计量到流式、工具调用、可靠性设计，按主题排列，方便速查与引用。
接入基础
- Base URL
- 客户端发送 API 请求的基础地址。原生 SDK 通常填主机根（如
https://api.anthropic.com），SDK 会自行追加/v1/...；OpenAI 兼容层则常需带/v1。填错会导致 404。详见 API 文档。 - API Key
- 用于鉴权的密钥，标识调用方身份并计费。应只保存在服务端环境变量或密钥管理系统，最小权限、可轮换、可撤销，绝不写入前端或日志。参见 API Key 安全。
- x-api-key 与 Bearer
- 两种鉴权头写法。OpenAI 用
Authorization: Bearer；Claude 原生用x-api-key（并带anthropic-version）。混用通常导致 401。 - OpenAI 兼容
- 实现 OpenAI API 请求/响应格式的接口，可复用 OpenAI SDK。兼容程度参差：普通对话成功不代表流式、工具调用、
usage字段都完整。迁移方法见 OpenAI 兼容 API 迁移。 - Chat Completions 与 Responses
- OpenAI 的两套主接口。Chat Completions 生态最全、兼容层普遍支持；Responses 更新、内置工具与状态管理更强，但兼容层支持不一。
- Messages API
- Anthropic Claude 的原生对话接口，使用
x-api-key与anthropic-version头，max_tokens为必填。接入见 Claude 中转接入。
计量与成本
- Token
- 模型处理文本的最小计费单位。一段文本被切分为若干 token，输入与输出分别计量，是成本核算的基础。
- 上下文窗口
- Context window，模型单次请求能容纳的 token 上限（输入+输出）。超出会返回
context_length_exceeded类错误。 - usage
- 响应中的用量字段，通常含
prompt_tokens/completion_tokens/total_tokens。流式需用include_usage等选项在流末尾获取。 - 倍率
- 部分中转站在基准费用上的计算系数。真实费用需用分类用量、价格版本、倍率与附加规则，配合 request ID 对照账单复算。参见 倍率是什么意思。
- 成本控制
- 结合模型路由、缓存、重试预算与异常告警建立可复核的费用流程。展开见 AI API 成本控制。
运行时与性能
- 流式输出
- Streaming，服务端通过 SSE 逐块返回内容。需消费完整事件链并等待结束标记（
[DONE]或message_stop），HTTP 200 后流内仍可能出错。见 流式与工具兼容。 - TTFT
- Time To First Token，首字时间，从发出请求到收到第一个内容块的耗时，衡量交互式体验的关键延迟指标。
- RPM / TPM 与速率限制
- 每分钟请求数与每分钟 token 数，是常见的限速维度，超限返回 429。需区分限速与欠费。
- 工具调用
- Tool calling / function calling，模型按定义的工具返回结构化调用请求。依赖 tool_call ID、参数 JSON、tool 角色回传与内容块顺序，需单独验证。
- JSON mode
- 约束模型输出为合法 JSON 的模式。需与
response_format等参数配合，兼容层可能忽略该字段。 - stop_reason / finish_reason
- 标识生成结束原因，如
end_turn、max_tokens、tool_use/tool_calls。据此判断是否正常结束，而非只看首段文本。
可靠性设计
- 幂等
- Idempotency，同一请求重复执行结果一致。重试前应过幂等门禁，避免重复扣费或重复副作用。
- 重试与退避
- Retry & backoff，失败后按指数退避加抖动有限重试，并设重试预算，避免重试风暴。见 重试机制。
- 熔断
- Circuit breaker，上游错误率过高时暂时切断请求，快速失败并给系统恢复时间，避免雪崩。
- 降级
- Fallback，主路径失败时切换到能力兼容的备选（换模型或换上游），保证可用性，需注意能力差异。
网关与运维
- 中转站 / 网关
- 位于客户端与模型上游之间的中间层，统一 Base URL 与鉴权、做模型路由、计量与限流。统一入口降低配置成本，但不保证所有上游接口完全兼容。原理见 API 中转站是什么。
- 上游
- Upstream，网关背后真正提供模型能力的服务方。判断上游是否透明要看模型映射、request ID、路由变更与可对账用量。见 上游渠道核验。
- 模型路由
- 网关按模型名或策略把请求分发到不同上游或渠道。路由是否透明、可对账，是评估网关可信度的核心。
- request ID
- 每次请求的唯一标识，用于日志关联、故障定位与账单对账。走网关时应同时保存网关与上游两个 request ID。
- 可观测性
- Observability，通过指标、日志与分布式追踪定位请求边界与上游尝试，完成用量、SLO 与告警复盘。见 可观测性。
遇到具体报错，配合 AI API 错误码速查手册 使用。
核验日期：本术语表于 2026-09-04 复核，概念定义力求稳定；涉及具体接口行为的部分，请以各家官方文档与你的控制台为准。