如何通过百度千帆和 OpenRouter 使用 ERNIE 5.5 Flash API

全面详解百度千帆与 OpenRouter 接入 ERNIE 5.5 Flash Preview API 的方法:涵盖密钥配置、Python/JS/curl 代码示例、流式输出、推理控制及错误码排查。

用 Apifox,节省研发团队的每一分钟

如何通过百度千帆和 OpenRouter 使用 ERNIE 5.5 Flash API

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

ERNIE 5.5 Flash API 目前已在两个平台上线:一是百度千帆(Baidu Qianfan),可通过 https://qianfan.baidubce.com/v2/chat/completions 调用 ernie-5.5-flash-preview;二是 OpenRouter,其 baidu/ernie-5.5-flash-preview:free 端点的每 token 费用为 $0。两个平台均遵循 OpenAI Chat Completions 格式,因此你只需修改 base URL、API 密钥和模型名称,即可使用官方 OpenAI SDK 对接任一平台。

下文将涵盖密钥获取、curl / Python / JavaScript 首次请求示例、流式传输、推理 token、1M 上下文窗口使用技巧以及常见错误码。文中所有字段和限额均于 2026 年 11 月 12 日核对自百度千帆与 OpenRouter 官方页面。

如需了解背景信息,请阅读什么是 ERNIE 5.5 Flash,或参考上一代模型的 ERNIE 5.1 API 指南。

AI Coding 交流群

如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。

AI Coding 交流群二维码

什么是 ERNIE 5.5 Flash API?

ERNIE 5.5 Flash API 是百度为 ERNIE 5.5 Flash Preview 提供的托管端点。该模型采用稀疏混合专家(MoE)架构,总参数量为 280B,每个 token 激活参数量为 14B,支持 1M token 上下文。百度于 2026 年 11 月 11 日将其作为基于 ERNIE 5.5 Flash Base 构建的首个后训练模型发布,并通过千帆和 OpenRouter 提供服务。

ERNIE 5.5 Flash API 概览

百度的发布公告将其定位于编码、Agent 任务、3D 建模、知识工作与内容创作。公告称该模型是一个中间检查点(intermediate checkpoint),因此后续行为可能会有所调整;同时表示模型权重将“很快”以 Apache 2.0 协议开源,但未公布具体日期。

百度千帆 vs OpenRouter:应该选择哪个端点?

根据两个平台目前公布的信息,两条接入路线的对比如下:

对比维度 百度千帆(Baidu Qianfan) OpenRouter
Base URL https://qianfan.baidubce.com/v2 https://openrouter.ai/api/v1
模型 ID ernie-5.5-flash-preview baidu/ernie-5.5-flash-preview:free
认证请求头 Authorization: Bearer <Qianfan API key> Authorization: Bearer <OpenRouter key>
上下文窗口 1M 输入,1M 输出 1,024,000 tokens
价格 从百度智能云账户余额扣费(具体费率见控制台) :free 变体为 $0
默认速率限制 300 次请求/分钟,3,000,000 tokens/分钟 20 次请求/分钟;50 次/天(充值 $10 后为 1,000 次/天)
推理(Reasoning) 始终开启,推理强度固定为 high 通过 reasoning 对象控制
调用 ERNIE 5.5 Flash Preview 的两条路线示意图:应用以模型 baidu/ernie-5.5-flash-preview:free 调用 OpenRouter(由其转发至百度千帆),或直接以模型 ernie-5.5-flash-preview 调用百度千帆

OpenRouter 列出的唯一提供商就是百度千帆,因此两条路线访问的是同一个后端。真正的区别在于速率限制:OpenRouter 的免费档位适合原型开发和评测,而千帆默认的 300 RPM 更适合生产环境。关于 $0 免费方案的更多细节,请参阅免费使用 ERNIE 5.5 Flash 指南。

如何获取 ERNIE 5.5 Flash API 密钥?

百度千帆

  1. 使用百度智能云账户登录千帆控制台。
  2. 在系统管理下打开 API Key 页面并创建密钥。密钥格式类似于 bce-v3/ALTAK-...。
  3. 导出环境变量:export QIANFAN_API_KEY="bce-v3/ALTAK-..."。

千帆会从你的百度智能云余额中扣除调用费用。如果余额为负数,接口会返回 403 account_overdue,因此在进行压力测试前请先充值。

OpenRouter

  1. 在 OpenRouter 注册账户并创建 API 密钥。
  2. 导出环境变量:export OPENROUTER_API_KEY="sk-or-v1-..."。
  3. 使用模型 ID baidu/ernie-5.5-flash-preview:free。

发送你的第一个 ERNIE 5.5 Flash 请求

curl

百度千帆:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -d '{
    "model": "ernie-5.5-flash-preview",
    "messages": [
      {"role": "system", "content": "You are a concise senior engineer."},
      {"role": "user", "content": "Write a Python function that validates an ISO 8601 date."}
    ]
  }'

OpenRouter:

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "baidu/ernie-5.5-flash-preview:free",
    "messages": [
      {"role": "user", "content": "Write a Python function that validates an ISO 8601 date."}
    ]
  }'

