文心 API 报错排查：鉴权与模型名两大类

2026-07-27

数据截至 2026-07，价格与限额以各官网为准。

在千帆平台上调文心 ERNIE API，跑不通的原因高度集中：不是密钥这一层出问题，就是模型 ID 写错了。真正复杂的业务参数问题反而很少见。所以排查时不要一上来就怀疑自己的请求体结构，先把”密钥是哪一套""模型名从哪儿抄的”这两件事确认掉，多数人到这一步问题就已经解决了。

有个很常见的误解值得先点破：不少人看到调用失败，第一反应是”是不是免费额度用完了""是不是要充值”。千帆平台是否有新用户免费额度、额度是多少，请以控制台账户页面实时展示为准，这篇不给数字；但从报错形态上讲，余额相关的问题和鉴权失败、模型不存在是完全不同的提示，不会混在一起。把提示原文认真读一遍，比凭直觉猜要快得多。

排查顺序：从外往里剥三层

不管报的是什么，建议固定按这个顺序过一遍，能避免绝大部分无效折腾：

网络层：请求到底有没有打到千帆的端点。如果报的是连接超时、DNS 解析失败、连接被拒绝这类，问题在网络或者 base_url 域名写错，跟密钥、模型名都没关系。百度千帆的服务在国内，正常网络环境下连通性一般不是瓶颈，但如果你在容器、内网代理、公司出口白名单这类环境里跑，先确认端点是可达的。
鉴权层：端点通了，但服务端说你没身份或者身份无效。这一层的提示通常围绕 token 无效、token 过期、无权限访问这几个意思展开，具体的错误码数字与含义请对照千帆官方错误码文档，不同接口版本的码值不一样，不要拿别人博客里贴的旧码表当标准。
参数层：身份认了，但请求内容有问题。模型 ID 不存在、消息结构不符合要求、超出上下文窗口都归在这一层。

这三层是有先后依赖的，跳着查会浪费时间。比如你在鉴权都没过的时候去改模型名，改一百遍也没用。

鉴权类第一坑：两套密钥体系混着用

这是千帆平台目前最容易让人栽跟头的地方，因为它正处在新旧并存的过渡期（2026-07 现状）。

新版（推荐）：在百度智能云控制台的千帆 - 系统管理 - API Key 页面（console.bce.baidu.com/qianfan/ais/console/apiKey）点”创建 API Key”，拿到的密钥形如 bce-v3/ALTAK-xxxx/xxxx。官方原文说明这个 API Key 永久有效，可以直接放进 HTTP 请求头 Authorization: Bearer <api_key>，不需要再走一遍 OAuth 2.0 换取 Access Token 的流程。

旧版：早期文档描述的是另一套流程——先创建一个”应用”，拿到一对 API Key / Secret Key，把它们当作 OAuth 2.0 的客户端凭证，去鉴权服务换一个 JWT 格式的 Access Token，这个 Access Token 标准有效期 30 分钟且不可续期，需要你自己实现刷新逻辑。官方正在引导用户往新版方式迁移，但没有核实到官方公布的”旧方式强制下线截止日期”，所以不能断言旧方式已经废弃，具体以千帆文档当次页面为准。

混用会出现哪些典型症状：

拿旧版的 API Key（不是 bce-v3/ALTAK- 开头的那种）直接塞进 Bearer 头。旧版那对 AK/SK 是用来换 token 的凭证，本身不是访问令牌，直接当 Bearer 用必然被拒。
拿换来的 Access Token 一直用不刷新。旧流程的 token 只有 30 分钟寿命，本地调试时刚拿到能跑，隔一顿饭回来就失效了。很多”昨天还好好的今天就不行”其实是这个原因，不是平台抽风。
在新版体系下还去写 token 刷新代码。新版 API Key 永久有效，多写的这套刷新逻辑不但没用，还可能因为拼错请求把好好的密钥弄成无效值。

排查动作很简单：先看你手里那串密钥是不是以 bce-v3/ALTAK- 开头。是，就走新版 Bearer 直连，把所有刷新逻辑删掉；不是，那你手里的是旧版凭证，要么补齐换 token 的流程，要么干脆去控制台创建一把新版 API Key，一劳永逸。

鉴权类第二坑：权限范围与关联 appid

创建新版 API Key 的时候，控制台会让你选权限：可以给”全部权限”，也可以给”自定义权限”，比如只勾模型服务权限。这里有两个衍生问题：

如果你按最小权限原则只勾了一部分，后来又想调别的能力，就会撞上”有身份但没权限”的报错。这类报错和”密钥无效”是两回事，提示措辞通常也不同，读清楚就不会误判成密钥坏了。
千帆文档里提到 API Key 需要关联 V2 版本应用的 appid 之后才能用于 v2 端点调用。如果这一步没做完，表现出来的也是鉴权环节过不去。

