DEV Community

Cover image for Cómo Usar la API de ERNIE 5.1
Roobia
Roobia

Posted on • Originally published at apidog.com

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 quieres llamar al modelo desde tu código, enrutar llamadas a herramientas o conectarlo a un ciclo de agente con Apidog, esta guía cubre el flujo completo: cuenta, clave, cuerpo de solicitud, streaming, herramientas y manejo de errores.

Prueba Apidog hoy

El enfoque será práctico. Al final tendrás ejemplos funcionales con curl, Python y Node.js, además de una estructura de solicitudes que puedes reproducir en Apidog.

Si todavía no has leído el análisis del lanzamiento de ERNIE 5.1, revísalo primero. Ahí se cubren benchmarks y comparativas frente a DeepSeek V4 y Kimi K2.6. Esta publicación es el complemento de implementación.

ERNIE 5.1

Paso 1: Obtén una clave API de Qianfan

ERNIE 5.1 se ofrece a través de Qianfan, la plataforma de Baidu Intelligent Cloud. No hay una “API de ERNIE” separada: las llamadas pasan por Qianfan.

  1. Ve a cloud.baidu.com y crea una cuenta o inicia sesión en Baidu Intelligent Cloud.
  2. Abre la consola de Qianfan: console.bce.baidu.com/qianfan.
  3. En Gestión de claves API (API Key 管理), haz clic en Crear clave API.
  4. Selecciona el espacio de trabajo y habilita el acceso al servicio de chat completions.
  5. Copia la clave y guárdala como variable de entorno. 
export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"
Enter fullscreen mode Exit fullscreen mode

Ten en cuenta dos puntos:

  • El endpoint v2 usa un único token Bearer. El flujo antiguo con access_token de OAuth v1 está siendo deprecado.
  • ERNIE 5.1 es de pago desde el primer día. Recarga un saldo pequeño antes de hacer pruebas.

Paso 2: Llama al endpoint compatible con OpenAI usando curl

Qianfan expone un endpoint de chat completions compatible con OpenAI. Si tu stack ya usa el formato de OpenAI, normalmente solo tienes que cambiar la URL base y el ID del modelo.

URL base:

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

Modelo:

ernie-5.1
Enter fullscreen mode Exit fullscreen mode

También existe ernie-5.1-preview para características de acceso anticipado.

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

Respuesta 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

Errores comunes:

  • 401 Unauthorized: clave incorrecta o expirada.
  • 403 Forbidden: la clave es válida, pero el modelo no está habilitado en ese espacio de trabajo.

Paso 3: Llama a ERNIE 5.1 desde Python

Como el endpoint es compatible con OpenAI, puedes usar el SDK oficial openai apuntándolo 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 usados: {response.usage.total_tokens}")
Enter fullscreen mode Exit fullscreen mode

Si ya tienes wrappers internos sobre el SDK de OpenAI, probar ERNIE 5.1 suele ser un cambio de una línea: base_url y model.

El mismo patrón funciona con la API de DeepSeek y otros proveedores compatibles con OpenAI.

Paso 4: Usa streaming para interfaces de chat

Para una UI de chat, activa 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)
Enter fullscreen mode Exit fullscreen mode

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

El formato del stream sigue el patrón de OpenAI:

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

Paso 5: Usa ERNIE 5.1 con herramientas

ERNIE 5.1 soporta un esquema similar a la llamada a funciones de OpenAI. Define tus herramientas, deja que el modelo elija una y ejecuta la llamada en tu backend.

Ejemplo:

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

El flujo de implementación es:

  1. Envías messages + tools.
  2. El modelo responde con tool_calls.
  3. Tu código ejecuta la herramienta real.
  4. Añades el resultado como un mensaje con rol tool.
  5. Vuelves a llamar al modelo.
  6. Terminas cuando finish_reason == "stop" y no hay tool_calls.

Implementa el parseo de argumentos de forma defensiva. ERNIE 5.1 puede devolver argumentos como JSON serializado limpio o dentro de un bloque de código. Usa json.loads() con try/except y, si falla, elimina delimitadores como

