文心AI技术文档与API说明高效生成指南
接入文心一言API时，首要任务就是获取access_token。该凭证有效期为24小时，需使用API Key与Secret Key进行交换。获取后，以Bearer Token形式向接口https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/ernie-bot-4发起请求。请求体采用JSON结构，其中messages为必填字段，temperature和top_p等属于可选配置。值得注意的是，响应中的result字段返回的是字符串而非对象——很多开发者在此处踩坑。常见错误码需牢记：110表示token过期，111表示配额不足，200001表示触发违规词。
若要高效产出一份文心AI的技术文档与API说明，帮助开发人员精准调用接口、透彻理解参数意义、规避典型错误，以下步骤值得逐一实践。
整理待文档化的API核心数据
首先搭建工作环境。登录文心AI控制台，导航至「我的应用」→「API密钥管理」，选中目标应用后点击「查看详情」。在「接口调用」选项卡中，确认当前所采用的模型ID（如ernie-bot-4）、请求URL（例如https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/ernie-bot-4）以及认证方式——必须使用Bearer Token搭配access_token。
同时将当前应用的API Key与Secret Key复制保存。后续将基于这两个值获取access_token，若信息泄露，账号可能遭受恶意调用，因此务必在本地安全环境中操作，切勿疏忽。
生成规范的API请求示例与参数说明
以下提供两种实现方式。
方法一：用官方SDK自动生成（推荐）
首先安装依赖包：pip install baidu-aip。接着新建Python脚本，导入AipNlp类，使用刚获取的API Key和Secret Key初始化client。调用client.invoke()时，设置模型参数为ernie-bot-4，传入示例messages，例如[{"role":"user","content":"你好"}]。执行后，可通过requests.Session().request拦截或启用debug日志，观察实际发出的HTTP请求结构。
方法二：手动构造cURL示例
不想装SDK？直接在终端里跑下面这条命令（记得把YOUR_ACCESS_TOKEN换成实时拿到的token）：
curl -X POST "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/ernie-bot-4?access_token=YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"解释量子纠缠"}]}'留意：cURL中的access_token有效期极短，需每30分钟刷新一次，严禁硬编码在代码中。否则请求时将返回error_code: 110，提示token已失效，白白耗费排查时间。
编制参数表与响应字段解析
第一步：提取请求体（JSON）中的所有键名
无论通过SDK还是cURL的-d参数，均可提取出messages、temperature、top_p、penalty_score、stream等字段。逐一确认各字段为必填或可选。例如stream默认为false，若设为true，响应体将切换为SSE流式格式，此时普通JSON.parse()无法解析，需替换为对应的流式处理逻辑。
第二步：给每个字段补充类型、范围、默认值和作用
以temperature为例：类型为number，取值范围0.01至1.0，数值越高输出随机性越强。若设定为0.01，输出近乎确定性，非常适合规则校验等要求稳定结果的场景。
第三步：解析典型成功响应结构
正常响应将包含id、object、created、result、usage五个一级字段。特别注意——result字段返回的是字符串而非对象。不少开发者误以为其下还有choices等子字段，导致前端解析时报错，此问题需提前向团队强调。
补充错误码对照表与调试建议
访问文心AI官方文档的「错误码说明」页面，筛选出高频错误项：110（access_token过期）、111（配额不足）、112（请求超时）、200001（输入内容含违禁词）、200002（输入过长）。将上述五项整理为两列表格：错误码 | 含义 | 建议操作。
特别提示：当返回200001时，控制台日志不会显示具体触发了哪个敏感词。此时无法盲目猜测，应改用「敏感词检测API」对content字段进行预检。否则反复调试也难以定位问题根源。