API和SDK有什么区别

很多人第一次接大模型，会卡在一个很基本的疑问上：我拿到一个 Key，到底该直接发 HTTP 请求，还是装个官方库？两者名字都听过，但说不清谁管谁。这篇按「先分层、再看调用路径、最后给选择清单」的顺序讲一遍，读完你能判断手上这个场景该走哪条路，以及选错了会多花哪些力气。

很多人第一次接大模型，会卡在一个很基本的疑问上：我拿到一个 Key，到底该直接发 HTTP 请求，还是装个官方库？两者名字都听过，但说不清谁管谁。这篇按「先分层、再看调用路径、最后给选择清单」的顺序讲一遍，读完你能判断手上这个场景该走哪条路，以及选错了会多花哪些力气。

先给一句能记住的话：API 是规则，SDK 是把规则包好的工具。两者不是二选一的关系，而是上下两层。下面拆开讲，每层都配上能立刻动手验证的动作。

先把 API 说清楚：它是一份契约

API 本质是双方约定的调用规则，包含请求地址、请求方法、要传哪些参数、返回什么结构。它跟编程语言完全无关，你用命令行、Postman、Python、Java 去调同一个 API，拿到的结果是一样的。所以判断标准很简单：如果换个语言就得把整套逻辑重写一遍，那你用的就是 API 那一层，没被谁封装。

想直观感受这份契约，最有效的办法不是看教程，而是看一遍请求和响应的字段结构。字段名、必填还是选填、返回里哪几个字段是嵌套的，这些看一遍比读十页文档都清楚。站内有一份结构说明可以对照着看：/openai-compatible-api-shape，顺着字段从头到尾过一遍，你对「契约」这个词就有实感了。

SDK 是什么：把 API 包起来的一层工具箱

SDK 通常包含针对某门语言的客户端库、鉴权封装、参数对象、重试逻辑和错误类，有些还附示例代码和本地文档。它的价值在省掉样板代码：拼接 URL、序列化 JSON、处理超时、统一异常类型，这些你都不用手写。但要注意，它内部最终还是要发 HTTP 请求，所以 API 变了，SDK 也必须跟着升级，否则就是版本错配。

什么时候 SDK 不适用？三种情况：你用的语言没有官方 SDK；你要极细地控制请求头、超时和重试策略；或者你怀疑 SDK 在偷偷帮你改参数，想排除干扰。这时候直连 API 反而更省事，因为你看到的每一个字段都是自己写的。

两者的关系：SDK 站在 API 上面，不是替代

从上到下是「你的代码 → SDK → HTTP 请求 → 服务端」。SDK 只是中间一层翻译，它不能绕过 API，也不能给你 API 之外的能力。同一家服务，直连和用 SDK 拿到的是同一个模型、同一份额度，差别只在写法。所以别纠结「哪个更高级」，要纠结的是「哪个更好排错」。

这条链在排错时特别好用。报错如果发生在参数构造阶段，那多半是 SDK 层的问题，比如版本不对、字段名改了；如果报错是网络超时或服务端返回异常状态码，那是 API 层的问题，跟 SDK 关系不大。方向不同，排查动作完全不一样，先分清楚能省很多时间。

• 版本错配是常见坑：SDK 和接口口径对不上时，先降到直连 API 验证，确认是不是库的问题
• SDK 的隐式重试要留意：有些库默认帮你重试，日志里看到的请求次数会比你预期多
• 混用完全可行：用 SDK 起项目，遇到疑难再抓原始请求体去直连复现
• 抓包是通用手段：不管走哪层，把实际发出的请求体打印出来，一切疑惑都好解

怎么选：一张对照清单

选择不靠感觉，靠场景。以下几种情况可以照着对号入座，选错了也能随时切换，别当成一锤子买卖。

选 SDK 的场景

主流语言、想快速跑通、愿意接受它的默认重试和默认参数

选直连 API 的场景

需要精细控制超时与重试、语言没有官方库、或想避开 SDK 的隐式行为

混用的场景

SDK 起项目，问题复杂时抓原始请求体去直连复现

先确认的三件事

鉴权方式、Base URL 写法、所在网络能不能通

1. 第一步：先量网络基线在写任何代码之前，用 /tools/speed-test 测一下到目标服务的延迟。基线不清楚，后面报错你分不清是网络还是代码。
2. 第二步：用直连跑通一次最小请求不装任何库，用命令行或 Postman 发一次最简单的请求，确认 Key、地址、参数都对。这一步通了，说明 API 层面没问题。
3. 第三步：再套 SDK 写业务代码直连通了之后，换上 SDK 写正式逻辑，遇到行为不一致，回头对比第二步的原始请求就能定位。
4. 第四步：确认口径与时效具体用哪家、什么价、接口结构有没有变，到 /official-api 核对当时的数字和说明，别照搬别人文章里的旧结论。

最后提醒一句：这套判断不是永久的。项目变复杂、团队换语言、服务端升级，你的选择都可能要跟着调。所以别把「用 SDK」或「直连」当成技术偏好，当成当前场景下的临时决定就好。