很多人拿到免费 API 的 Key 之后就卡住了：文档一堆参数不知道填哪个，curl 复制过来报错，跑通了也不知道算不算真的成功。这篇不讲协议原理，只按顺序带你走一遍第一次调用：先确认手上有什么、把最小请求拼出来、发出去、看返回值、失败时按什么顺序查。全程用通用示例，具体地址和限额到站内页面核对。
很多人拿到免费 API 的 Key 之后就卡住了：文档一堆参数不知道填哪个，curl 复制过来报错，跑通了也不知道算不算真的成功。这篇不讲协议原理，只按顺序带你走一遍第一次调用：先确认手上有什么、把最小请求拼出来、发出去、看返回值、失败时按什么顺序查。
全程用通用示例，具体接口地址、鉴权方式和限额到站内页面核对。下面的步骤照着做，能让你在一次会话里把第一次调用真正跑通，而不是「看起来像跑通了」。
动手前先把手上的四样东西对齐
发请求之前先把手里有的东西对照一遍。缺哪一样都会让你在键盘前瞎试：少了地址不知道往哪发，少了 Key 会被拒，少了模型名填不进请求体。很多新手卡住不是因为不会写代码，是因为这几样没对齐就开始复制文档。
- 接口地址
- Base URL 或完整端点，决定请求发到哪里去
- 鉴权 Key
- 证明你是谁，通常放在请求头里
- 模型名
- 告诉服务端用哪个模型来处理这次请求
- 发送工具
- curl、Postman 或一段几十行的脚本，能发 HTTPS 请求即可
- 别把文档里的示例当成你的真实值：示例里的模型名、路径往往是占位，按你实际拿到的替换
- 先确认这个免费额度是走官方还是走中转，两者在地址和 Key 的写法上经常不一样，到 /ai-nav/category/ai-api 比一比再动手
- 准备一个能发 HTTPS 请求的工具，别一上来就接进业务代码，先单独把请求跑通
- 把 Key 存在环境变量或临时文件里，别直接贴进会被提交的代码
拼出最小可用请求：路径、请求头、请求体
- 先写全四块方法（通常是 POST）、拼好的完整 URL、请求头、JSON 请求体，四块先写全再简化，不要跳步。
- 补鉴权头和内容类型头鉴权头让服务端认你，内容类型头告诉它你在发 JSON；缺内容类型头会让服务端解析不了你的请求体。
- 请求体只放最小字段用哪个模型、说什么话，先只放这两样；温度、最大长度这些先不填，跑通再调。
- URL 分开写再拼把 Base URL 和端点分开写、最后再拼，最常见的坑是路径重复或缺少版本段，分开写容易定位。
curl -X POST "完整接口地址" -H "鉴权头: 你的Key" -H "Content-Type: application/json" -d '{"model":"你拿到的模型名","messages":[{"role":"user","content":"你好"}]}'第一次跑建议只用上面这一条命令，改三个地方：完整接口地址、鉴权头、模型名。任何一处拿不准就先去站内核对，而不是猜着填。跑通之前不要加参数、不要加循环。
看返回值：怎么判断这次算真的成功了
状态码和内容是两回事。状态码是 2 开头只说明请求层面被受理了，正文里仍然可能带着业务错误。判断成不成功，两步都要看。
| 看哪里 | 正常表现 | 异常时要怀疑什么 |
|---|---|---|
| HTTP 状态码 | 2 开头 | 鉴权、地址、限额 |
| 响应里的选择项 | 有正常返回内容 | 模型名或参数不对 |
| 响应里的内容 | 有非空文本 | 安全策略拦截、长度上限 |
| 响应里的用量 | 有用量数字 | 请求被截断或没真正执行 |
- 先看 HTTP 状态码再看内容体，状态码过了不代表业务成功
- 文本为空但状态码正常，多半是被安全策略拦了或者到达长度上限，不一定是接口坏了
- 把这一次的请求和响应原样留一份，后面调参数、排错都要拿它做对比
- 状态码看不懂别硬猜，到 /ai-dict 把含义对清楚再动手改
跑通的标准不是「没报错」，而是「拿回了非空且符合预期的内容，并且用量数字对得上」。
报错时的排查顺序（照这个顺序走，别乱试）
报错的种类看着杂，其实分四层。一层一层往下走，每层只改一个地方再重发。同时改好几处，改好了你也不知道是哪一处起的作用，下次还会卡。
- 先查鉴权Key 有没有多余空格、有没有过期、请求头名字对不对；鉴权类报错先看站内状态码字典把含义对清楚。
- 再查地址把完整 URL 打印出来看，路径是不是多了一层或少了一层；免费端点有时和付费端点不是同一个。
- 然后查参数模型名拼错、字段名写错、少包一层或多包一层，是最常见的三类，改完重发别改多处。
- 最后查网络与限额本地代理、证书、频率限制都会让请求发不出去或直接被拒，这类报错和参数报错的表现完全不同。
| 报错表现 | 大概率在哪层 | 下一步动作 |
|---|---|---|
| 立刻被拒、提示身份问题 | 鉴权层 | 核对 Key 和请求头名字 |
| 提示找不到资源或路径 | 地址层 | 打印完整 URL 逐段比对 |
| 提示字段或模型无效 | 参数层 | 只改一个字段重发 |
| 超时、连不上、被限流 | 网络与限额 | 断开代理解，隔一会儿再试 |
跑通之后马上做三件事，让它能重复用
第一次跑通只是一次性的。想让它变成能天天用的东西，需要在成功的那一刻就把请求固定下来。这四件事花不了几分钟，但能省掉后面反复手拼请求的时间。
- 把这次成功的请求存成一个可重跑的脚本或命令，参数抽成变量，改一个值就能换任务
- 设一个超时时间，别让请求无限等；具体分几档到 /tools/speed-test 先量出你的延迟基线再定
- 记一条最简日志：时间、状态码、用量、耗时，这四个字段够你后面复盘慢在哪
- 别在一个请求里塞太多需求，先保证能稳定跑通单次调用，再去谈并发和批量
顺带说一个不适用的情况：如果你打算把免费额度接进正式业务，上面这套「先单次跑通」的做法只适合验证阶段，上线前还得补重试、降级和用量监控，这些不在本文范围内。
下一步想看不同提供方的接口地址、鉴权写法和免费额度差别，到站内分类页对照着挑一个先练手，比对着文档猜要快得多。→常见问题
免费 API 调用失败，先怀疑哪一步？
先看鉴权再看地址，最后看参数。鉴权类报错通常一改 Key 或请求头就好；地址类报错多半是路径拼错，把完整 URL 打印出来一对就清楚；参数类报错服务端一般会在返回里点名哪个字段，照着改就行。别同时改好几处，否则不知道是哪一步修好了。
一定要用 curl 吗，用别的工具行不行？
都行，关键是能不能自己控制请求头、请求体和完整 URL。curl 好在可以直接粘贴成命令、复制给别人复现；图形化工具好在能看结构化响应；脚本好在能参数化反复跑。建议第一次用 curl 或图形化工具跑通，之后固化成脚本。
文档里的示例能直接复制来用吗？
不能直接用，但可以当模板。示例里的模型名、端点路径、甚至字段名都可能是占位值。正确做法是把示例当成结构参考，把地址、Key、模型名换成你实际拿到的，再把请求体精简到最小，跑通之后再一点点加回参数。
