文心一言API调用及旧版接口查询指南-牛站云

文心一言曾通过百度智能云千帆大模型平台向开发者提供 API 能力，早期开发者通常通过 API Key、Secret Key 获取 access_token，再调用 ERNIE-Bot、ERNIE-Bot-turbo 等模型接口。随着千帆平台持续升级，API 鉴权和调用方式也发生了变化，目前官方文档已经将千帆 ModelBuilder 作为统一的大模型服务与开发平台，提供模型调用、推理服务 API、SDK 等能力。百度智能云+1

因此，如果需要接入“文心一言 API”，不能简单按照网上较早的代码直接复制使用。尤其是搜索到 aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/... 这类地址时，应先判断它属于旧版调用方式还是当前仍然适用的接口。

一、文心一言 API 的调用方式经历了哪些变化

早期的文心一言 API 主要依托千帆大模型平台提供。开发者创建千帆应用后，可以获得 API Key 和 Secret Key，然后通过 OAuth 接口换取 access_token，最后携带 Token 请求具体模型接口。百度早期公开的接入资料就是按照这一流程设计的。千帆云助手+1

典型流程可以概括为：


创建千帆应用
    ↓
获取 API Key / Secret Key
    ↓
请求 OAuth Token
    ↓
获得 access_token
    ↓
调用具体模型 API
    ↓
获取模型生成结果

早期接口的一个典型 Token 地址为：


https://aip.baidubce.com/oauth/2.0/token

请求时需要携带：


grant_type=client_credentials
client_id=API_KEY
client_secret=SECRET_KEY

获取 Token 后，再将其作为参数传递给模型接口。

需要注意的是，这种方式主要对应历史版本的文心大模型 API 接入方案。百度后续推出了千帆 ModelBuilder API V2，并采用 Bearer Token 等方式进行鉴权，同时提供了 OpenAI SDK 兼容能力。百度智能云+1

二、旧版文心一言 API 接口在哪里

如果维护的是早期项目，或者代码中已经存在文心一言 API 调用逻辑，可以重点检查以下接口。

1. 获取 access_token 接口

旧版 Token 获取接口通常为：


POST https://aip.baidubce.com/oauth/2.0/token

参数类似：


grant_type=client_credentials
client_id=你的API Key
client_secret=你的Secret Key

早期资料显示，获取到的 access_token 用于后续模型 API 的身份认证。千帆云助手+1

例如 Python 可以写成：

Python
运行
import requests

API_KEY = "你的API_KEY"
SECRET_KEY = "你的SECRET_KEY"

url = "https://aip.baidubce.com/oauth/2.0/token"

params = {
    "grant_type": "client_credentials",
    "client_id": API_KEY,
    "client_secret": SECRET_KEY
}

response = requests.post(url, params=params)
data = response.json()

access_token = data.get("access_token")
print(access_token)

实际项目中不要把真实的 API Key 和 Secret Key 直接写进源代码，更不要提交到 Git 仓库。

2. 旧版聊天接口

早期文心一言 API 中比较常见的调用地址为：


https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions

调用时需要追加：


?access_token=你的ACCESS_TOKEN

百度早期官方社区示例也使用过这一调用形式。千帆云助手+1

请求体通常采用消息列表：

JSON
{
  "messages": [
    {
      "role": "user",
      "content": "请介绍一下人工智能"
    }
  ]
}

Python 调用示例：

Python
运行
import requests

access_token = "你的ACCESS_TOKEN"

url = (
    "https://aip.baidubce.com/"
    "rpc/2.0/ai_custom/v1/wenxinworkshop/"
    "chat/completions"
)

params = {
    "access_token": access_token
}

payload = {
    "messages": [
        {
            "role": "user",
            "content": "请介绍一下人工智能"
        }
    ]
}

response = requests.post(
    url,
    params=params,
    json=payload,
    timeout=60
)

print(response.json())

需要特别注意，旧版接口并不意味着所有历史模型名称、URL 和参数现在仍然有效。模型服务会随着平台版本变化进行调整，因此新项目不建议仅凭旧文章中的接口地址进行开发。

三、旧版 ERNIE-Bot 和 ERNIE-Bot-turbo 怎么查询

很多旧项目代码中会出现类似：


ERNIE-Bot
ERNIE-Bot-turbo
eb-instant

这样的模型或接口名称。

早期千帆文档将 ERNIE-Bot 和 ERNIE-Bot-turbo 分别作为预置服务提供，开发者通过不同 URL 调用对应模型。百度当时的接口指南也明确区分了这些服务。千帆云助手

