接口文档好不好：照着跑一遍就知道

选大模型 API 时，能力看榜单，接入成本看文档。文档差一个档次，工期可能从一天变成一周，因为你要花时间猜参数、试错误码、绕开没写清楚的限制。判断方法不复杂：把官方示例原样跑一遍，数一数改了几处才通。

五分钟跑通测试

准备一个空项目，只装官方 SDK，复制文档里的示例，只改密钥和模型名。记录三件事：改了几处、报了什么错、多久拿到首个正常返回。

改三处以内属于正常，通常是密钥、模型名、接口地址。要改五处以上，或者示例里的方法名在 SDK 里根本不存在，说明文档和当前版本脱节。这时候先看变更记录，确认是不是版本对不上，再决定要不要继续评估。

测试时把口径固定下来：同一段输入、同一个模型、同一个区域端点。对比类评测最容易犯的错是变量太多，最后说不清差异来自文档还是环境，做横向对比时先统一测试条件这条原则在接口评测里同样成立。

错误码要能指向下一步

只写请求失败的文档等于没写。合格的错误码表至少要有四列：码值、含义、常见原因、处理建议。有请求 ID 的更省事，提工单时直接贴过去，对方能定位到具体一次调用。

看错误码表还有一个技巧：故意传错一个类型，看文档能不能让你在三分钟内定位。定位不了，说明这张表只是给内部人看的，外部接入者只能靠猜。

参数表比示例更能暴露水平

示例只覆盖一条顺利路径，参数表才暴露边界。看四样：哪些必填、类型是什么、取值范围、默认值。缺默认值的接口最麻烦，你不传它按什么处理，只能一个个试。

单位必须写清。超时时间写 30，是秒还是毫秒，一字之差能让请求全部失败。最大长度写 4096，是字符还是 token，直接决定你怎么切分输入。这两处是接入期最常见的返工来源。

还要看枚举值。角色字段只写三个取值，却不说明各自能不能出现在同一位置，首次调用就会报错。参数之间的互斥关系也要写，比如某个字段开了之后另一个字段失效。

流式、超时与重试写没写

这三样是上线后才暴露的坑。流式输出要看：怎么判断结束、断线后能不能续、错误发生在流中间怎么处理。文档只给非流式示例的，接入时要自己摸事件格式，半天到一天很正常。

超时和重试要看：默认超时多少、是否自动重试、重试会不会重复计费。涉及计费的接口，这一点必须写清，否则一次网络抖动可能产生多条记录，对账时说不清。

幂等设计也要看。同一个请求重复提交，是返回同一条结果还是新建一条，文档不写，你就得自己做去重，成本落在业务层。

多语言示例与 SDK 的一致性

团队用 Python，文档只有 Java 和 Node 示例，接入时就要自己翻译，翻译过程最容易漏必填字段。示例覆盖的语言越多越好，但更重要的是示例和 SDK 版本对得上。

看依赖版本：示例里写的是哪个 SDK 大版本，当前最新是哪个。差一个大版本，方法签名经常不兼容。文档带最后更新日期的，可信度高于没有日期的；日期停在两年前，基本可以判定维护不足。

安装命令也要对。示例写某个包名，实际包名已经改了，新手会卡在起步，这类小问题最能反映维护状态。

变更记录与废弃策略

接口会变。有变更记录的厂商会在改字段前给迁移期；没有的，你只能从报错里发现。看三样：记录是否按日期倒序、废弃接口是否标明替代方案和下线时间、旧版本还能用多久。

这一项对长期项目权重高，对一次性脚本几乎无所谓。判断标准很直接：这个接口你打算用超过一年吗，是就认真看，不是就跳过。

什么时候文档差也能接受

团队里有人熟悉该接口，或者已经有封装好的内部 SDK，文档差一点可以靠人补。新人多、排期紧、没人兜底，文档质量就是硬门槛，省下的评估时间会在联调阶段加倍还回去。

还有一个变量是支持渠道。有工单、有社区、有客服的，文档缺的部分能问出来；只有一页 README 的，卡住就是卡住。如果打算私有化部署，接入形态还会变，可以先看网页版与本地部署的差异，再判断文档要看到哪一层。

评估时给三项打分：跑通成本、错误可诊断性、长期维护成本。三项里有两项不及格，能力再强也不建议放进核心链路。若团队还在选型阶段，程序员选 AI 工具的判据里那套按任务拆分的思路可以直接套用。

接口文档五分钟体检

• 复制示例，只改密钥与模型名，数改动处
• 查错误码表有没有处理建议
• 查参数表的单位与默认值
• 查变更记录和废弃时间

三个实际问题

示例跑不通，先怀疑什么？按顺序查三处：SDK 版本与接口版本是否匹配、密钥权限是否覆盖该模型、网络与区域端点是否选对。三处都排除后再怀疑文档本身，避免一上来就换方案。

只有命令行示例、没有 SDK 示例，能用吗？能，但要预留封装时间，至少半天。先用命令行把请求跑通，确认参数和返回结构，再照着写代码，比直接啃 SDK 快。

免费额度够不够做评估？看限流，不看总额度。评估阶段更容易被每分钟请求数卡住，连续压测十分钟就会触发限制，这一点文档里通常写在费率页而不是接口页。