Python

运行 pip install openai 安装 SDK,然后根据所选平台切换 base URL:

import os
from openai import OpenAI

PROVIDERS = {
    "qianfan": ("https://qianfan.baidubce.com/v2", "QIANFAN_API_KEY", "ernie-5.5-flash-preview"),
    "openrouter": ("https://openrouter.ai/api/v1", "OPENROUTER_API_KEY", "baidu/ernie-5.5-flash-preview:free"),
}

base_url, key_env, model = PROVIDERS["qianfan"]
client = OpenAI(base_url=base_url, api_key=os.environ[key_env])

resp = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
    max_completion_tokens=4096,
)
print(resp.choices[0].message.content)
print(resp.usage)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "baidu/ernie-5.5-flash-preview:free",
  messages: [{ role: "user", content: "List three causes of HTTP 499 errors." }],
});
console.log(resp.choices[0].message.content);

如何流式传输 ERNIE 5.5 Flash 响应?

在请求中添加 "stream": true,两个平台都会返回以 data: [DONE] 结尾的 Server-Sent Events(SSE)流。在千帆上,可以额外添加 "stream_options": {"include_usage": true},以便在最后一个数据块(chunk)中获取 token 统计信息。如果你还不熟悉这种格式,可以参考 SSE 流式传输指南了解底层传输结构。