```json antes de reintentar.

Paso 6: Llama a ERNIE 5.1 desde Node.js

En Node.js, el SDK openai v5+ también funciona cambiando baseURL.


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

response_format: { type: "json_object" } funciona para respuestas JSON. Los esquemas JSON estrictos (json_schema) todavía se están implementando en Qianfan, así que valida la respuesta en tu aplicación.

Paso 7: Prueba y compara con Apidog

Si estás comparando ERNIE 5.1, DeepSeek V4 y Kimi K2.6, evita hacerlo manualmente desde la terminal. Usa Apidog para crear un workspace con una carpeta por proveedor, cuerpos de solicitud equivalentes y entornos separados por clave API.

Configuración rápida:

  1. Crea un nuevo proyecto llamado LLM bake-off.

Crear proyecto en Apidog

  1. Añade un entorno con estas variables:

text
QIANFAN_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
Enter fullscreen mode Exit fullscreen mode

Variables de entorno en Apidog

  1. Crea tres solicitudes con la URL base de cada proveedor.
  2. Configura el campo model así:

json
{
  "ernie": "ernie-5.1",
  "deepseek": "deepseek-chat",
  "kimi": "kimi-k2-6"
}
Enter fullscreen mode Exit fullscreen mode
  1. Usa el mismo array de messages en las tres solicitudes.
  2. Ejecuta las solicitudes con la función Run de Apidog para comparar resultados.

Apidog guarda el historial de solicitudes por entorno. Eso te permite repetir la misma evaluación más adelante contra nuevas versiones del modelo, sin reconstruir el experimento.

Para pruebas multi-proveedor, también puedes revisar Prueba LLMs locales como APIs y la 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. Antes de citar cifras internamente, revisa la tarjeta de tarifas en la consola.

Puntos prácticos:

  • Los límites de tasa dependen del espacio de trabajo. Las cuentas nuevas suelen empezar con QPS bajo. Solicita aumento desde la consola cuando termines tus pruebas.
  • El uso de tokens viene en la respuesta. Registra prompt_tokens, completion_tokens y total_tokens por solicitud.
  • El caché de prompts no es automático. Qianfan no expone actualmente una primitiva de caché de prompts para ERNIE 5.1. Si envías un prompt de sistema de 2.000 tokens, lo pagas en cada llamada.

Manejo de errores

Errores típicos en producción:

Estado Significado Solución
401 Token Bearer incorrecto o expirado Regenerar la clave desde la consola
403 Modelo no habilitado en el espacio de trabajo Añadir ERNIE 5.1 en la consola
429 Límite de tasa alcanzado Reintentar con backoff y jitter
400 invalid messages Orden incorrecto de roles Validar la secuencia de mensajes
500/502 Fallo temporal en Qianfan Reintentar una vez y revisar estado si persiste

Envuelve cada llamada con reintentos usando retroceso exponencial, limitado a 3 intentos. En producción, registra el request_id de los encabezados de respuesta; el soporte de Baidu lo necesitará para depurar incidentes.

Wrapper mínimo para producción

Un wrapper básico en Python:


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

Este wrapper cubre el caso base: autenticación, modelo, temperatura y reintentos. Para streaming y herramientas, constrúyelos encima de esta función o separa wrappers específicos por flujo.

Preguntas frecuentes

¿Es gratuita la API de ERNIE 5.1?

No. Qianfan funciona con pago por uso. No hay un nivel gratuito permanente, aunque algunas cuentas nuevas pueden recibir créditos de prueba. Para experimentación gratuita, usa la interfaz de chat de ernie.baidu.com o revisa opciones de LLM gratuitas.

¿Puedo ejecutar ERNIE 5.1 localmente?

No. No hay pesos públicos. Si necesitas despliegue local, revisa cómo ejecutar DeepSeek V4 localmente o los mejores LLMs locales en 2026.

¿Funciona el SDK de OpenAI sin cambios?

Sí, configurando:


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

El campo model debe usar IDs de Qianfan, como ernie-5.1. Streaming, llamadas a herramientas y response_format: json_object funcionan. La validación estricta con json_schema todavía se está implementando.

¿Cómo maneja ERNIE 5.1 prompts en chino e inglés?

Ambos son casos de uso principales. Para tareas técnicas en inglés, como código y diseño de API, es competitivo. Para escritura creativa en chino, destaca entre los modelos chinos.

¿Cuál es la longitud máxima de salida?

No está publicada oficialmente. En la práctica, las respuestas de un solo turno se limitan a alrededor de 8K tokens antes de finalizar. Para generación larga, divide el trabajo en fragmentos y continúa por partes.

Si estás construyendo un agente sobre ERNIE 5.1, descarga Apidog y usa una colección de solicitudes compatible con OpenAI para simular, probar y documentar el endpoint de Qianfan junto con el resto de tus servicios.

Top comments (0)