api接口和http接口的区别，常见坑和正确做法一次讲清

很多人一开口就把「API 接口」和「HTTP 接口」当同义词，写文档、配 Base URL、跟后端对接口时各自理解不一致，最后问题出在鉴权、路径或协议上却互相推锅。这篇不铺概念，先给包含关系的一句话结论，再用一张对照表把场景、坑点和正确做法列出来，最后给一份上手前的自查清单。

很多人一开口就把「API 接口」和「HTTP 接口」当同义词用，写文档的、配 Base URL 的、跟后端对接口的各说各话，最后问题出在鉴权、路径还是协议上，谁也说不清，只能互相甩锅。这篇不铺概念，先把包含关系一句话讲死，再用对照表把场景、坑点和正确做法列出来，最后给一份上手前的自查清单，照着走能少返工。

适用范围先说清楚：这套判断主要给做服务对接、写接口文档、配中转服务的人用。如果你只是调一个现成 SDK 里的函数，那层传输细节已经被封装掉了，下面讨论的很多内容对你不成立，不用硬套。

先定关系：谁包含谁

API 是「能力约定」，讲的是你能调什么、传什么、拿回什么；HTTP 只是承载这层约定的一种传输方式。RPC、gRPC、WebSocket、甚至一个 SDK 里的方法调用，都可以叫 API。HTTP 接口是用 HTTP 方法和路径把这些能力暴露出来的形式，是 API 的子集。所以「HTTP 接口必然是 API 接口」成立，反过来不成立。

API

能力层面的约定：有哪些操作、入参出参长什么样

HTTP 接口

用方法加路径承载约定的具体形式，属于 API 的一种

协议

约定的字段风格，比如兼容层和各家原生协议字段往往对不上

Base URL

只是入口地址，改它不改变接口本身的约定

判断口径很简单：双方聊的是「能力边界」还是「传输细节」。聊能力边界时说 API 没问题，聊怎么发请求、放哪个头、用什么方法时再说 HTTP 接口。对外文档里这两层最好分开写，否则读者会把地址当接口全部信息。

常见混淆点和它们的真实代价

• 先抓一份对方给的请求样例，它比任何口头描述都准，字段名和层级照抄不猜
• 请求方法不写清就别动手，GET 和 POST 在参数位置上经常不一样
• 流式返回和一次性返回的处理逻辑完全不同，接之前要问明白
• 错误码要分级看：连接失败、HTTP 状态异常、业务响应体报错是三件事
• 改配置一次只改一项，改完立刻发最小请求验证，别攒着一起改

还有一类高频坑是把「协议兼容」当成「接口全等」：很多中转服务对外声称兼容某种风格，实际字段和错误码结构有出入。这类差异光看宣传看不出来，得比对实际请求样例，并到 /stacks 的协议与 SDK 目录里核对对应关系，别凭印象假设。

给开发者的落地对照与自查清单

1. 先定性问对方要的是能力描述还是一份抓包样例。只说「支持某模型、某能力」的是能力层，必须再要到方法、路径、鉴权头的细节才能动手。
2. 列四要素把请求方法、完整路径、鉴权方式、请求体字段列成一张表，缺一项就标红，别等联调时才发现没对齐。
3. 最小请求先行用最少字段发一次请求，确认连通和鉴权通过；通了再逐个补字段，不要一上来就跑完整业务流。
4. 分层排错连不上查地址和网络，连上但状态码异常查方法和头，状态码正常但结果不对查响应体结构和字段名。
5. 文档固定模板团队统一一段模板：接口名、传输方式、方法路径、鉴权方式、请求示例、错误码含义，缺项不允许上线。
6. 外部服务先验可信度用第三方中转时，先到 /sites 看可信度检测结果，再拿最小请求实测一遍，两边一致才算接稳。

联调顺序和排错顺序最好写进团队规范，不是靠个人经验。一家 5 人小团队最常见的翻车就是：一个人按抓包接了，另一个人按文档接了，两套理解叠在同一个项目里，最后谁都说不清哪一步错了。规范写清四要素和分层排错，新人接手也能快速定位。

至于某家中转当前的价格与可用模型，别用旧截图做判断，到 /price-watch 核对当时的数字，再决定是否用它做长期依赖。价格和模型列表会变，接口约定相对稳定，两者要分开看。