ERNIE 5.5 Flash API 사용법: Qianfan 및 OpenRouter 가이드

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가 토큰당 $0입니다. 두 곳 모두 OpenAI Chat Completions 형식을 지원하므로, base URL, 키, 모델 이름만 바꾸면 공식 OpenAI SDK로 어느 쪽이든 호출할 수 있습니다.

아래에서는 API 키 발급, curl·Python·JavaScript로 보내는 첫 요청, 스트리밍, reasoning 토큰, 1M 컨텍스트 윈도우, 그리고 오류 처리까지 다룹니다. 모든 필드와 제한값은 2026년 11월 12일 기준으로 Qianfan과 OpenRouter의 공식 페이지에서 확인한 것입니다.

배경 지식이 필요하다면 ERNIE 5.5 Flash란 무엇인가를 읽어보거나, 이전 세대 모델을 위한 ERNIE 5.1 API 가이드를 참고하세요.

ERNIE 5.5 Flash API란 무엇인가?

ERNIE 5.5 Flash API는 Baidu가 호스팅하는 ERNIE 5.5 Flash Preview 엔드포인트입니다. ERNIE 5.5 Flash Preview는 총 280B 파라미터, 토큰당 14B 활성 파라미터를 가진 sparse mixture-of-experts 모델로, 1M 토큰 컨텍스트를 지원합니다. Baidu는 2026년 11월 11일, ERNIE 5.5 Flash Base를 기반으로 포스트트레이닝을 거친 최초의 모델로 이를 공개했으며, Qianfan과 OpenRouter를 통해 서비스하고 있습니다.

Baidu의 공개 발표에서는 코딩, 에이전트 작업, 3D 모델링, 지식 노동, 콘텐츠 제작 용도로 이 모델을 소개합니다. 또한 이 모델을 중간 체크포인트로 명시하고 있어 동작이 달라질 수 있음을 예상해야 하며, 가중치가 Apache 2.0 라이선스로 "곧" 오픈소스화될 것이라고 밝혔지만 구체적인 일정은 없습니다.

Qianfan vs OpenRouter: 어떤 엔드포인트를 사용해야 할까?

오늘날 각 플랫폼이 공개하는 정보를 기준으로 두 경로를 비교하면 다음과 같습니다.

OpenRouter는 Baidu Qianfan이라는 단일 공급자만 등록하고 있으므로, 두 경로 모두 동일한 백엔드에 연결됩니다. 실질적인 차이는 제한입니다. OpenRouter의 무료 티어는 프로토타이핑과 평가에 적합하고, Qianfan의 기본값인 분당 300 요청은 프로덕션에 적합합니다. 무료 ERNIE 5.5 Flash 가이드에서 $0 경로를 더 자세히 다룹니다.

ERNIE 5.5 Flash API 키는 어떻게 발급받나요?

Qianfan

1. Baidu AI Cloud 계정으로 Qianfan 콘솔에 로그인합니다.
2. 시스템 관리에서 API Key를 열고 키를 생성합니다. 키는 bce-v3/ALTAK-... 형태입니다.
3. 키를 내보냅니다: export QIANFAN_API_KEY="bce-v3/ALTAK-...".

Qianfan은 호출 비용을 Baidu AI Cloud 잔액에서 청구합니다. 잔액이 음수이면 403 account_overdue 오류가 반환되므로, 부하 테스트 전에 잔액을 충전하세요.

OpenRouter

1. OpenRouter에서 계정과 키를 생성합니다.
2. 키를 내보냅니다: export OPENROUTER_API_KEY="sk-or-v1-...".
3. 모델 ID로 baidu/ernie-5.5-flash-preview:free를 사용합니다.

첫 ERNIE 5.5 Flash 요청 보내기

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

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를 반환합니다. Qianfan에서는 "stream_options": {"include_usage": true}를 추가하면 마지막 청크에서 토큰 수를 받을 수 있습니다. 이 형식이 낯설다면 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)

기본적으로 스트리밍을 사용하세요. 모델이 답변 전에 추론을 수행하기 때문에, 블로킹 호출로는 한동안 아무 응답도 받지 못할 수 있습니다.

공급자별 reasoning 토큰은 어떻게 작동하나요?

ERNIE 5.5 Flash Preview는 reasoning 모델이며, 두 플랫폼이 이를 서로 다른 방식으로 노출합니다.

Qianfan에서는 딥씽킹 문서에서 thinking 파라미터가 ernie-5.5-flash-preview에 대해 "활성화만 가능, 비활성화 불가"라고 명시하고 있으며, 기본값이 high인 reasoning_effort는 "조정할 수 없다"고 합니다. 즉, 여기서는 reasoning을 끄거나 수준을 낮출 수 없습니다. 사고 과정은 content와 별도로 reasoning_content로 반환되며, Qianfan은 이를 max_completion_tokens에 포함해 계산하므로 상한이 너무 낮으면 최종 답변이 잘리고 finish_reason: "length"가 반환될 수 있습니다.

OpenRouter에서는 reasoning 객체로 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를 다시 전달하여 모델이 이어서 추론할 수 있도록 요청합니다. reasoning 토큰 수는 usage.completion_tokens_details.reasoning_tokens에 표시됩니다.

1M 토큰 컨텍스트 윈도우 활용 팁

