Como Usar a API ERNIE 5.1: Guia Completo

ERNIE 5.1 foi lançado em 9 de maio de 2026, e em uma semana a API Qianfan já estava ativa para ele. Se você deseja chamar o modelo a partir do seu próprio código, rotear chamadas de ferramenta através dele ou integrá-lo a um loop de agente com Apidog, este guia percorre todo o caminho: conta, chave, corpo da requisição, streaming, uso de ferramentas, tratamento de erros.

Vamos manter a praticidade. Ao final, você terá trechos de código funcionais em curl, Python e Node, além de uma coleção de requisições que você pode importar para o Apidog.

Se você ainda não leu a análise de lançamento do ERNIE 5.1, leia-a primeiro; ela aborda benchmarks e trade-offs em comparação com DeepSeek V4 e Kimi K2.6. Este post é o acompanhamento da implementação.

Passo 1: Obtenha uma chave de API Qianfan

ERNIE 5.1 é servido através da plataforma Qianfan da Baidu Intelligent Cloud. Não há uma "API ERNIE" separada; tudo é roteado através do Qianfan.

Vá para cloud.baidu.com e crie ou faça login em uma conta Baidu Intelligent Cloud. Desenvolvedores internacionais podem usar o cadastro por e-mail; algumas funcionalidades empresariais ainda exigem um número de telefone da China continental.
Abra o console Qianfan em console.bce.baidu.com/qianfan.
Em Gerenciamento de Chaves de API (API Key 管理), clique em Criar Chave de API. Escolha o espaço de trabalho e conceda acesso ao serviço de `chat-completions`.
Copie a chave. Ela se parece com bce-v3/ALTAK-xxxx/xxxx. Armazene-a em uma variável de ambiente, não no código-fonte.

export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"

Duas coisas para saber de antemão. Primeiro, o novo endpoint v2 usa um único token Bearer; o fluxo OAuth access_token v1 mais antigo está sendo descontinuado e você não deve construir novos códigos com ele. Segundo, o ERNIE 5.1 é um modelo pago desde o primeiro dia. Recarregue um pequeno saldo (¥10 é suficiente para testar) antes da sua primeira requisição.

Passo 2: Acesse o endpoint compatível com OpenAI usando curl

O Qianfan expõe um endpoint de `chat-completions` compatível com OpenAI, então qualquer coisa em sua pilha que já entenda o formato OpenAI funcionará com uma troca de URL base e uma alteração de ID de modelo.

URL Base: https://qianfan.baidubce.com/v2 ID do Modelo: ernie-5.1 (também: ernie-5.1-preview para recursos de acesso antecipado)

Requisição mínima viável:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-5.1",
    "messages": [
      {"role": "system", "content": "You are a senior API designer."},
      {"role": "user", "content": "Sketch a REST schema for a GitHub-style PR review API. Be concise."}
    ],
    "temperature": 0.3
  }'

Você receberá uma resposta no formato padrão OpenAI:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1746780000,
  "model": "ernie-5.1",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 318,
    "total_tokens": 360
  }
}

Se você vir 401 Unauthorized, sua chave está errada ou expirada. Se você vir 403, a chave é válida, mas o modelo não está habilitado neste espaço de trabalho; volte ao console e adicione o ERNIE 5.1 aos modelos permitidos do espaço de trabalho.

Passo 3: Chame o ERNIE 5.1 a partir do Python

Como o endpoint é compatível com OpenAI, o SDK oficial openai para Python funciona como está. Aponte-o para o Qianfan.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[
        {"role": "system", "content": "You explain APIs in plain English."},
        {"role": "user", "content": "Why would I use server-sent events over WebSockets for a chat UI?"},
    ],
    temperature=0.4,
)

print(response.choices[0].message.content)
print(f"\nTokens used: {response.usage.total_tokens}")

