DEV Community

Cover image for Como Usar a API ERNIE 5.1: Guia Completo
Lucas
Lucas

Posted on • Originally published at apidog.com

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 o modelo. Se você quer chamar o modelo a partir do seu código, rotear chamadas de ferramenta ou integrá-lo a um loop de agente com Apidog, este guia mostra o caminho completo: conta, chave, payload, streaming, ferramentas e tratamento de erros.

Experimente o Apidog hoje

Ao final, você terá exemplos funcionais em curl, Python e Node.js, além de uma estrutura prática para testar o ERNIE 5.1 no Apidog.

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

Passo 1: Obtenha uma chave de API Qianfan

ERNIE 5.1 é servido pela plataforma Qianfan da Baidu Intelligent Cloud. Não existe uma “API ERNIE” separada; as chamadas passam pelo Qianfan.

  1. Acesse cloud.baidu.com e crie ou entre em uma conta Baidu Intelligent Cloud.
  2. Abra o console Qianfan em console.bce.baidu.com/qianfan.
  3. Em Gerenciamento de Chaves de API (API Key 管理), clique em Criar Chave de API.
  4. Escolha o workspace e conceda acesso ao serviço chat-completions.
  5. Copie a chave. Ela deve ter um formato parecido com: 
bce-v3/ALTAK-xxxx/xxxx
Enter fullscreen mode Exit fullscreen mode

Salve a chave como variável de ambiente:

export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • O endpoint v2 usa um único token Bearer.
  • O fluxo OAuth antigo com access_token v1 está sendo descontinuado.
  • O ERNIE 5.1 é pago desde o primeiro dia. Recarregue um pequeno saldo antes do primeiro teste.

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

O Qianfan expõe um endpoint chat-completions compatível com OpenAI. Na prática, você troca a URL base, o token e o ID do modelo.

URL base:

https://qianfan.baidubce.com/v2
Enter fullscreen mode Exit fullscreen mode

Modelo:

ernie-5.1
Enter fullscreen mode Exit fullscreen mode

Também existe ernie-5.1-preview para recursos de acesso antecipado.

Requisição mínima:

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
  }'
Enter fullscreen mode Exit fullscreen mode

Resposta esperada:

{
  "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
  }
}
Enter fullscreen mode Exit fullscreen mode

Erros comuns nesta etapa:

Status Causa provável Correção
401 Unauthorized Chave inválida ou expirada Gere uma nova chave no console
403 Forbidden Modelo não habilitado no workspace Habilite o ERNIE 5.1 no Qianfan

Passo 3: Chame o ERNIE 5.1 com Python

Como o endpoint é compatível com OpenAI, você pode usar o SDK oficial openai apontando para o Qianfan.

Instale o SDK:

pip install openai
Enter fullscreen mode Exit fullscreen mode

Exemplo:

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}")
Enter fullscreen mode Exit fullscreen mode

Se sua aplicação já usa wrappers em torno do SDK da OpenAI, testar ERNIE 5.1 costuma exigir apenas:

base_url="https://qianfan.baidubce.com/v2"
model="ernie-5.1"
Enter fullscreen mode Exit fullscreen mode

O mesmo padrão também funciona com a API do DeepSeek e vários outros provedores compatíveis.

Passo 4: Use streaming para interfaces de chat

Para interfaces de chat, use stream: true e consuma Server-Sent Events.

Exemplo em Python:

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)
Enter fullscreen mode Exit fullscreen mode

Exemplo equivalente com curl:

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
Enter fullscreen mode Exit fullscreen mode

O formato do stream segue o padrão OpenAI:

data: {...}
data: {...}
data: [DONE]
Enter fullscreen mode Exit fullscreen mode

Passo 5: Use ERNIE 5.1 com ferramentas

O ERNIE 5.1 usa o mesmo esquema de chamada de função da OpenAI. Você define uma lista de ferramentas, envia junto com a conversa e deixa o modelo decidir quando chamar uma função.

Exemplo de definição de ferramenta:

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"],
            },
        },
    }
]
Enter fullscreen mode Exit fullscreen mode

Chamada com tool_choice="auto":

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})")
Enter fullscreen mode Exit fullscreen mode

Fluxo recomendado:

  1. Envie messages + tools.
  2. Verifique se a resposta contém tool_calls.
  3. Execute a função real no seu backend.
  4. Adicione o resultado como mensagem tool.
  5. Chame o modelo novamente.
  6. Termine quando finish_reason == "stop" e não houver tool_calls.

Exemplo de parse defensivo para argumentos de ferramenta:

import json
import re

