Cách sử dụng API ERNIE 5.5 Flash với Qianfan và OpenRouter

API ERNIE 5.5 Flash đã có mặt tại hai nơi: Baidu Qianfan, nơi bạn gọi ernie-5.5-flash-preview tại https://qianfan.baidubce.com/v2/chat/completions, và OpenRouter, nơi baidu/ernie-5.5-flash-preview:free có giá 0$ mỗi token. Cả hai đều dùng định dạng OpenAI Chat Completions, vì vậy bạn có thể trỏ SDK OpenAI chính thức đến một trong hai chỉ bằng cách thay đổi base URL, khóa API và tên model.

Bên dưới: cách lấy khóa, các yêu cầu đầu tiên bằng curl, Python và JavaScript, streaming, token suy luận (reasoning), cửa sổ ngữ cảnh 1M, và các lỗi thường gặp. Mọi trường và giới hạn đều lấy từ trang chính thức của Qianfan và OpenRouter, đã kiểm tra vào ngày 12 tháng 11 năm 2026.

Để có thêm nền tảng, hãy đọc ERNIE 5.5 Flash là gì, hoặc hướng dẫn API ERNIE 5.1 cho thế hệ trước.

API ERNIE 5.5 Flash là gì?

API ERNIE 5.5 Flash là điểm cuối do Baidu vận hành cho ERNIE 5.5 Flash Preview, một model mixture-of-experts dạng thưa (sparse) với tổng cộng 280B tham số, 14B tham số hoạt động cho mỗi token và ngữ cảnh 1 triệu token. Baidu phát hành nó vào ngày 11 tháng 11 năm 2026, là model post-trained đầu tiên được xây dựng trên ERNIE 5.5 Flash Base, và cung cấp thông qua Qianfan và OpenRouter.

Bài viết phát hành của Baidu định vị model cho lập trình, công việc agentic, mô hình hóa 3D, công việc tri thức và sáng tạo nội dung. Họ gọi đây là một checkpoint trung gian, nên hãy kỳ vọng hành vi có thể thay đổi, và nói rằng trọng số (weights) sẽ được mã nguồn mở theo Apache 2.0 “sớm”, không có ngày cụ thể.

Qianfan vs OpenRouter: bạn nên dùng điểm cuối nào?

Dưới đây là so sánh hai tuyến, dựa trên những gì mỗi nền tảng công bố hiện nay.

OpenRouter chỉ liệt kê một nhà cung cấp là Baidu Qianfan, nên cả hai tuyến đều đi đến cùng một backend. Khác biệt thực sự nằm ở giới hạn: gói miễn phí của OpenRouter phù hợp để tạo mẫu (prototyping) và đánh giá (evals), còn mặc định 300 RPM của Qianfan phù hợp cho production. Hướng dẫn dùng ERNIE 5.5 Flash miễn phí đi sâu hơn vào các tuyến miễn phí 0$.

Làm thế nào để lấy khóa API ERNIE 5.5 Flash?

Qianfan

1. Đăng nhập vào console Qianfan bằng tài khoản Baidu AI Cloud.
2. Mở API Key trong phần quản lý hệ thống và tạo một khóa. Nó có dạng bce-v3/ALTAK-....
3. Xuất biến môi trường: export QIANFAN_API_KEY="bce-v3/ALTAK-...".

Qianfan tính phí các cuộc gọi vào số dư Baidu AI Cloud của bạn. Số dư âm sẽ trả về 403 account_overdue, nên hãy nạp tiền trước khi stress test.

OpenRouter

1. Tạo tài khoản và khóa tại OpenRouter.
2. Xuất biến môi trường: export OPENROUTER_API_KEY="sk-or-v1-...".
3. Dùng model ID baidu/ernie-5.5-flash-preview:free.

Gửi yêu cầu ERNIE 5.5 Flash đầu tiên

curl

Qianfan:

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

Cài SDK bằng pip install openai, rồi đổi base URL theo từng nhà cung cấp:

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);

Làm thế nào để stream phản hồi từ ERNIE 5.5 Flash?

Thêm "stream": true và cả hai nhà cung cấp sẽ trả về server-sent events kết thúc bằng data: [DONE]. Trên Qianfan, thêm "stream_options": {"include_usage": true} để nhận số lượng token trong chunk cuối cùng. Nếu bạn chưa quen với định dạng này, hướng dẫn streaming SSE giải thích định dạng truyền dẫn.

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)

Mặc định hãy dùng stream: model suy luận trước khi trả lời, nên một cuộc gọi đồng bộ (blocking) có thể im lặng trong một khoảng thời gian.

Token suy luận hoạt động thế nào trên mỗi nhà cung cấp?

ERNIE 5.5 Flash Preview là một model reasoning, và hai nền tảng hiện điều đó theo cách khác nhau.

Trên Qianfan, tài liệu deep-thinking liệt kê ernie-5.5-flash-preview ở trạng thái “chỉ bật được, không thể tắt” cho tham số thinking, và giá trị mặc định high của reasoning_effort “không thể điều chỉnh”. Vì vậy bạn không thể tắt suy luận hay giảm mức độ ở đây. Chuỗi suy luận (chain of thought) được trả về trong reasoning_content, tách biệt với content. Qianfan tính nó vào max_completion_tokens, nên mức giới hạn quá chặt có thể cắt ngắn câu trả lời cuối và khiến bạn nhận finish_reason: "length".

Trên OpenRouter, bạn kiểm soát reasoning bằng đối tượng reasoning và đọc chuỗi suy luận từ reasoning_details. Để ẩn chuỗi suy luận khỏi phản hồi:

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

