---
title: "把 API 接稳：从 key 到重试"
description: "接 API 不是换个 base URL 就完事。专题从密钥、端点与第一次请求讲起，覆盖 OpenAI 兼容、流式响应、限流重试与幂等，最后给出可排查的调试路径。"
updated: 2026-11-13
canonical: https://docai.cc/topics/api-integration/
markdown_mirror: https://docai.cc/topics/api-integration.md
---
把模型接进产品，第一步不是选模型，而是让一次请求稳定地发出去并拿到可解析的结果。密钥放哪、请求发到哪、失败怎么判断，这些基础决定后面的功能能不能做。

## 这个专题包含什么

专题覆盖一条完整链路。基础部分讲 API、API 密钥与端点：请求由谁认证、发往哪里、一次最小调用需要哪些字段。接入部分讲第一次 API 调用、接入代码、OpenAI 兼容接口与 base URL：很多客户端只认某种请求格式，兼容层和地址配错是最常见的失败原因。稳定性部分讲流式响应与 SSE、重试与退避、幂等、限流，以及流式调试课。请求日志要能定位到具体调用，但不要把完整密钥写进日志。专题不比较供应商，也不提供密钥托管方案的具体实现；密钥绝不能写进前端代码或提交到仓库，这一点没有例外。

## 学习顺序

先读 API 与密钥，建立「认证信息只放服务端」的底线。再读端点，理解地址、版本与路径的关系。第三步跟课跑通第一次调用：用最小请求验证密钥、网络和返回格式，不要在这一步就叠加重试与流式。第四步把请求接进代码，处理超时、异常与日志。之后读 OpenAI 兼容接口与 base URL，理解换供应商时哪些字段可能不兼容。稳定性部分按「先流式、再重试、再幂等」推进：流式课讲事件格式与断流判断，重试与退避讲哪些错误值得重试，幂等讲重复请求为什么不能产生重复副作用，限流讲配额与排队，最后用流式调试课收口。流式不是所有场景都需要；先确认产品是否真的需要逐字输出。

## 全部相关词条

基础组：API、API 密钥、端点、流式响应、SSE。兼容与迁移组：OpenAI 兼容接口、base URL、兼容接入课。稳定性组：重试与退避、幂等、限流、流式调试课。建议先把基础组的请求跑通，再碰兼容层；稳定性组不是上线前才补的装饰，而是从第一次调用就该有的默认行为。兼容层只解决格式，不解决能力差异；换供应商后仍要重跑关键用例。密钥轮换与权限最小化也要在第一次接入时就定好，不要等出事再补。出错时先看请求与响应，再怀疑模型；大多数问题在到达模型之前就发生了。