stream = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Draft a README for a CLI tool."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta
        thinking = getattr(delta, "reasoning_content", None)
        if thinking:
            print(f"[thinking] {thinking}", end="", flush=True)
        if delta.content:
            print(delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

建议默认开启流式传输:因为模型在输出最终回答前会先进行推理思考,阻塞式调用可能会在较长时间内没有任何输出。

两个平台上的推理 token 分别如何工作?

ERNIE 5.5 Flash Preview 是一个推理模型,两个平台暴露推理过程的方式有所不同。

在百度千帆上,深度思考文档将 ernie-5.5-flash-preview 的 thinking 参数列为“仅支持开启,不可关闭”,且默认的 reasoning_effort(high)“不可调整”。这意味着在千帆上无法关闭推理或调低推理强度。思维链内容会通过与 content 分离的 reasoning_content 字段返回。千帆会将推理 token 计入 max_completion_tokens,因此如果该上限设得太小,可能会截断最终回答并返回 finish_reason: "length"。

在 OpenRouter 上,你可以通过 reasoning 对象控制推理行为,并从 reasoning_details 中读取推理轨迹。如果希望在响应中隐藏推理轨迹,可按如下方式设置:

{
  "model": "baidu/ernie-5.5-flash-preview:free",
  "reasoning": { "exclude": true },
  "messages": [{ "role": "user", "content": "Is 2^61 - 1 prime?" }]
}

在多轮对话中,OpenRouter 建议你将完整的 reasoning_details 随 assistant 消息一并传回,以便模型能够从上一次推理中断的位置继续。推理 token 数量会显示在 usage.completion_tokens_details.reasoning_tokens 中。

使用 1M token 上下文窗口的实用技巧

一百万 token 足以装下一个中等规模的代码库。养成以下四个习惯可以让长上下文调用更加可控:

  1. 同时按每分钟 token 数(TPM)而非仅按请求数做预算。 千帆的默认限额为 3,000,000 TPM,因此一分钟内发送三次完整的 1M token 提示词就会耗尽全部配额。建议关注每次响应头中的 X-Ratelimit-Remaining-Input-Tokens。
  2. 将固定不变的内容放在前面。 把系统提示词(system prompt)和参考文档放在最前面,把每次变化的问题放在末尾,这样重复的前缀就能命中缓存。11 月 12 日 OpenRouter 页面显示该模型的缓存命中率高达 90.83%。
  3. 为推理过程预留充足空间。 将 max_completion_tokens 设得足够高,以同时容纳思考过程与最终回答。
  4. 实测验证速度,不要轻信宣传数据。 百度宣称该模型每秒可生成超过 200 token;而在 11 月 12 日 OpenRouter 免费端点上,实测 P50 吞吐量为每秒 79 token,P50 延迟为 2.53 秒。

如果需要使用结构化输出,上线前请务必充分测试。OpenRouter 虽然支持传入带 JSON schema 的 response_format,但其页面报告该模型近三天的结构化输出错误率为 21.70%,而工具调用错误率仅为 1.01%。因此请严格校验每一次 JSON 响应,并在解析失败时进行重试。

ERNIE 5.5 Flash API 常见错误码与速率限制

以下是最常遇到的错误状态码,整理自千帆的错误码表与 OpenRouter 限额页面:

状态码 平台 错误码或原因 解决方法
400 百度千帆 tokens_too_long 将提示词裁剪到 1M 输入上限以内
401 百度千帆 invalid_iam_token API 密钥错误、已过期,或漏掉了 Bearer 前缀
401 百度千帆 invalid_model 检查模型 ID 是否严格等于 ernie-5.5-flash-preview
403 百度千帆 account_overdue 账户余额小于零;请先充值
429 百度千帆 rpm_rate_limit_exceeded、tpm_rate_limit_exceeded 进行退避等待;配额会在 60 秒内刷新
402 OpenRouter 信用余额为负数 充值补齐余额(即使调用 :free 模型也需余额非负)
429 OpenRouter 触发免费模型限额(20 次/分钟,50 或 1,000 次/天) 读取 X-RateLimit-Reset 响应头,或查询 GET /api/v1/key

在 OpenRouter 上,调用 GET https://openrouter.ai/api/v1/key 会返回 free_model_daily_requests.remaining。遇到 429 错误时请采用带抖动的指数退避策略重试;切勿对 400 或 401 错误进行盲目重试。

让你的编码 Agent 使用 Apifox CLI 同时测试两个端点

当两个平台都能正常响应后,你还需要确保它们持续稳定地返回正确结果:状态码正确、数据结构合规、延迟在可接受范围内。可以把这项验证交给你的编码 Agent。Apifox CLI 为 Claude Code、Codex、Cursor 或 OpenCode 提供了命令行能力,能够导入接口、为每个平台保存独立环境,并针对两个环境运行同一个测试场景。

工作流示意图:编码 Agent 驱动 Apifox CLI 针对千帆环境与 OpenRouter 环境运行同一个测试场景,并将测试报告返回给 Agent

只需完成一次初始化设置:

npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_APIFOX_TOKEN>
apifox skill install

然后向你的 Agent 发送一条提示词:

Write an OpenAPI 3 file for POST /chat/completions that matches the ERNIE 5.5 Flash
request and response shape (model, messages, stream; choices[0].message.content, usage).
Import it into Apifox project <projectId>. Create two environments: "qianfan" with base
URL https://qianfan.baidubce.com/v2 and "openrouter" with https://openrouter.ai/api/v1,
each with a "model" variable. Build one test scenario that sends a short prompt and
asserts status 200, the response schema, and a response time under 30 seconds. Run it
against both environments, passing the API keys as environment variables, and summarize
any failures.

Agent 会检查各个 schema、校验 payload,并执行类似如下的命令:

apifox import --project <projectId> --format openapi --file ./ernie-5-5-flash.openapi.yaml
apifox environment create qianfan --project <projectId> --base-url https://qianfan.baidubce.com/v2
apifox environment create openrouter --project <projectId> --base-url https://openrouter.ai/api/v1
apifox cli-schema get test-scenario-create
apifox test-scenario create --project <projectId> --name "ERNIE 5.5 Flash smoke" --folder-id <folderId> --priority <priority>
apifox test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointId> --sync manual
apifox run -t <scenarioId> --project <projectId> -e <qianfanEnvId> --env-var "apiKey=$QIANFAN_API_KEY" -r cli,json
apifox run -t <scenarioId> --project <projectId> -e <openrouterEnvId> --env-var "apiKey=$OPENROUTER_API_KEY" -r cli,json

使用 --env-var 传递密钥可以避免将其保存在项目配置中,同时单个测试场景就能让你直观对比两条路线的实际表现。同一条 apifox run 命令加上 -r junit 即可直接放入 CI/CD 流水线;具体配置可参考 Apifox CLI CI/CD 指南,Agent 侧用法详见 Claude Code 中的 Apifox CLI 指南。Apifox 免费版不限制成员数量和协作人数。

常见问题

ERNIE 5.5 Flash API 是免费的吗? 在 OpenRouter 上是免费的:baidu/ernie-5.5-flash-preview:free 每 token 收费 $0,限制为每分钟 20 次请求、每天 50 次请求(累计购买 $10 额度后提升至每天 1,000 次)。百度千帆则会从你的百度智能云账户余额中扣费。

ERNIE 5.5 Flash 的模型 ID 是什么? 在百度千帆上使用 ernie-5.5-flash-preview,在 OpenRouter 上使用 baidu/ernie-5.5-flash-preview:free。

在百度千帆上可以关闭深度思考(thinking)吗? 不能。千帆文档说明该模型的深度思考功能仅支持开启且无法关闭,同时 reasoning_effort 固定为 high。请务必为推理过程预留足够的输出 token 预算。

ERNIE 5.5 Flash API 支持工具调用吗? 支持。千帆将其列为支持 Function Call 和结构化输出,OpenRouter 也接受 tools、tool_choice 和 response_format 参数。由于 OpenRouter 报告该模型的结构化输出错误率较高,使用时请务必做好数据校验。

我可以自己私有化部署 ERNIE 5.5 Flash 吗? 百度已在 Hugging Face 上发布了 ERNIE 5.5 Flash Base 权重,并承诺将按 Apache 2.0 协议开源 Preview 权重。部署方法详见使用 vLLM 在本地运行 ERNIE 5.5 Flash。

它与 DeepSeek V4.1 Flash 相比如何? 请参阅 ERNIE 5.5 Flash 对比 DeepSeek V4.1 Flash 以及 DeepSeek V4.1 Flash API 指南。