Trong hội thoại nhiều lượt, OpenRouter yêu cầu bạn truyền toàn bộ reasoning_details trở lại kèm tin nhắn của assistant để model có thể tiếp tục từ chỗ nó dừng lại. Số token suy luận xuất hiện trong usage.completion_tokens_details.reasoning_tokens.

Mẹo cho cửa sổ ngữ cảnh 1 triệu token

Một triệu token chứa được một codebase cỡ vừa. Bốn thói quen giúp các cuộc gọi dài ổn định, dễ đoán:

1. Định ngân sách theo token mỗi phút, không chỉ theo số yêu cầu. Mặc định của Qianfan là 3.000.000 TPM, nên ba prompt đầy đủ 1 triệu token trong một phút đã dùng hết hạn mức. Theo dõi X-Ratelimit-Remaining-Input-Tokens trên mỗi phản hồi.
2. Đặt nội dung ổn định lên đầu. Giữ system prompt và tài liệu tham khảo ở phần đầu, câu hỏi thay đổi ở phần cuối, để các tiền tố lặp lại có thể trúng cache. OpenRouter ghi nhận tỷ lệ cache hit 90,83% cho model này vào ngày 12 tháng 11.
3. Chừa chỗ cho suy luận. Đặt max_completion_tokens đủ cao để bao gồm cả phần suy nghĩ và câu trả lời.
4. Đo lường trước khi tin các tuyên bố về tốc độ. Baidu cho biết model tạo ra hơn 200 token mỗi giây. Trên endpoint miễn phí của OpenRouter, thông lượng P50 vào ngày 12 tháng 11 là 79 token mỗi giây, với độ trễ P50 là 2,53 giây.

Với structured output, hãy kiểm tra kỹ trước khi đưa vào sử dụng. OpenRouter chấp nhận response_format với JSON schema, nhưng trang của họ báo tỷ lệ lỗi structured-output 21,70% cho model này trong ba ngày, trong khi tỷ lệ lỗi tool-call chỉ là 1,01%. Hãy validate mọi phản hồi JSON và retry khi parse thất bại.

Lỗi và giới hạn tốc độ của API ERNIE 5.5 Flash

Đây là những mã bạn sẽ gặp nhiều nhất, lấy từ bảng mã lỗi của Qianfan và trang giới hạn của OpenRouter:

Trên OpenRouter, GET https://openrouter.ai/api/v1/key trả về free_model_daily_requests.remaining. Hãy retry lỗi 429 với exponential backoff và jitter; đừng bao giờ retry lỗi 400 hoặc 401.

Cho coding agent của bạn kiểm thử cả hai điểm cuối bằng Apidog CLI

Khi cả hai nhà cung cấp đã phản hồi, bạn cần bằng chứng rằng họ tiếp tục phản hồi đúng: trạng thái đúng, cấu trúc đúng, độ trễ chấp nhận được. Giao việc đó cho coding agent của bạn. Apidog CLI cung cấp cho Claude Code, Codex, Cursor hoặc OpenCode các lệnh để import endpoint, lưu một environment cho mỗi nhà cung cấp và chạy một kịch bản kiểm thử với từng cái.

Cài đặt một lần:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

Sau đó đưa cho agent một prompt:

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 Apidog 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 sẽ kiểm tra từng schema, validate payload và chạy các lệnh như sau:

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

Truyền khóa bằng --env-var giúp chúng không bị lưu vào project, và một kịch bản duy nhất cho bạn cái nhìn so sánh song song cả hai tuyến. Cùng lệnh apidog run với -r junit có thể đưa vào pipeline; hướng dẫn Apidog CLI CI/CD trình bày cách thiết lập, và Apidog CLI trong Claude Code nói về khía cạnh agent. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.

Câu hỏi thường gặp

API ERNIE 5.5 Flash có miễn phí không? Trên OpenRouter, có: baidu/ernie-5.5-flash-preview:free có giá 0$ mỗi token, với giới hạn 20 yêu cầu mỗi phút và 50 mỗi ngày, hoặc 1.000 mỗi ngày sau khi bạn đã mua 10$ tín dụng. Qianfan tính phí các cuộc gọi vào số dư Baidu AI Cloud của bạn.

Model ID của ERNIE 5.5 Flash là gì? Dùng ernie-5.5-flash-preview trên Qianfan và baidu/ernie-5.5-flash-preview:free trên OpenRouter.

Có thể tắt thinking trên Qianfan không? Không. Tài liệu Qianfan cho biết thinking chỉ có thể bật cho model này và reasoning_effort giữ ở mức high. Hãy định ngân sách output token cho phần suy luận.

API ERNIE 5.5 Flash có hỗ trợ tool calling không? Có. Qianfan liệt kê Function Call và structured output là được hỗ trợ, và OpenRouter chấp nhận tools, tool_choice và response_format. Hãy validate structured output, vì OpenRouter đã báo cáo tỷ lệ lỗi cao cho tính năng này.

Có thể tự chạy ERNIE 5.5 Flash không? Baidu đã công bố ERNIE 5.5 Flash Base trên Hugging Face, và trọng số Preview được hứa sẽ phát hành theo Apache 2.0. Xem chạy ERNIE 5.5 Flash cục bộ với vLLM.

Nó so sánh thế nào với DeepSeek V4.1 Flash? Xem ERNIE 5.5 Flash vs DeepSeek V4.1 Flash và hướng dẫn API DeepSeek V4.1 Flash.