另外，使用前提是百度账号完成了实名认证（企业或个人），部分权益和额度可能跟实名类型挂钩。实名没走完就在那儿反复重建密钥，是纯粹的白费力气。

鉴权类第三坑：base_url 填错，尤其是 coding 那条

千帆的 OpenAI 兼容层有两个不同的 base URL，用途不一样：

通用 Chat 场景：https://qianfan.baidubce.com/v2
编程 / Coding 场景专用：https://qianfan.baidubce.com/v2/coding，完整的 chat 接口路径是 .../v2/coding/chat/completions。这是另一套订阅制套餐（Coding Plan），跟按 token 计费的通用推理服务是两个产品。

这两个地址长得太像，复制粘贴的时候极易串。串了之后的表现不一定是干脆的 404，也可能是鉴权层直接把你挡掉——因为你的账户可能根本没订阅 Coding Plan，或者反过来，你订的是 Coding Plan 却在往通用端点上打。判断方法：你是给自己的应用做通用对话调用，就用 /v2；你是在给 Claude Code、OpenCode、Codex 这类编程工具配千帆的 Coding Plan，才用 /v2/coding。

还有一个更朴素的错法：从别的平台的示例代码改过来时漏改 base_url，拿着千帆的密钥去撞别家的端点。这种情况报的是鉴权失败，但根源在 URL 上，很容易查错方向。改完记得把 base_url 打印出来看一眼实际值。

模型名类第一坑：ID 从哪儿抄

千帆当前在架的文心系列模型 ID，可以对照官方模型列表页确认。常用的几个是：

模型	API 模型 ID	上下文窗口
ERNIE 5.1（当前旗舰）	`ernie-5.1`	128K
ERNIE 5.0	`ernie-5.0`	128K
ERNIE 5.0 Thinking Preview	`ernie-5.0-thinking-preview`	128K
ERNIE 5.0 Thinking Latest	`ernie-5.0-thinking-latest`	128K
ERNIE 4.5 Turbo 128K	`ernie-4.5-turbo-128k`	128K
ERNIE 4.5 Turbo 32K	`ernie-4.5-turbo-32k`	32K
ERNIE 4.5 Turbo VL（视觉多模态）	`ernie-4.5-turbo-vl` / `ernie-4.5-turbo-vl-32k`	128K / 32K
ERNIE 4.5 8K	`ernie-4.5-8k`	8K
ERNIE 4.5 开源 0.3B 稠密版	`ernie-4.5-0.3b`	128K
ERNIE Speed Pro 128K	`ernie-speed-pro-128k`	128K
ERNIE Lite Pro 128K	`ernie-lite-pro-128k`	128K
ERNIE Character 8K（角色扮演场景）	`ernie-char-8k`	8K

从这张表能直接看出几个高频错法：

把上下文档位后缀吃掉。ernie-4.5-turbo-32k 和 ernie-4.5-turbo-128k 是两个不同的模型 ID，不是同一个模型加了个参数。写成 ernie-4.5-turbo 这种”看起来更通用”的名字，服务端不认。
自己拼版本号或日期后缀。千帆的模型 ID 是列表页上写死的字符串，不要凭印象往后面接日期、接 -latest。注意 ernie-5.0-thinking-latest 里的 latest 是这个 ID 本身的一部分，不是一个可以随便往别的模型后面挂的通配后缀。
大小写和分隔符。这些 ID 全是小写加连字符，抄的时候别被文档排版里的空格、中文破折号带偏。
抄了几个月前的教程。百度这边模型迭代和命名调整都发生过，旧文章里的模型名可能已经不在架。稳妥做法是每次接新模型时去官方模型列表页复制一次，而不是从记忆或者搜索结果摘要里拿。

模型名类第二坑：把开源版当成 API 模型 ID

2025-06-30 百度开源了文心大模型 4.5 系列，一次性开放 10 款模型，参数梯度从 0.3B 稠密版一直覆盖到 300B 以上的 MoE，采用 Apache 2.0 协议，支持学术研究与商业使用，权重可以在飞桨星河社区、HuggingFace 等平台下载后自行部署。

这件事本身很好，但带来一个高频混淆：开源权重自己部署，和通过千帆 API 按 token 调用，是两条完全不同的路。 具体后果有两种：

