百度API免费接口调用示例

很多人拿到百度免费接口的 Key 之后，第一次调用能通，一放进项目就开始超时、报错、被限流。问题通常不在代码语法，而在鉴权拼接、超时设置、并发节奏和失败兜底这几个环节。这篇按「申请 → 首个请求跑通 → 接进工程 → 上线前检查」的顺序走一遍，每一步都给可执行的判断标准，具体价格、额度、可用模型版本请到站内页面核对当时数字。

很多人拿到百度免费接口的 Key 之后，第一次调用能通，一放进项目就开始超时、报错、被限流。问题通常不在代码语法，而在鉴权拼接、超时设置、并发节奏和失败兜底这几个环节。这篇按「申请 → 首个请求跑通 → 接进工程 → 上线前检查」的顺序走一遍，每一步都给可执行的判断标准。价格、额度、可用接口档位这类会变的数字，请到站内页面核对当时的值。

写作前提说清楚：本文只讲流程和判断标准，不承诺任何接口永久可用、也不保证免费额度够你用。凡是涉及「多少钱、多少量、多少 QPS」的地方，一律以站内页面展示的实时信息为准，因为免费额度随时可能调整，写死在文章里的数字第二天就可能是错的。

一、申请与拿 Key：先确认你能拿到什么权限

第一步不是写代码，而是搞清楚你手里这串 Key 到底能调什么。控制台里通常要「建应用 → 勾选需要的接口 → 拿 Key」这一整条链路，缺一步就是权限不足。有些接口是两段式鉴权，Key 不能直接当 Bearer Token 塞进请求头，必须先用它换一个临时的 access token 再调业务接口，这个差别会直接决定你的代码结构。

第二件事是分清「免费额度」和「永久免费」。前者通常是每月送的额度，月底归零，下个月重新给；后者往往限 QPS 和每日调用量，用超了直接拒绝。两种情况的工程做法完全不同：额度型要做用量监控和月底告警，永久免费型要做限流排队和降级。判断不准的时候，别猜，去站内官方 API 资料页看当时的说明。

• 建应用时就把需要的接口勾齐，后补权限往往要重新走审核，测试会卡住
• 测试和线上别共用同一个 Key，单独建一个测试应用，出问题时能一刀切停掉
• 拿到 Key 先确认它是「一段式」还是「两段式」鉴权，这决定你要不要写换 token 的逻辑
• 到站内官方 API 页面核对这家平台当前的接口口径与档位，再决定要不要写进项目

二、跑通第一个请求：最小可运行示例的四个检查点

很多人卡在这里，其实不是代码问题，是请求本身没拼对。先用最小 body 跑通一个请求，再逐步加字段，这样出错时你只需要怀疑一个变量。四个最容易错的地方：请求地址、鉴权参数放的位置、Content-Type、以及接口要求的必填字段。这四项错一个就是 4xx，而且报错信息经常不告诉你错在哪一项。

第二个习惯是：把返回体原样打印出来，别只判断 HTTP 状态码。不少免费接口的失败是「HTTP 200 包着一个业务错误码」返回的，你只看状态码会以为成功，结果数据是空的。业务错误码要和接口文档的错误码表对着看，认不出来的码先记下来再查。

# 只做一件事：把完整返回打出来，不解析
curl -s -X POST '接口地址' \
  -H 'Content-Type: application/json' \
  -d '{"最小必填字段":"值"}' | tee resp.json
# 然后单独看这个文件，别在管道里做判断
cat resp.json

1. 先确认链路延迟首字慢不一定是你的代码问题，先到站内测速工具量一下到该域名的延迟基线，再判断是代码慢还是链路慢。
2. 用最小请求跑通只填必填字段，其他全不带，通了再加字段。每加一个字段跑一次，定位到具体字段最省时间。
3. 存下可复现片段把这次成功的完整参数存成一个 curl 或脚本文件，后面所有排错都拿它做对照，避免「这次和上次哪里不一样」这种问题。
4. 对照错误码表把返回里的业务错误码对着文档错误码表过一遍，认不出的记下来，别猜意思。

三、接进工程：超时、并发与降级怎么设

跑通不等于能用。免费接口在高峰期会排队，你如果只设一个超时值兜全部，读取超时给太短，就会大面积误报失败，日志里全是超时，其实是接口在排队而不是真挂了。正确做法是分两档：连接超时短一点，快速发现连不上的问题；读取超时长一点，给接口留排队时间。两个值各设多少，按你测出来的链路延迟来定，不要抄别人的。

并发也别按你机器的能力设，要按接口侧允许的 QPS 设，并在客户端主动排队。免费档的限流阈值通常比付费低不少，你本地开一百个协程同时打，结果就是一批成功一批被拒，看起来像随机故障，其实是你在超发。

• 重试前先判断错误类型，鉴权失败、参数错误这类重试一百次也没用，直接告警
• 重试必须带退避，别原地死循环，否则限流会雪上加霜
• 降级方案提前想好：主接口失败时是重试、换备用接口，还是直接返回兜底结果
• 兜底结果要能被下游识别，别把兜底数据当真实数据用

四、日志与观测：让每次失败都能复盘

日志的目标不是「记录调用」，而是「出问题时能一眼看出是哪一类失败」。所以每次调用至少记这几样：时间、接口名、请求参数摘要、HTTP 状态码、业务错误码、耗时、是否重试。缺了耗时，你不知道是慢还是错；缺了业务错误码，你分不清是限流还是参数问题。

再进一步，把请求 ID 或者自己生成的 trace ID 打进去，跨服务排查时能串成一条链路。免费接口的额度消耗也值得单独记一笔，不然到月中突然不通，你很难第一时间想到是额度用完了。

上线前再写一批固定用例做回归，改完参数或者换接口版本后跑一遍，看结论有没有变。用例不用多，覆盖主流程和几个已知边界就够，关键是能重复跑、能对比前后结果。

五、常见坑与不适用的情况

鉴权失败最常见的三类原因是签名算错、时间戳过期、编码不一致。排查就按这个顺序：先确认签名拼接方式，再确认服务器时间和本地时间有没有偏差，最后确认参数编码和文档要求是否一致。这三步走完，大部分 4xx 都能定位。

接口返回结构和文档对不上时，先别怀疑自己代码，去看是不是平台做过灰度或者版本切换。站内的服务状态页可以帮你确认是不是服务侧的问题，别自己闷头改半天。

• 免费接口不适合承载有稳定性承诺的核心链路，它对 SLA 没有保证
• 延迟敏感或者调用量大的业务，免费档的限流会让你反复踩坑，该评估付费档或换接口
• 免费额度、限流阈值、可用接口档位都会变，用之前到站内页面核对当时的数字
• 别人的示例代码只能参考结构，具体参数要以你拿到的权限和文档为准

跑通一次靠运气，能稳定跑靠的是超时、并发、降级和日志这四件事都提前想过。