例如历史代码中可能看到：


/wenxinworkshop/chat/completions

或者：


/wenxinworkshop/chat/eb-instant

这类地址对于理解旧项目非常有价值，但不能把它们直接等同于当前平台的推荐接口。

如果你的目标是“查找一个老项目到底调用了哪个文心模型”，建议按照以下顺序排查：


代码中的 URL
      ↓
接口路径中的模型标识
      ↓
项目配置文件中的模型名称
      ↓
旧版千帆控制台配置
      ↓
对应版本 API 文档

比单纯搜索“文心一言 API 地址”更加可靠。

四、当前项目应该优先关注千帆 ModelBuilder

目前百度智能云将千帆大模型服务与开发平台 ModelBuilder 定位为面向企业开发者的大模型开发和服务运行平台，平台不仅包含文心系列模型，也提供其他模型、模型调用、推理服务 API 和 SDK 等能力。百度智能云

这意味着新项目在设计 API 接入方案时，应优先查看当前千帆 ModelBuilder 文档，而不是直接套用 2023 年、2024 年的文心一言接入教程。

官方文档目前提供了以下主要内容：

模型调用
推理服务 API
平台 OpenAPI
SDK 参考
平台计费
最佳实践
常见问题

具体接口应以当前官方文档中的模型和版本为准。百度智能云

五、千帆 API V2 与 OpenAI SDK 兼容

对于已经使用 OpenAI SDK 的项目，千帆平台提供了更方便的迁移方式。

百度智能云曾介绍，千帆大模型平台 API V2 支持 Bearer Token 鉴权，并可以兼容 OpenAI SDK。百度智能云

这种方式对于已有 AI 应用尤其方便，因为项目原本可能已经采用类似：

Python
运行
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL"
)

的架构。

迁移到千帆后，主要需要根据当前官方文档调整：


API Key
Base URL
模型名称

百度千帆社区的 OpenAI SDK 调用示例也展示了通过 api_key、base_url 和 model 三项配置调用千帆推理服务的方式。千帆云助手

这种架构还有一个实际优势：业务代码可以将模型调用层抽象出来。

例如：

Python
运行
def chat(client, model, message):
    response = client.chat.completions.create(
        model=model,
        messages=[
            {
                "role": "user",
                "content": message
            }
        ]
    )

    return response.choices[0].message.content

业务层只负责传入模型和消息，而不需要把具体 HTTP 请求细节散落在整个项目中。

六、为什么网上的旧版接口代码经常调用失败

搜索文心一言 API 时，经常会遇到“代码看起来完全正确，但是请求返回错误”的情况。

最常见的原因并不是 Python、Java 或 Node.js 语法问题，而是接口版本发生了变化。

模型名称已经发生变化

旧教程可能使用：


ERNIE-Bot
ERNIE-Bot-turbo

而当前平台中的可用模型、模型 ID 和调用方式可能已经不同。

因此不要仅凭：

Python
运行
model = "ERNIE-Bot"

判断模型仍然可用。

应当进入当前千帆模型列表确认实际模型标识。

鉴权方式发生变化

旧版项目常见：


API Key
+
Secret Key
↓
access_token

而较新的 API V2 方案可以使用 Bearer Token 鉴权。百度官方资料已经明确介绍了 V2 对 Bearer Token 和 OpenAI SDK 的支持。百度智能云

因此，如果项目迁移到新版 API，不能简单地把旧版 access_token 参数继续拼接到 URL 后面。

接口 URL 发生变化

例如历史项目中可能出现：


aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/

而新版服务可能采用不同的 API 地址和版本路径。

判断接口是否还能使用时，应以当前官方 API 文档为准，而不是以搜索引擎中排名较高的旧博客为准。

七、Java 调用文心一言 API 的基本思路

Java 项目不一定需要专门的 SDK，HTTP 客户端同样可以完成 API 调用。

例如使用 Java 11 HttpClient：

Java
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("API_URL"))
        .header("Content-Type", "application/json")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .POST(HttpRequest.BodyPublishers.ofString("""
            {
              "messages": [
                {
                  "role": "user",
                  "content": "介绍一下人工智能"
                }
              ]
            }
            """))
        .build();

HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

这里的 API_URL、Token 类型以及请求参数需要按照当前使用的千帆 API 版本进行替换。

如果维护的是旧版系统，则应按照旧版接口的认证方式处理；如果开发的是新系统，则应直接根据当前 ModelBuilder API 文档实现。

八、Node.js 调用时需要注意什么

Node.js 项目通常可以使用 fetch、Axios 或 OpenAI SDK。

