Cómo Usar la API de ERNIE 5.1

ERNIE 5.1 fue lanzado el 9 de mayo de 2026, y en una semana la API de Qianfan ya estaba disponible para él. Si deseas llamar al modelo desde tu propio código, enrutar llamadas a herramientas a través de él, o conectarlo a un ciclo de agente con Apidog, esta guía te muestra el camino completo: cuenta, clave, cuerpo de solicitud, streaming, uso de herramientas, manejo de errores.

Lo mantendremos práctico. Al final tendrás fragmentos funcionales de curl, Python y Node, además de una colección de solicitudes que puedes importar a Apidog.

Si aún no has leído el análisis del lanzamiento de ERNIE 5.1, échale un vistazo primero; cubre los puntos de referencia y las ventajas/desventajas frente a DeepSeek V4 y Kimi K2.6. Esta publicación es el complemento de implementación.

Paso 1: Obtén una clave API de Qianfan

ERNIE 5.1 se ofrece a través de la plataforma Qianfan de Baidu Intelligent Cloud. No existe una "API de ERNIE" separada; todo se enruta a través de Qianfan.

Ve a cloud.baidu.com y crea o inicia sesión en una cuenta de Baidu Intelligent Cloud. Los desarrolladores internacionales pueden usar el registro por correo electrónico; algunas características empresariales aún requieren un número de teléfono continental.
Abre la consola de Qianfan en console.bce.baidu.com/qianfan.
En Gestión de claves API (API Key 管理), haz clic en Crear clave API. Selecciona el espacio de trabajo y concede acceso al servicio de finalización de chat.
Copia la clave. Tiene un formato similar a bce-v3/ALTAK-xxxx/xxxx. Almacénala en una variable de entorno, no en el código fuente.

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

Dos cosas que debes saber de antemano. Primero, el nuevo endpoint v2 utiliza un único token Bearer; el flujo access_token de OAuth v1 anterior está siendo deprecado y no debes construir nuevo código sobre él. Segundo, ERNIE 5.1 es un modelo de pago desde el primer día. Recarga un pequeño saldo (¥10 son suficientes para probar) antes de tu primera solicitud.

Paso 2: Accede al endpoint compatible con OpenAI usando curl

Qianfan expone un endpoint de finalización de chat compatible con OpenAI, por lo que cualquier elemento de tu pila que ya hable el formato de OpenAI funcionará con un cambio de URL base y un cambio de ID de modelo.

URL Base: https://qianfan.baidubce.com/v2 ID del Modelo: ernie-5.1 (también: ernie-5.1-preview para características de acceso anticipado)

Solicitud mínima viable:

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": "Eres un diseñador de API experimentado."},
      {"role": "user", "content": "Esboza un esquema REST para una API de revisión de PR al estilo GitHub. Sé conciso."}
    ],
    "temperature": 0.3
  }'

Obtienes una respuesta con formato estándar de 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
  }
}

Si ves 401 Unauthorized, tu clave es incorrecta o ha expirado. Si ves 403, la clave es válida pero el modelo no está habilitado en este espacio de trabajo; vuelve a la consola y añade ERNIE 5.1 a los modelos permitidos del espacio de trabajo.

Paso 3: Llama a ERNIE 5.1 desde Python

Dado que el endpoint es compatible con OpenAI, el SDK oficial de Python openai funciona tal cual. Apúntalo a 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": "Explicas APIs en inglés sencillo."},
        {"role": "user", "content": "¿Por qué usaría eventos enviados por el servidor en lugar de WebSockets para una interfaz de usuario de chat?"},
    ],
    temperature=0.4,
)

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

Si ya tienes envoltorios alrededor del SDK de OpenAI en tu base de código, intercambiar ERNIE 5.1 para pruebas A/B es un cambio de una sola línea. El mismo truco funciona para la API de DeepSeek y la mayoría de los otros proveedores de modelos chinos.

Paso 4: Transmite tokens para interfaces de usuario de estilo chat

Para cualquier chat orientado al usuario, querrás streaming (transmisión). Configura stream: true y consume eventos enviados por el servidor.

stream = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "Escribe un haiku sobre el versionado de API."}],
    stream=True,
)

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

Equivalente en Curl para depuración:

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": "Transmite un chiste de 3 frases."}]
  }' \
  --no-buffer

El formato del stream es idéntico al de OpenAI: líneas data: {...} terminadas por data: [DONE].

Paso 5: Usa ERNIE 5.1 con herramientas (la parte de agente)

Aquí es donde ERNIE 5.1 se gana su titular de lanzamiento. El modelo obtuvo una puntuación superior a DeepSeek-V4-Pro en τ³-bench y SpreadsheetBench-Verified, lo que significa que la llamada a herramientas funciona en producción, no solo en demostraciones.

Mismo esquema que la llamada a funciones de OpenAI:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtener el tiempo actual para una ciudad.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Nombre de la ciudad, ej. Singapur"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "¿Qué tiempo hace en Tokio ahora mismo?"}],
    tools=tools,
    tool_choice="auto",
)

tool_calls = response.choices[0].message.tool_calls
if tool_calls:
    call = tool_calls[0]
    print(f"El modelo quiere llamar a: {call.function.name}({call.function.arguments})")

Después de que tu código ejecute la herramienta real, añade el resultado como un mensaje con rol tool y vuelve a llamar. El bucle termina cuando finish_reason == "stop" y tool_calls está vacío.