def parse_tool_arguments(raw):
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        cleaned = re.sub(r"^```

json|

```$", "", raw.strip(), flags=re.MULTILINE).strip()
        return json.loads(cleaned)
Enter fullscreen mode Exit fullscreen mode

Isso é útil porque o modelo pode ocasionalmente retornar argumentos como JSON dentro de um bloco de código, em vez de uma string JSON limpa.

Passo 6: Chame o ERNIE 5.1 com Node.js

Para projetos Node.js usando openai v5+:

npm install openai
Enter fullscreen mode Exit fullscreen mode

Exemplo:

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);
Enter fullscreen mode Exit fullscreen mode

response_format: { type: "json_object" } funciona bem para respostas JSON. Já esquemas JSON estritos com json_schema ainda estão sendo implementados no Qianfan, então valide a resposta no seu código.

Exemplo simples de validação:

const content = completion.choices[0].message.content;

let parsed;

try {
  parsed = JSON.parse(content);
} catch (error) {
  throw new Error(`Resposta não é JSON válido: ${content}`);
}

console.log(parsed);
Enter fullscreen mode Exit fullscreen mode

Passo 7: Teste e compare com Apidog

Se você está comparando ERNIE 5.1, DeepSeek V4 e Kimi K2.6, evite gerenciar vários comandos curl manualmente. Use Apidog para criar um workspace com uma pasta por provedor, bodies padronizados e ambientes separados por chave de API.

Configuração rápida:

  1. Abra o Apidog.
  2. Crie um projeto chamado LLM bake-off.

  1. Adicione um ambiente com as variáveis: 
QIANFAN_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
Enter fullscreen mode Exit fullscreen mode

  1. Crie três requisições, uma para cada provedor.
  2. Configure o campo model conforme o provedor: 
{
  "model": "ernie-5.1"
}
Enter fullscreen mode Exit fullscreen mode 
{
  "model": "deepseek-chat"
}
Enter fullscreen mode Exit fullscreen mode 
{
  "model": "kimi-k2-6"
}
Enter fullscreen mode Exit fullscreen mode
  1. Use o mesmo array messages em todas as requisições.
  2. Execute com o recurso Run do Apidog para comparar as saídas.

O nível gratuito lida bem com esse fluxo. O Apidog também salva o histórico de requisições por ambiente, o que facilita repetir o mesmo teste quando um provedor atualizar o modelo.

Para mais testes com múltiplos provedores, veja Teste LLMs locais como APIs e o 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 no console antes de usar números em estimativas internas.

Na implementação, acompanhe três pontos:

  • Limites de taxa são definidos por workspace. Contas novas começam com QPS baixo. Aumente o limite no console depois dos testes iniciais.
  • O uso de tokens vem na resposta. Registre prompt_tokens, completion_tokens e total_tokens por requisição.
  • Cache não é automático. O Qianfan atualmente não expõe um primitivo de cache de prompt para o ERNIE 5.1. Se seu system prompt tem 2.000 tokens, você paga por ele em cada chamada.

Exemplo de log de uso:

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=messages,
)

usage = response.usage

print({
    "prompt_tokens": usage.prompt_tokens,
    "completion_tokens": usage.completion_tokens,
    "total_tokens": usage.total_tokens,
})
Enter fullscreen mode Exit fullscreen mode

Tratamento de erros

Erros mais comuns em produção:

Status Significado Correção
401 Token Bearer errado ou expirado Regenerar a chave no console
403 Modelo não habilitado no workspace Adicionar ERNIE 5.1 no console
429 Limite de taxa atingido Backoff + nova tentativa com jitter
400 invalid messages Ordem incorreta de message.role Validar alternância e estrutura das mensagens
500/502 Falha no Qianfan Tentar novamente uma vez; se persistir, verificar status/suporte

Use repetição com backoff exponencial e limite de tentativas. Em produção, registre também o request_id dos headers de resposta, porque o suporte da Baidu pode precisar dele para depuração.

Wrapper mínimo para produção

Um wrapper simples, com retry para rate limit e erros 5xx:

import os
import time
import random

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:
            sleep_seconds = (2 ** attempt) + random.random()
            time.sleep(sleep_seconds)

        except APIError as e:
            should_retry = (
                e.status_code is not None
                and e.status_code >= 500
                and attempt < max_retries - 1
            )

            if should_retry:
                time.sleep(1 + attempt)
                continue

            raise

    raise RuntimeError("ERNIE 5.1 retries exhausted")
Enter fullscreen mode Exit fullscreen mode

Uso:

messages = [
    {
        "role": "system",
        "content": "You are a concise API design assistant."
    },
    {
        "role": "user",
        "content": "Design a pagination strategy for a REST API."
    },
]

response = chat(messages)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Esse wrapper cobre a maioria dos casos básicos. Para streaming e tool calling, construa em cima da mesma ideia: timeout, retry controlado, logs de uso e validação da resposta.

Perguntas frequentes

A API do ERNIE 5.1 é gratuita?

Não. O Qianfan funciona em modelo de pagamento conforme o uso. Não há um nível gratuito permanente, embora novas contas às vezes recebam créditos de teste.

Para experimentação gratuita, use a interface de chat em ernie.baidu.com ou veja opções gratuitas de LLM.

Posso executar o ERNIE 5.1 localmente?

Não. Não há pesos públicos. Se implantação local for requisito, veja como executar o DeepSeek V4 localmente ou os melhores LLMs locais em 2026.

O SDK da OpenAI funciona sem alterações?

Funciona com estas mudanças:

base_url="https://qianfan.baidubce.com/v2"
api_key=os.environ["QIANFAN_API_KEY"]
model="ernie-5.1"
Enter fullscreen mode Exit fullscreen mode

Chamada de função, streaming e response_format: json_object funcionam. Validação estrita com json_schema ainda está sendo lançada.

Como o ERNIE 5.1 lida com prompts em chinês e inglês?

Ambos são tratados como idiomas 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, como código e design de API, ele é competitivo com modelos fechados de fronteira. Para escrita criativa em chinês, é um dos principais modelos chineses.

Qual é o comprimento máximo de saída?

Não foi publicado oficialmente. Na prática, respostas de uma única chamada chegam a cerca de 8K tokens antes de finalizar. Para textos longos, divida a geração em partes e continue a partir do contexto anterior.

Próximo passo

Se você está construindo um agente com ERNIE 5.1, baixe o Apidog e use requisições compatíveis com OpenAI para simular, testar e documentar o endpoint Qianfan junto com o restante dos seus serviços.

Top comments (0)