让AI接第三方API，先把这20行验证脚本跑通再动手

让 AI 帮你接第三方 API，最贵的错误从来不是写错业务逻辑，而是它凭记忆编出了一个不存在的参数。

你做完了整套集成，写了三百行适配代码，第一次真机联调时返回 422：unknown field: async_mode。真实字段叫 callback_mode。于是你把参数改掉，再跑，报错变成毫秒数必须是整数。你开始逐个改，五个参数改了一个下午。

这些错误在写代码前用 10 分钟就能全部暴露。方法是先做连通性验证，再让 AI 写业务逻辑。

为什么 AI 会编造 API 参数

训练数据里同一个 SDK 有十几个历史版本，模型学到的是它们的加权混合。它记得这个接口存在、记得大致语义，但对当前版本的字段名、嵌套层级、必填项并不可靠。加上厂商文档半年一改版，模型的记忆天然滞后。

所以正确的假设应该是：AI 写的每一个 API 调用都是未经验证的猜测。你的工作不是审阅代码，而是先用最小实验证伪。

验证脚本的设计原则

一个合格的验证脚本满足三个条件：

1. 能在 30 秒内跑完并给出明确成功/失败；
2. 只做一件事：真实调用一次，打印原始响应的完整结构；
3. 不包含任何业务逻辑，不写进主分支。

下面是我常用的骨架（Python 为例，换成任何语言的思路一样）：

import json, os, requests, time

BASE = os.environ["BASE_URL"]
H = {"Authorization": f"Bearer {os.environ['TOKEN']}", "Content-Type": "application/json"}

# 1. 参数最小化：只传文档声称的必填项
payload = {"model": "xxx", "input": "ping"}

# 2. 打印完整原始响应，不要只打 status_code
r = requests.post(f"{BASE}/v1/endpoint", headers=H, json=payload, timeout=30)
print("STATUS", r.status_code)
print(json.dumps(r.json(), ensure_ascii=False, indent=2)[:2000])

关键在于最后那行打印完整响应。AI 经常连响应结构也记错——它说返回 data.items，实际是 result.outputs。你在脚本里一眼就能看见差异，而不是在业务代码的 KeyError 堆栈里慢慢找。

四个必须验证的层面

按依赖顺序验证，前一层不过就不要往下写。

1. 认证与鉴权

先确认 token 有效、scope 够用。很多「参数错误」实际是权限不足被包装成了 400。做法：用最小请求打一次，看到 401 就停，别猜。

2. 字段级契约

把 AI 生成的所有参数逐个删一个，看是否报错。谁报错谁就是必填。这一步最笨但最有效：

把 payload 从 {} 开始，每次加一个字段，直到请求成功。成功的那个集合就是真实必填项。

顺便验证枚举值。文档说 mode: "sync" | "async"，实际可能是 "realtime" | "batch"。让 AI 列出它以为的枚举，然后一个不落地试。

3. 错误码与重试语义

这是最容易被 AI 编造的领域。它默认给你加「失败重试三次，指数退避」，但你可能接的是一个非幂等的写接口——重试会造成重复下单。

验证方法：故意传错参数，看返回码是 400 还是 500；构造超时，看服务端是否已落库。只有确认幂等，才允许加自动重试。

4. 限流与成本

发 20 个并发请求，记录返回的 429 和响应头里的速率限额字段。AI 写的代码几乎从不读这些头，但线上事故里限流被误判成「服务不稳定」的比例很高。

怎样让 AI 配合这个过程

不要让它「写集成代码」，让它「写验证脚本」。这两个任务的幻觉成本完全不同：验证脚本里错一个字段只是多跑一次，业务代码里错一个字段就是线上事故。

有效的提问方式：

「这是文档片段（粘贴官方文档原文，而不是给 URL）。请针对这四个层面各写一个独立的验证函数，每个函数打印完整响应。不要写业务逻辑，不要加异常处理之外的任何封装。字段名必须和文档逐字一致，不确定的标注 TODO。」

关键在给原文而不是给链接——大多数模型无法访问实时文档，给 URL 等于让它继续凭记忆猜。如果文档很长，只截取你要用的那一段接口定义。

验证完之后

把跑通的请求固化成一个 fixtures/ 下的样例响应文件，作为后续开发的契约。然后让 AI 基于这个真实响应写解析逻辑，而不是基于文档描述写解析逻辑。这一步能把「字段名不匹配」类的 bug 消灭在源头。

再往前走一步：把这批验证脚本改造成集成测试里的冒烟用例，在每次依赖升级时跑一次。第三方 API 会在某个平常的周二无声无息地改掉一个字段。有了这个脚本，你是第一个知道的人。

小结

AI 接 API 的核心风险是幻觉被封装进业务逻辑。解法不是更仔细地读代码，而是把不确定性前置到一次廉价的实验里：先验认证、再验字段、再验重试语义、最后验限流。10 分钟的成本，换掉一个下午的调试，还顺带得到一份可靠的集成契约。