Se você já tem wrappers em torno do SDK da OpenAI em seu código, substituir o ERNIE 5.1 para testes A/B é uma mudança de uma linha. O mesmo truque funciona para a API do DeepSeek e a maioria dos outros provedores de modelos chineses.

Passo 4: Transmita tokens para interfaces de usuário estilo chat

Para qualquer chat voltado para o usuário, você vai querer streaming. Defina stream: true e consuma eventos enviados pelo servidor.

stream = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "Write a haiku about API versioning."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Equivalente em Curl para depuração:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-5.1",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a 3-sentence joke."}]
  }' \
  --no-buffer

O formato de stream é idêntico ao da OpenAI: linhas data: {...} terminadas por data: [DONE].

Passo 5: Use ERNIE 5.1 com ferramentas (a parte "agentic")

É aqui que o ERNIE 5.1 justifica seu título de lançamento. O modelo obteve pontuações acima do DeepSeek-V4-Pro no τ³-bench e SpreadsheetBench-Verified, o que significa que a chamada de ferramentas funciona em produção, não apenas em demonstrações.

Mesmo esquema de chamada de função da OpenAI:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. Singapore"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "What's the weather in Tokyo right now?"}],
    tools=tools,
    tool_choice="auto",
)

tool_calls = response.choices[0].message.tool_calls
if tool_calls:
    call = tool_calls[0]
    print(f"Model wants to call: {call.function.name}({call.function.arguments})")

Depois que seu código executa a ferramenta real, anexe o resultado como uma mensagem de função tool e chame novamente. O loop termina quando finish_reason == "stop" e tool_calls estiver vazio.

