百度文心 ERNIE API 怎么接入？千帆平台密钥与 SDK 调用
数据截至 2026-07，价格与限额以各官网为准。
接入文心 ERNIE API 走的是百度智能云千帆平台，路径本身不复杂：开通千帆、创建 API Key、走 OpenAI 兼容层改两行代码就能跑通；真正需要留意的是密钥体系正处在新旧交替期——官方正在把老的”应用级 AK/SK 换 Access Token”流程往新版”直接拿 Bearer Token”上迁移，两套东西长得不一样，混用最容易出问题。
跟阿里云百炼、字节火山这些平台比，百度千帆的历史包袱更重一些：早年的文心一言、后来的千帆大模型平台、如今围绕 ERNIE 5.1/5.0/4.5 三代模型的产品线，命名和鉴权方式都经历过几轮调整。这篇按真实接入顺序走一遍，把新旧密钥怎么区分、该用哪个 base_url 这些容易卡壳的地方讲清楚。
第一步：千帆平台入口与实名认证
千帆大模型平台的官方入口是 cloud.baidu.com/product-s/qianfan_home，用百度账号登录后进控制台。跟大多数云厂商的大模型服务一样，正式发起调用之前需要完成百度账号的实名认证（企业或个人二选一），部分权益、额度可能跟实名类型挂钩——这一步没做，后面创建密钥、发起调用大概率会在某个环节被拦下来，建议先把实名走完再往下操作。
千帆平台自身不只是文心系列的入口，它同时也上架了 DeepSeek、Qwen、GLM、Kimi 等第三方模型供调用，如果你专门是为了用 ERNIE 系列模型进来的，控制台里注意别选混了模型 ID，这点后面单价那篇会展开讲，这里先按下不表。
第二步：密钥怎么拿——新旧两套体系并存
这是整个接入流程里最值得展开讲的部分，因为千帆的鉴权体系目前正处于新旧并存的过渡期，网上能搜到的教程新旧混杂，容易让人误以为哪种都行、随便抄一段代码就能跑。
推荐方式（新版，Bearer Token）：登录百度智能云控制台，进入”千帆 - 系统管理 - 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 的流程。对大多数新接入的开发者来说，这是目前最省心的路径。
旧版方式（应用级 AK/SK → Access Token）：早期文档描述的流程更绕一些——先创建一个”应用”，拿到一对 API Key 和 Secret Key，把这对凭证当成 OAuth 2.0 的客户端身份，向鉴权服务换取一枚 JWT 格式的 Access Token；这枚 Token 标准有效期只有 30 分钟，还不能自动续期，得自己写代码定时刷新。官方目前的态度是在引导用户往新版 Bearer Token 迁移，但没有查到一个明确的”旧方式几号强制下线”的截止日期，所以这里不替你下结论，只能说：如果你是新项目，直接用新版；如果手头有跑了很久的旧代码用的还是 AK/SK 换 Token 那一套，暂时能用，但值得找时间迁移一下，免得哪天官方真收紧了措手不及。
跟其他平台一样，密钥别写死在代码里、更别提交进 Git 仓库，放环境变量最省心。如果团队里有多套环境（本地、测试、生产），建议分别建 key，方便出问题时单独吊销。
第三步：OpenAI 兼容 base_url 该填哪个
千帆支持 OpenAI 兼容模式，官方文档给出的通用 Chat 场景 base_url 是：
https://qianfan.baidubce.com/v2
这里有个容易搞混的地方要单独提一句：千帆还有一套专门给 Claude Code、OpenCode、Codex 这类编程工具接入用的”Coding Plan”端点，地址是 https://qianfan.baidubce.com/v2/coding，这是另一套订阅制套餐，跟本文讲的按 token 量计费的通用推理服务是两回事，别把两个端点填反了——如果你要做的是常规的应用集成、聊天场景调用，用上面那个不带 /coding 后缀的通用地址就对了。
Python 最小调用示例
装好 OpenAI 官方 SDK（pip install --upgrade "openai>=1.0"），几行代码即可跑通：
from openai import OpenAI
client = OpenAI(
api_key="bce-v3/ALTAK-xxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", # 千帆新版 API Key
base_url="https://qianfan.baidubce.com/v2",
)
completion = client.chat.completions.create(
model="ernie-4.5-turbo-128k", # 按需替换为 ernie-5.1 / ernie-4.5-0.3b 等
messages=[
{"role": "user", "content": "你好，请自我介绍一下。"}
],
)
print(completion.choices[0].message.content)
几个细节值得说一下。第一，api_key 直接填上一步创建的新版 Bearer Token 格式密钥，不用做额外的换算处理；第二，model 字段这里填的是 ernie-4.5-turbo-128k，如果要换成旗舰款 ernie-5.1 或者性价比更高的开源款 ernie-4.5-0.3b，直接改这个字符串即可，具体各个型号贵不贵、怎么选，涉及计费细节，放在计费那篇里讲更合适；第三，千帆官方文档原文确认”通过 OpenAI SDK 调用千帆模型推理服务，只需调整 api_key、base_url、model 等参数”，但没有提供逐字的 Python 示例，上面这段是按参数说明手写的最小可用版本，正式接入前建议对照官方 Python SDK 文档再核对一遍字段名。
如果你更习惯用千帆官方的原生 SDK（PyPI 包名 qianfan，GitHub 仓库 baidubce/bce-qianfan-sdk），也可以走这条路，它支持一些 OpenAI 兼容层覆盖不到的千帆特有能力，字段命名和响应结构跟 OpenAI 兼容模式不完全一样，两条路选一条走完整，别混用。
还有一点提前打个招呼：第三方开发者社区反馈过，千帆的 OpenAI 兼容层走的是”兼容转译”而非原生 OpenAI 请求整形，个别工具接入时遇到过参数没被正确转发、报出类似”content should be string”这样的非标准错误。这类现象不算普遍，但如果你接入过程中遇到跟 OpenAI 官方行为不一致的报错，优先去查千帆官方文档当页列出的参数支持范围，而不是照抄 OpenAI 官方文档的写法硬套。
免费模型 / 近乎免费的档位怎么选
千帆这次没有查到官方页面明确列出的”新用户赠送多少 token”这类通用免费额度条款，第三方资讯口径也不一致，所以这里不给具体数字——千帆是否有新用户免费额度、额度多少，请以你登录后控制台账户页面的实时展示为准，别按别的教程里的旧数字下结论。
如果你只是想先跑通、试试效果，官方在架模型里价格最低的一档是 ernie-4.5-0.3b（ERNIE 4.5 开源 0.3B 稠密版），单价是官方在架模型里最低的档位之一，非常适合当”练手模型”用来验证接入链路对不对，等确认流程通了再切换到能力更强、价格也更高的正式模型。
顺带说一句容易被搞混的地方：百度在 2025 年中把文心大模型 4.5 系列开源了，一次性放出了从 0.3B 到数千亿参数级别的多款模型，权重可以在飞桨星河社区、HuggingFace 上下载自己部署，这跟”通过千帆 API 按 token 付费调用”是两回事——即便模型本身开源免费，走千帆的 API 通道调用依然要按计费页的单价付费，别把”模型开源”误当成”API 免费”。
常见坑 / 注意
- 别把新旧密钥体系搞混：新版
bce-v3/ALTAK-开头的密钥直接当 Bearer Token 用，旧版 AK/SK 需要额外换 Access Token 且 30 分钟就过期，两套代码逻辑完全不同，别照抄一篇过期教程里的示例硬套到新密钥上。 - 通用推理端点和 Coding Plan 端点别填反：
v2和v2/coding是两个不同的产品，计费方式也不一样。 - 密钥别硬编码进代码：放环境变量，别提交进 Git，一旦怀疑泄露，去控制台立即吊销重建。
- “模型开源”不等于”API 免费”：ERNIE 4.5 系列开源权重可以自己部署，但通过千帆 API 调用依然按量计费。
- 实名认证是前提条件：没做实名认证，创建密钥、发起调用大概率会在某一步被拦下来，建议提前走完这一步。
- OpenAI 兼容层偶有非标准报错：遇到跟 OpenAI 官方行为不一致的报错，先去查千帆官方文档当页的参数支持范围，别死磕。