Una advertencia: ERNIE 5.1 ocasionalmente devuelve los argumentos de la herramienta como un JSON serializado dentro de un bloque de código en lugar de como una cadena JSON limpia. Analiza de forma defensiva con json.loads() envuelto en try/except, y si falla, elimina los delimitadores ```json antes de reintentar.

Paso 6: Llama a ERNIE 5.1 desde Node.js

Plug-and-play para cualquier proyecto 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: "Devuelve un objeto JSON con 3 consejos de diseño de API." },
  ],
  response_format: { type: "json_object" },
});

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

response_format: { type: "json_object" } funciona y es fiable. Los esquemas JSON estrictos (json_schema) todavía se están implementando en Qianfan; verifica la forma de la respuesta en el código en lugar de confiar en la restricción.

Paso 7: Prueba y compara con Apidog

Si estás decidiendo entre ERNIE 5.1, DeepSeek V4 y Kimi K2.6, no lo hagas desde la terminal. Usa Apidog para construir un único espacio de trabajo con una carpeta por proveedor, cuerpos de solicitud idénticos y entornos guardados por clave API.

La configuración en 60 segundos:

Abre Apidog y crea un nuevo proyecto llamado “LLM bake-off.”

Añade un entorno con QIANFAN_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY como variables.

Crea tres solicitudes apuntando a la URL base de cada proveedor con model configurado a ernie-5.1, deepseek-chat y kimi-k2-6 respectivamente.

Fija el mismo array de messages en las tres. Usa la función “Run” de Apidog para ejecutarlas en paralelo y comparar las salidas.

El nivel gratuito lo maneja cómodamente. Apidog guarda el historial de solicitudes por entorno, para que puedas volver la próxima semana y volver a ejecutar la misma evaluación exacta contra una nueva versión del modelo. Es mejor que supervisar curl en un panel de tmux.

Para más información sobre pruebas multi-proveedor, consulta Prueba LLMs locales como APIs y nuestra guía de la API de GLM 5.1.

Precios, límites de tasa y cuotas

Los precios públicos de Qianfan para ERNIE 5.1 no estaban en la publicación de lanzamiento; revisa la tarjeta de tarifas de la consola en vivo antes de citar números internamente. Tres consejos prácticos mientras esperas:

Los límites de tasa predeterminados están sujetos al espacio de trabajo. Las cuentas nuevas comienzan con un límite bajo de QPS. Auméntalo desde la consola una vez que termines de probar.
El uso de tokens aparece en la respuesta. El campo usage proporciona prompt_tokens, completion_tokens y total_tokens por llamada. Registra estos por solicitud; no confíes únicamente en el panel de control para la contabilidad de costos.
El almacenamiento en caché no es automático. A diferencia de Anthropic, Qianfan no expone actualmente una primitiva de caché de prompts para ERNIE 5.1. Si tienes un prompt de sistema de 2,000 tokens, lo pagas en cada llamada. Diseña tu arquitectura en torno a esto.

Manejo de errores que te salvará

Los errores que encontrarás en la práctica, en un orden aproximado de frecuencia:

Estado	Significado	Solución
401	Token Bearer incorrecto o expirado	Regenerar desde la consola
403	Modelo no habilitado en este espacio de trabajo	Añadir ERNIE 5.1 en la consola
429	Límite de tasa alcanzado	Retroceso + reintento con jitter
400 (`invalid messages`)	Orden incorrecto de rol de mensaje	Asegurar alternancia usuario/asistente
500/502	Fallo temporal en Qianfan	Reintentar una vez; si persiste, revisar página de estado

Envuelve cada llamada en un reintento con retroceso exponencial, limitado a 3 intentos. Para producción, registra el request_id de los encabezados de respuesta; el soporte de Baidu lo necesita para depurar tu caso.

Un envoltorio mínimo con forma de producción

Si quieres integrar ERNIE 5.1 en una aplicación real hoy, aquí tienes el envoltorio más pequeño que no es vergonzoso:

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("Reintentos de ERNIE 5.1 agotados")

Eso maneja el 80% de los casos. Para bucles de herramientas y streaming, construye sobre esto.

Preguntas frecuentes

¿Es gratuita la API de ERNIE 5.1? No. Qianfan es de pago por uso. No hay un nivel gratuito permanente; las cuentas nuevas a veces reciben créditos de prueba. Para experimentación gratuita, usa la interfaz de chat de ernie.baidu.com o busca opciones de LLM gratuitas.

¿Puedo ejecutar ERNIE 5.1 localmente? No. No hay pesos públicos. Si la implementación local es un requisito estricto, consulta cómo ejecutar DeepSeek V4 localmente o los mejores LLMs locales en 2026 en su lugar.

¿Funciona el SDK de OpenAI sin cambios? Sí, con base_url configurado a https://qianfan.baidubce.com/v2 y api_key configurado a tu clave de Qianfan. El campo model acepta IDs de modelos de Qianfan, no de OpenAI. La llamada a funciones, el streaming y response_format: json_object funcionan todos. La validación estricta de json_schema todavía se está implementando.

¿Cómo maneja ERNIE 5.1 los prompts en chino versus inglés? Ambos son de primera clase. La puntuación de Arena Search de 1,223 provino de un grupo de votantes de idiomas mixtos. Para tareas técnicas en inglés (código, diseño de API), es competitivo con la frontera cerrada; para la escritura creativa en chino es el mejor de su clase entre los modelos chinos.

¿Cuál es la longitud máxima de salida? No publicado oficialmente. En la práctica, las respuestas de un solo turno se limitan a unos 8K tokens antes de que el modelo finalice. Para la generación de formato largo, divide en fragmentos y continúa.

¿Estás construyendo un agente sobre ERNIE 5.1? Descarga Apidog y usa la colección de solicitudes compatible con OpenAI para simular, probar y documentar el endpoint de Qianfan junto con el resto de tus servicios.