百度千帆大模型平台调用：API Key 配置与 Python 请求示例

知识分享

2026-10-31 16:00

15 阅读

百度千帆使用教程的核心是三步：在控制台创建应用拿到 API Key 和 Secret Key，用它们换取 access_token，再拿 access_token 去调用具体的模型接口。
下面按顺序讲清楚每一步在哪个页面操作、代码怎么写、失败时先查什么。

先确认账户状态和要调用的模型

动手之前先确认两件事，否则后面的代码一定跑不通。

百度智能云账户已完成实名认证，且千帆大模型平台已开通。未开通时控制台会提示先开通服务，按页面引导操作即可。
明确你要调用哪个模型。千帆平台上不同模型的接口地址和参数名可能不同，本文以平台提供的对话类接口为例，实际调用前在控制台的“在线调试”或接口文档里核对当前模型对应的 endpoint。

API Key 和 Secret Key 只属于当前应用，不要用错项目下的密钥。

创建应用并拿到密钥

登录百度智能云控制台，进入千帆大模型平台，在应用管理相关页面新建一个应用。
创建完成后页面会展示该应用的 API Key 和 Secret Key。

这两个值只展示一次的情况很常见，建议立即保存到本地密码管理器或服务器的环境变量文件，不要写死在代码里提交到 Git。

把密钥放到服务器环境变量中，例如在 ~/.bashrc 或项目 .env 里追加：

export QIANFAN_API_KEY="你的API_Key"
export QIANFAN_SECRET_KEY="你的Secret_Key"

执行 source ~/.bashrc 后，用 echo $QIANFAN_API_KEY 确认变量已生效。

用密钥换取 access_token

千帆的接口鉴权走的是 access_token 机制：先用 API Key 和 Secret Key 向鉴权地址请求 token，再在业务请求里带上这个 token。
token 有有效期，过期后需要重新获取，所以代码里不要假设它永久有效。

下面是一个获取 token 的 Python 示例，依赖 requests，可用 pip install requests 安装：

import os
import requests

def get_access_token():
    url = "https://aip.baidubce.com/oauth/2.0/token"
    params = {
        "grant_type": "client_credentials",
        "client_id": os.environ["QIANFAN_API_KEY"],
        "client_secret": os.environ["QIANFAN_SECRET_KEY"],
    }
    resp = requests.post(url, params=params, timeout=10)
    resp.raise_for_status()
    data = resp.json()
    if "access_token" not in data:
        raise RuntimeError(f"获取 token 失败: {data}")
    return data["access_token"]

预期结果是返回一个 JSON，其中包含 access_token 和 expires_in 字段。
如果没有 access_token，先看返回里的 error 和 error_description，常见原因是密钥填错或应用未开通对应权限。

发送一次对话请求并验证结果

拿到 token 后，把它拼到业务接口地址的查询参数里。
接口地址和请求体字段要以你所用模型的文档为准，示例结构如下：

import requests

def chat(token, user_text):
    url = "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions"
    headers = {"Content-Type": "application/json"}
    payload = {
        "messages": [
            {"role": "user", "content": user_text}
        ]
    }
    resp = requests.post(
        url,
        params={"access_token": token},
        headers=headers,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

token = get_access_token()
result = chat(token, "用一句话说明什么是对象存储")
print(result)

运行后如果返回体里出现 result 或 choices 之类的生成内容字段，说明链路已打通。
不同模型返回字段名可能不同，以实际返回为准，不要硬套示例里的字段名去取值。

常见报错怎么排查

鉴权失败、token 无效这类报错，按下面顺序查：

确认 client_id 和 client_secret 与环境变量一致，没有多余空格或换行。
确认 token 没有过期，重新调用 get_access_token() 再试。
确认请求的接口地址与当前模型匹配，换模型后地址或参数可能需要调整。

返回限流或配额相关错误时，先看控制台应用页面的调用量统计和配额说明，确认是否超出当前套餐限制；
不要靠重复重试硬扛，容易把问题放大。

请求超时或连接失败，优先在服务器上执行 curl -I https://aip.baidubce.com 检查出网和 DNS，再排查代理或防火墙设置。

上线前值得注意的几点

密钥不要进代码仓库。用环境变量或配置中心管理，泄露后立即在控制台重置。
token 做缓存。按 expires_in 提前刷新，避免每次请求都换 token 增加延迟和失败点。
给请求加超时和日志。记录状态码和错误信息，出问题时能快速定位是鉴权、网络还是模型侧返回。
先小流量验证。接入业务前用固定测试语句跑通，再逐步放量，避免配额被意外耗尽。

按以上步骤走完，你就能完成百度千帆从创建应用到代码调用的基本闭环。
真正容易卡住的不是代码本身，而是密钥权限、接口地址与模型是否匹配这两处，排错时优先从这两点入手。

阿里云百炼怎么用：API Key 配置与 Python 调用示例

腾讯混元API调用实操：密钥配置与Python请求示例