文心API文档导览：在百度智能云千帆平台跑通你的第一次调用
所谓「文心API文档」并不是一个孤立页面，而是围绕百度智能云千帆大模型平台展开的一整套接口说明：从账号开通与密钥鉴权，到 ERNIE 文心系列的对话补全调用，再到错误码与配额规则，散落在文档中心的不同章节[1][2]。本页把这些章节按开发者的真实动线串起来，帮你少走弯路。
开通准备：账号、实名与应用密钥
一切调用之前的三件套接入的第一步不在代码里，而在控制台：注册百度智能云账号并完成实名认证，在控制台找到「千帆大模型平台」开通服务，然后创建一个应用，拿到 API Key（AK）与 Secret Key（SK）。这对密钥就是你调用接口的身份凭证，后续鉴权全靠它们。
新手最容易在这里犯的错，是把开通服务、创建应用、领取资源三个动作漏掉其一，结果代码报鉴权错误却以为是密钥写错了。控制台的菜单结构会随版本改版调整，具体入口位置以 cloud.baidu.com 当前页面为准[3]。
另外建议在动手写代码之前，先花十分钟通读文档中心的总览章节，弄清楚平台术语——什么是应用、什么是服务、什么是模型代号的命名规律。很多沟通成本都来自术语错位：你以为在调「文心一言这个产品」，实际上调用的是千帆平台上某个具体型号的推理服务。
鉴权换票：先用 AK/SK 换 access_token
OAuth2 客户端凭证模式千帆的对话类接口普遍采用 OAuth2 的 client_credentials 方式：拿 AK 和 SK 向令牌端点换取一个有时效的 access_token，再把 token 附在业务请求上。token 过期后需要重新获取，因此工程上应把它缓存起来、临近过期再刷新，而不是每次请求都去换票。
注意：AK/SK 等同于账户身份，只允许放在服务端环境变量或密钥管理服务中；示例中的参数名与端点以官方鉴权文档为准。
模型选型：ERNIE 家族怎么挑
效果、成本与吞吐的三角权衡文心系列在千帆平台上以多个档位并存，定位各有侧重：旗舰档推理与创作能力强，中坚档均衡耐用，轻量档主打高并发与低成本。选型的本质是在效果、成本、吞吐三个角之间找当前业务最需要的那个点，而不是盲目追新追大。
| 你的任务类型 | 建议考虑的档位 | 为什么 |
|---|---|---|
| 复杂推理、长文案创作 | ERNIE 旗舰系列（如 4.x 档） | 复杂指令遵循与多步推理能力更强 |
| 常规对话、摘要、翻译 | ERNIE 中坚系列（如 3.5 档） | 效果与成本平衡，适合大多数在线业务 |
| 分类打标、高并发轻任务 | Speed / Lite / Tiny 等轻量档 | 响应快、单价低，规模化场景更划算 |
注：各档位的具体型号名称、上下文长度与能力边界以千帆文档「模型说明」实时页面为准[1]。
发起调用：一条请求该长什么样
路径形态、消息数组与流式开关对话补全类接口的通用路径形态是把模型代号拼进 URL，再附上 access_token；请求体核心是一个 messages 数组，system 可选、user 与 assistant 交替出现，采样温度等参数按需附加。
强烈建议给 C 端产品打开 stream 流式：服务端按行解析返回的分片并逐段下发，用户看到的是逐字浮现而非长时间白屏后一次性吐出，体感差异巨大。聚合侧要注意拼接增量内容并处理结束标记。字段命名与分片格式以对应模型的文档页为准。
读懂结果与处理报错
choices 是答案，usage 是账单正常返回的结构里，choices 中是模型给出的消息内容，usage 里是本次消耗的 token 统计——前者决定功能是否正确，后者直接挂钩成本，做用量看板时要盯住它。
报错处置讲究分层：鉴权类错误应当立即中断流程并触发告警，因为它通常意味着配置出了问题，重试没有意义；限流与配额类错误适合放进重试队列做退避处理，属于正常业务波动；参数校验错误要在测试阶段就拦下来；内容安全拦截则需要产品层面准备兜底话术，而不是让用户看到一行生硬的错误码。
| 报错现象 | 高频诱因 | 处置动作 |
|---|---|---|
| 鉴权失败 / token 无效 | token 过期、AK/SK 错误或拼参遗漏 | 重新换取 token 并核对密钥归属的应用 |
| 触发限流 | 并发超过所选模型的 QPS 配额 | 指数退避重试，必要时申请提额 |
| 当日额度用尽 | 免费额度或套餐配额耗尽 | 查用量明细后扩容或次日再试 |
| 参数校验错误 | messages 角色顺序错乱、字段拼写有误 | 对照文档逐字段检查请求体 |
| 内容安全拦截 | 输入或输出触发平台风控策略 | 调整提示词并为产品预留兜底文案 |
注：返回体中的 error_code 数值与 error_msg 文案以官方错误码说明为准，排查时优先看这两个字段。
工程化技巧：上线前过一遍这份清单
从 Demo 到生产的距离- 密钥管理：SK 只进环境变量或密钥管理服务，前端永远不直连大模型接口。
- 统一封装：超时、重试、退避、熔断收敛到一个客户端层，避免散落在业务代码里。
- 日志脱敏：入参出参入库前抹掉手机号、身份证等敏感字段。
- 成本看板：基于 usage 统计 token 消耗，按业务线设预算告警。
- 双模型灰度：主备两条模型通道，单点故障时可一键切换。
- 版本锁定：升级模型档位前，用固定的评测集回归一遍再放量。
常见问题
文心 API 在哪里申请？
在百度智能云控制台开通千帆大模型平台并创建应用，即可获得 AK/SK 密钥；控制台入口以 cloud.baidu.com 当前页面为准[2]。
必须使用 access_token 吗？
公开文档主推 OAuth2 换取 token 的方式；是否存在其他鉴权形态，以官方鉴权章节的最新说明为准。
计费是怎么算的？
一般按模型档位与实际消耗的 token 用量计费，不同档位单价不同，价格随官方策略调整，以千帆价格页实时公示为准。
支持流式输出吗？
对话补全类接口普遍提供 stream 流式参数，逐段返回生成内容；具体字段与分片格式以各模型的文档页为准。
遇到报错应该先查什么？
先读返回体里的 error_code 与 error_msg，再对照官方错误码表定位类别；新手问题的大头集中在鉴权失败与触发限流两类。
只能调文心系列吗？
千帆平台的定位是大模型一站式服务平台，除 ERNIE 系列外还提供第三方与开源模型的服务能力，可用范围以平台当前列表为准[5]。