Um detalhe: o ERNIE 5.1 ocasionalmente retorna os argumentos da ferramenta como um JSON stringificado dentro de um bloco de código em vez de uma string JSON limpa. Faça o parse defensivamente com json.loads() envolvido em try/except, e se falhar, remova os blocos de código ```json antes de tentar novamente.

Passo 6: Chame o ERNIE 5.1 a partir do Node.js

Integração direta para qualquer projeto Node que use openai v5+:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QIANFAN_API_KEY,
  baseURL: "https://qianfan.baidubce.com/v2",
});

const completion = await client.chat.completions.create({
  model: "ernie-5.1",
  messages: [
    { role: "user", content: "Return a JSON object with 3 API design tips." },
  ],
  response_format: { type: "json_object" },
});

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

response_format: { type: "json_object" } funciona e é confiável. Esquemas JSON estritos (json_schema) ainda estão sendo implementados no Qianfan; verifique o formato da resposta no código em vez de confiar na restrição.

Passo 7: Teste e compare com Apidog

Se você está decidindo entre ERNIE 5.1, DeepSeek V4 e Kimi K2.6, não faça isso pelo terminal. Use Apidog para construir um único espaço de trabalho com uma pasta para cada provedor, corpos de requisição idênticos e ambientes salvos por chave de API.

A configuração de 60 segundos:

Abra o Apidog e crie um novo projeto chamado "LLM bake-off."

Adicione um ambiente com QIANFAN_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY como variáveis.

Crie três requisições apontando para a URL base de cada provedor com model definido para ernie-5.1, deepseek-chat e kimi-k2-6 respectivamente.

Fixe o mesmo array de messages em todos os três. Use o recurso "Run" do Apidog para executá-los em paralelo e comparar as saídas.

O nível gratuito lida com isso confortavelmente. Apidog salva o histórico de requisições por ambiente, para que você possa voltar na próxima semana e reexecutar a mesma avaliação exata contra uma nova versão do modelo. É melhor do que ficar gerenciando curl em um painel tmux.

Para mais informações sobre testes com múltiplos provedores, consulte Teste LLMs locais como APIs e nosso guia da API GLM 5.1.

Preços, limites de taxa e cotas

Os preços públicos do Qianfan para o ERNIE 5.1 não foram incluídos no post de lançamento; verifique o cartão de taxas do console ao vivo antes de citar números internamente. Três dicas práticas enquanto você espera:

Os limites de taxa padrão são definidos por espaço de trabalho. Novas contas começam com um baixo limite de QPS (queries por segundo). Aumente-o no console assim que terminar os testes.
O uso de tokens aparece na resposta. O campo usage fornece prompt_tokens, completion_tokens e total_tokens por chamada. Registre-os por requisição; não confie apenas no painel para a contabilidade de custos.
O cache não é automático. Ao contrário do Anthropic, o Qianfan atualmente não expõe um primitivo de cache de prompt para o ERNIE 5.1. Se você tem um prompt de sistema de 2.000 tokens, você paga por ele em cada chamada. Arquitete seu sistema levando isso em conta.

Tratamento de erros que o salvará

Os erros que você encontrará na prática, em ordem aproximada de frequência:

Status	Significado	Correção
401	Token Bearer errado ou expirado	Regenerar no console
403	Modelo não habilitado neste espaço de trabalho	Adicionar ERNIE 5.1 no console
429	Limite de taxa atingido	Backoff + nova tentativa com jitter
400 (`invalid messages`)	Ordenação de `message-role` errada	Garantir alternância de `user`/`assistant`
500/502	Falha no Qianfan	Tentar novamente uma vez; se persistir, verificar a página de status

Envolva cada chamada em um mecanismo de repetição com backoff exponencial limitado a 3 tentativas. Para produção, registre o request_id dos cabeçalhos de resposta; o suporte Baidu precisa dele para depurar seu caso.

Um wrapper mínimo com formato de produção

Se você deseja integrar o ERNIE 5.1 em um aplicativo real hoje, aqui está o menor wrapper que não é embaraçoso:

import os, time, random, json
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

def chat(messages, *, model="ernie-5.1", temperature=0.3, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                temperature=temperature,
            )
        except RateLimitError:
            time.sleep((2 ** attempt) + random.random())
        except APIError as e:
            if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(1 + attempt)
                continue
            raise
    raise RuntimeError("ERNIE 5.1 retries exhausted")

Isso cobre 80% dos casos. Para loops de ferramenta e streaming, construa em cima disso.

Perguntas Frequentes

A API do ERNIE 5.1 é gratuita? Não. O Qianfan funciona no modelo de pagamento conforme o uso. Não há um nível gratuito permanente; novas contas às vezes recebem créditos de teste. Para experimentação gratuita, use a interface de chat em ernie.baidu.com ou procure por opções gratuitas de LLM.

Posso executar o ERNIE 5.1 localmente? Não. Não há pesos públicos. Se a implantação local for um requisito rígido, veja como executar o DeepSeek V4 localmente ou os melhores LLMs locais em 2026.

O SDK da OpenAI funciona sem alterações? Sim, com base_url definido para https://qianfan.baidubce.com/v2 e api_key definido para sua chave Qianfan. O campo model aceita IDs de modelo Qianfan, não da OpenAI. Chamada de função, streaming e response_format: json_object funcionam. A validação estrita de json_schema ainda está sendo lançada.

Como o ERNIE 5.1 lida com prompts em chinês versus inglês? Ambos são de primeira classe. A pontuação de 1.223 no Arena Search veio de um grupo de eleitores de idiomas mistos. Para tarefas técnicas em inglês (código, design de API), ele é competitivo com a fronteira fechada; para escrita criativa em chinês, é o melhor da categoria entre os modelos chineses.

Qual é o comprimento máximo de saída? Não publicado oficialmente. Na prática, respostas de uma única vez chegam a cerca de 8K tokens antes que o modelo finalize. Para geração de textos longos, divida e continue.

Construindo um agente no ERNIE 5.1? Baixe o Apidog e use a coleção de requisições compatíveis com OpenAI para simular, testar e documentar o endpoint Qianfan junto com o restante dos seus serviços.