100만 토큰이면 중형 코드베이스 하나를 담을 수 있습니다. 다음 네 가지 습관이 긴 호출을 예측 가능하게 만들어 줍니다:

1. 요청 수가 아니라 분당 토큰 기준으로 예산을 잡으세요. Qianfan의 기본값은 3,000,000 TPM이므로, 1분 안에 1M 토큰 프롬프트 세 번만 보내도 할당량을 모두 소진합니다. 매 응답에서 X-Ratelimit-Remaining-Input-Tokens를 확인하세요.
2. 안정적인 콘텐츠를 앞에 두세요. 시스템 프롬프트와 참조 문서를 앞쪽에, 변하는 질문을 뒤쪽에 배치하면 반복되는 접두사가 캐시에 적중할 수 있습니다. OpenRouter는 11월 12일 이 모델의 캐시 적중률이 90.83%였다고 보고했습니다.
3. reasoning을 위한 여유를 남기세요. max_completion_tokens를 추론 과정과 답변을 모두 감당할 만큼 크게 설정하세요.
4. 속도 주장을 믿기 전에 직접 측정하세요. Baidu는 이 모델이 초당 200개 이상의 토큰을 생성한다고 밝혔지만, 11월 12일 기준 OpenRouter 무료 엔드포인트의 P50 처리량은 초당 79토큰, P50 지연 시간은 2.53초였습니다.

구조화된 출력은 출시 전에 철저히 테스트하세요. OpenRouter는 JSON 스키마가 포함된 response_format을 지원하지만, 같은 페이지에서 이 모델의 3일간 구조화 출력 오류율을 21.70%, 툴 호출 오류율을 1.01%로 보고했습니다. 모든 JSON 응답을 검증하고, 파싱 실패 시 재시도하세요.

ERNIE 5.5 Flash API 오류 및 속도 제한

Qianfan의 오류 코드 표와 OpenRouter의 제한 페이지를 기준으로, 가장 자주 마주치는 코드는 다음과 같습니다:

OpenRouter에서 GET https://openrouter.ai/api/v1/key를 호출하면 free_model_daily_requests.remaining이 반환됩니다. 429 오류는 지수 백오프와 지터를 적용해 재시도하고, 400이나 401은 절대 재시도하지 마세요.

Apidog CLI로 코딩 에이전트에게 두 엔드포인트 테스트 맡기기

두 공급자 모두 응답하기 시작하면, 올바른 상태 코드, 올바른 응답 구조, 허용 가능한 지연 시간으로 계속 정상 응답하는지 검증해야 합니다. 이 작업을 코딩 에이전트에게 맡기세요. Apidog CLI는 Claude Code, Codex, Cursor, OpenCode에 엔드포인트를 가져오고, 공급자별 환경을 저장하고, 각 환경에서 테스트 시나리오를 실행하는 명령어를 제공합니다.

한 번만 설정하세요:

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

그리고 에이전트에게 프롬프트 하나만 주면 됩니다:

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.

에이전트는 각 스키마를 검사하고, 페이로드를 검증하고, 다음과 같은 명령어를 실행합니다:

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

--env-var로 키를 전달하면 저장된 프로젝트에 키가 남지 않으며, 하나의 시나리오로 두 경로를 나란히 비교할 수 있습니다. 동일한 apidog run에 -r junit을 붙이면 파이프라인에 바로 넣을 수 있습니다. 설정 방법은 Apidog CLI CI/CD 가이드에서, 에이전트 측 사용법은 Claude Code에서의 Apidog CLI에서 확인하세요. Apidog의 무료 플랜은 최대 4명의 사용자까지 지원합니다.

FAQ

ERNIE 5.5 Flash API는 무료인가요? OpenRouter에서는 그렇습니다: baidu/ernie-5.5-flash-preview:free는 토큰당 $0이며, 분당 20회, 일 50회(또는 $10 크레딧 구매 후 일 1,000회)의 제한이 있습니다. Qianfan은 호출 비용을 Baidu AI Cloud 잔액에서 청구합니다.

ERNIE 5.5 Flash의 모델 ID는 무엇인가요? Qianfan에서는 ernie-5.5-flash-preview, OpenRouter에서는 baidu/ernie-5.5-flash-preview:free를 사용하세요.

Qianfan에서 thinking을 끌 수 있나요? 아니요. Qianfan 문서에 따르면 이 모델은 thinking을 활성화만 할 수 있고, reasoning_effort는 high로 고정됩니다. 추론 과정을 위한 출력 토큰을 미리 확보하세요.

ERNIE 5.5 Flash API는 툴 호출을 지원하나요? 네. Qianfan은 Function Call과 구조화 출력을 지원한다고 명시하고 있으며, OpenRouter는 tools, tool_choice, response_format을 지원합니다. OpenRouter에서 구조화 출력의 오류율이 높다고 보고했으므로 반드시 검증하세요.

ERNIE 5.5 Flash를 직접 실행할 수 있나요? Baidu는 Hugging Face에 ERNIE 5.5 Flash Base를 공개했고, Preview 가중치도 Apache 2.0으로 공개될 예정입니다. vLLM으로 ERNIE 5.5 Flash 로컬 실행하기를 참고하세요.

DeepSeek V4.1 Flash와 비교하면 어떤가요? ERNIE 5.5 Flash vs DeepSeek V4.1 Flash와 DeepSeek V4.1 Flash API 가이드를 참고하세요.