你在 HuggingFace 上看到某个开源仓库的名字，直接把它当成 model 参数往千帆请求里填，结果自然是模型不存在。千帆的模型 ID 只能从千帆模型列表页取。
你以为”模型都开源免费了，API 调用应该也不要钱”。即便模型开源，通过千帆 API 调用仍然按平台的计费规则走。想要真正免费，那得是你自己把权重下下来部署在自己的机器上，那条路的成本是算力和运维，不是 token。

顺带说一句，ernie-4.5-0.3b 是官方在架模型里价格最低的档位之一（输入 0.0001 元/千 tokens、输出 0.0004 元/千 tokens，约合 0.1 / 0.4 元每百万 tokens），拿来跑通链路、验证鉴权和请求格式很合适，但它并不是 0 元。等链路确认没问题了再换回你真正要用的型号，比一上来就用旗舰模型反复试错省钱。

另外还有一个产品层面的区分要交代清楚：官方历史上说过”免费向用户开放”，那指的是文心一言官网 / App 端这个面向消费者的对话产品，跟千帆 API 按量计费是两个不同的产品和计费体系。看到”文心免费”的说法，先确认它说的是哪一个。

兼容层转译带来的”非标准报错”

千帆的 OpenAI 兼容层走的是”兼容转译”而不是原生的 OpenAI 请求整形。这句话的实际含义是：你按 OpenAI SDK 的写法发出去的请求，会被平台侧翻译成千帆自己的格式，翻译过程中不是所有字段都有一一对应关系。

带来的现象是，部分 provider 专属参数可能不会被转发；有第三方工具（Roo-Code、Cline）的使用者反馈过 content should be string 这类兼容性报错。这些是 GitHub issue 上的交叉印证，不是官方文档的一手声明，也没有核实是否已经修复，这里只作为已知现象说明。

处理思路：遇到看起来不像标准 OpenAI 报错的提示，优先去查千帆官方文档里的参数支持范围，而不是去翻 OpenAI 的文档。 特别是当你的 content 传的是数组形式（多模态消息结构）而不是纯字符串时，先确认目标模型和兼容层是否支持这种结构。如果确实需要用到千帆特有的能力，官方还提供独立的原生 Python SDK（PyPI 包名 qianfan，仓库是 github.com/baidubce/bce-qianfan-sdk），绕开兼容层反而更省事。

一份可以照着走的排查清单

跑不通的时候，按这个顺序过，一般五分钟内能定位：

把 base_url 打印出来，确认是 https://qianfan.baidubce.com/v2（或者你确实要用的 /v2/coding），而不是别家平台的地址。
把密钥打印出来看开头（别打印全串，也别提交进仓库），确认是不是 bce-v3/ALTAK-。是新版就走 Bearer 直连，不要有刷新逻辑；不是就去控制台建一把新的。
确认百度账号实名认证已完成、API Key 的权限范围包含模型服务、并且已关联 V2 版本应用的 appid。
把 model 换成 ernie-4.5-0.3b 这种低价档位跑一次最小请求。能通，说明鉴权链路没问题，问题在你原来的模型名或者请求参数上；还不通，说明问题仍在鉴权层。
模型名去官方模型列表页当场复制，别从旧教程抄，注意 32k / 128k 这类后缀是 ID 的一部分。
报错文案看起来不像标准 OpenAI 风格的，去查千帆文档的参数支持范围，或者改用官方原生 qianfan SDK 试一次。
以上都排除了，再去看消息结构、上下文长度、并发这些业务侧因素。

局限和不适用的场景

这篇讲的是 OpenAI 兼容层这条路径上的常见问题。如果你走的是千帆原生 SDK、或者用的是 Coding Plan 订阅制套餐，报错形态和排查点会有差异，请以对应文档为准。计费相关的具体条款、免费额度是否存在及数额、旧版鉴权方式的官方下线时间表，这些都以千帆官网计费页和控制台实时页面为准，本文不做定量断言。

另外，官方历史上做过整体的刊例价调整，说明价格是会变的。如果你的排查涉及”是不是余额不够”，请直接看控制台的实时账户页面，不要拿任何文章里的数字（包括这篇引用的）当作当前生效值。

小结

千帆上调文心 API 的报错，八成落在两类：密钥体系新旧混用，和模型 ID 抄错。前者的判断标志只有一个——密钥是不是 bce-v3/ALTAK- 开头，是就走永久有效的 Bearer 直连，别写刷新逻辑；后者的解法也只有一个——模型名从官方模型列表页当场复制，不从旧教程和记忆里拿。排查顺序固定为网络、鉴权、参数三层往里剥，用 ernie-4.5-0.3b 这种低价档跑最小请求来切分问题归属，是性价比最高的一招。最后记住开源权重和 API 调用是两条路，别把两边的名字和计费混在一起。