如果使用新版兼容 OpenAI 的方式，可以将模型调用封装为独立模块：

JavaScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QIANFAN_API_KEY,
  baseURL: process.env.QIANFAN_BASE_URL
});

const response = await client.chat.completions.create({
  model: process.env.QIANFAN_MODEL,
  messages: [
    {
      role: "user",
      content: "请介绍一下文心系列模型"
    }
  ]
});

console.log(response.choices[0].message.content);

推荐将敏感配置放入环境变量：


QIANFAN_API_KEY=******
QIANFAN_BASE_URL=******
QIANFAN_MODEL=******

这样可以避免 API 密钥直接出现在源代码中。

早期百度千帆开发资料也曾提供 Node.js 接入文心一言 API 的实践方案，因此对于旧项目维护者而言，Node.js 同样可以通过 HTTP API 方式完成调用。千帆云助手

九、如何快速判断一个文心 API 是否属于旧版接口

可以从三个方面判断。

第一，看域名和路径。

如果代码中出现：


aip.baidubce.com

以及：


wenxinworkshop

等旧版路径，可以进一步检查项目创建时间和对应文档版本。

第二，看认证方式。

如果代码逻辑是：


API Key + Secret Key
        ↓
OAuth access_token
        ↓
URL 参数传递 access_token

基本可以判断它采用的是历史版本调用方案。

第三，看模型名称。

如果代码使用的是：


ERNIE-Bot
ERNIE-Bot-turbo
eb-instant

等历史模型名称，就应该进一步确认该模型当前是否仍然提供服务。

十、API 调用失败的常见排查方法

1. 401 或鉴权失败

首先检查：


API Key
Secret Key
Bearer Token
access_token

是否混用了不同版本的认证方式。

旧版 API 的 Token 认证方式与新版 V2 的 Bearer Token 方式不能简单混用。百度智能云

2. 404 或接口不存在

重点检查：


域名
API 版本
路径
模型名称

特别是从旧文章复制 URL 时，应确认该接口是否已经调整。

3. 模型不存在

如果返回模型相关错误，优先检查当前千帆控制台中的模型 ID，而不是继续修改 Python 或 Java 代码。

4. 额度或计费问题

模型服务通常与账号、资源开通及计费状态有关。早期千帆接入资料就明确提示，付费服务停止后可能无法继续调用对应 API。百度智能云

因此遇到请求失败时，还应检查：


账号状态
模型服务是否开通
资源是否可用
调用额度
计费状态

5. 请求参数错误

模型接口通常对 messages、模型名称以及其他参数存在明确要求。

建议先使用官方文档中的最小请求示例进行测试，确认“鉴权 → 网络 → 模型 → 参数”这条链路正常后，再逐步加入业务参数。

十一、生产环境接入文心 API 的建议

正式项目中，不建议把 API 调用代码直接散落在业务逻辑中，可以设计一个独立的模型服务层。

例如：


业务系统
   ↓
AI Service
   ↓
千帆 API Client
   ↓
ModelBuilder
   ↓
具体模型

同时将以下信息配置化：


API 地址
API Key
Token
模型 ID
超时时间
最大重试次数

对于高并发系统，还应增加超时、重试、限流、日志和异常处理机制。

尤其需要注意，不要在日志中输出：


API Key
Secret Key
完整 Authorization
完整 access_token

否则即使接口本身运行正常，也可能产生严重的密钥泄露风险。

十二、文心一言 API 新旧接口查询总结

如果只是学习历史代码，可以将文心一言 API 的演进简单理解为：


早期文心一言 API
        ↓
千帆应用
        ↓
API Key + Secret Key
        ↓
access_token
        ↓
旧版 ERNIE 接口

                ↓

千帆 ModelBuilder 新版服务
        ↓
新版 API / SDK
        ↓
Bearer Token 等认证方式
        ↓
模型推理服务
        ↓
可兼容 OpenAI SDK

旧版接口对于维护存量系统、分析历史代码仍然有参考价值，但新项目不宜机械照搬旧教程。百度当前千帆 ModelBuilder 官方文档已经将模型调用、推理服务 API 和 SDK 等内容集中管理，开发时应优先根据当前文档确认接口地址、认证方式、模型 ID 和请求参数。百度智能云

对于已经存在的文心一言 API 项目，最稳妥的迁移方式不是直接替换 URL，而是先确认原项目使用的接口版本，再分别核对鉴权方式、模型名称、请求格式和响应结构。这样既能快速定位旧版接口，也能降低迁移到新版千帆 API 时产生兼容性问题的概率。