文心一言 API 怎么接：千帆的模型名、计费和三个常见报错

四步：控制台建 API Key、选模型、复制示例代码、发一次请求。不需要单独申请开通，也不用走商务审批。真正会卡住人的不是流程，是模型名写错和鉴权方式混用这两个细节。

四步拿到第一次响应

第一步，进千帆控制台。 路径是百度智能云 → 千帆 → 「快速接入」。页面上会直接给一个「创建通用 API Key」的按钮，企业用户如果买了 Token Plan，用对应的专属 Key。

第二步，选模型。 模型卡片上标了计费方式、能力标签、上下文长度和输入输出价格。C 端对话用的是文心 5.1，接口侧的模型名是 ernie-5.1；11 月新上的文心 5.5 Flash Preview，平台模型名是 ERNIE-5.5-Flash，版本名带 -Preview 后缀。

第三步，复制示例代码。 选完模型，model 字段和鉴权头会自动填进示例里。这一步别自己手写，模型名的连字符和大小写在千帆上是有区分的。

第四步，发请求。 v2 接口的形态是 OpenAI 兼容风格：

import requests, os

resp = requests.post(
    "https://qianfan.baidubce.com/v2/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['QIANFAN_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "ernie-5.1",
        "messages": [{"role": "user", "content": "用一句话说明什么是 MoE"}],
        "temperature": 0.3,
    },
    timeout=60,
)
print(resp.json()["choices"][0]["message"]["content"])

跑通之后再去动参数。第一次就调 temperature、top_p 这些，出问题分不清是配置还是模型。

价格怎么算

按 token 计费，输入输出分开计价，这是 2026 年的主流做法。

5.5 Flash Preview 当前有限时五折活动，折后忙时输入 1 元、输出 4 元，缓存命中 0.1 元/百万 token。活动结束日官方没有写死，做预算时按原价留余量。

忙时是 8:00–22:00，闲时是 22:00–次日 8:00，价差一倍。批量任务放到夜里跑，这一条就能省掉一半成本。

文心 5.0 在海外站是另一个价格体系，每百万输入 1.40 美元、输出 5.60 美元，和国内千帆不能直接换算比较。各家横向价格见 11 月大模型 API 价格表。

三个高频报错

401，鉴权失败。 九成是把 AK/SK 和 API Key 搞混了。AK/SK 是老版本地签名方式，需要先换 access_token 再调；现在控制台主推的是 API Key，直接放在 Authorization: Bearer 后面。两套东西别混着用，文档里两种示例都有，照抄容易抄错年代。

404 或 model not found。 模型名不对。千帆上同一代模型常有三个名字：展示名（文心 5.5 Flash）、平台模型名（ERNIE-5.5-Flash）、带版本后缀的完整名（ERNIE-5.5-Flash-Preview）。接口要的是后者。

429，限流。 千帆的限流按 TPM（每分钟 token 数）计，具体档位跟账号类型和是否订阅有关，官方没有公开一张统一的限额表，控制台的用量页能看到当前配额和触顶记录。遇到 429 先看是哪个维度触顶，再决定是降并发还是申请提额。

接之前先想清楚的两件事

一是要不要用 Agent 框架。如果你的场景是多步工具调用，直接在千帆上搭 Agent 比自己在外面套一层循环省事，千帆本身就有 Agent 开发平台。但如果你的 Agent 需要跨厂商模型，标准化的连接方式更合适，可以参考 MCP 是什么里的协议设计。

二是成本结构。文心的输出价是输入价的 4 倍，长回答比长输入贵得多。如果你的业务是「长文档进、短结论出」，成本会很低；反过来「短问题进、长报告出」，账单会超出直觉。先按实际业务比例估一遍，再决定用哪一档模型。

现在可以做的

去控制台建一个通用 API Key，用上面那段代码跑一次 ernie-5.1。能出结果，说明账号、网络、鉴权都通了，剩下的都是业务层的事。

跑不通就按 401 / 404 / 429 三个分支查，别一上来就怀疑网络。