Cómo usar la API GLM-5.1: guía completa con ejemplos de código

TL;DR

GLM-5.1 está disponible vía la API de BigModel en https://open.bigmodel.cn/api/paas/v4/. La API es compatible con OpenAI: misma estructura de endpoint, formato de solicitud y patrón de streaming. Solo necesitas una cuenta de BigModel, una clave API y el nombre del modelo glm-5.1. Esta guía muestra autenticación, primera solicitud, streaming, llamada a herramientas y cómo probar tu integración con Apidog.

Prueba Apidog hoy

Introducción

GLM-5.1 es el modelo agéntico insignia de Z.AI, lanzado en abril de 2026. Es #1 en SWE-Bench Pro y supera a GLM-5 en los principales benchmarks de codificación. Si desarrollas asistentes de codificación IA, agentes autónomos o apps que requieren tareas de larga duración, integra GLM-5.1.

La API es 100% compatible con OpenAI. Si ya usas GPT-4 o Claude, cambia solo la URL base y el nombre del modelo. No necesitas aprender un nuevo SDK ni lidiar con formatos de respuesta diferentes.

💡 Tip: El mayor reto con APIs agénticas es la prueba. Los agentes pueden ejecutar cientos de llamadas a herramientas en minutos, difícil de testear sin consumir cuota. Apidog soluciona esto: define toda la secuencia de solicitudes, simula respuestas para cada estado y verifica que tu integración maneje correctamente streaming, llamadas a herramientas y errores antes de producción.

Requisitos previos

Antes de empezar:

1. Cuenta en BigModel en bigmodel.cn
2. Clave API desde la consola de BigModel, sección “API Keys”
3. Python 3.8+ o Node.js 18+ (los ejemplos cubren ambos)
4. SDK de OpenAI o librerías estándar requests/fetch

Configura la clave API como variable de entorno:

export BIGMODEL_API_KEY="tu_clave_api_aquí"

Nunca incluyas claves API en el código fuente.

Autenticación

Cada solicitud requiere este encabezado:

Authorization: Bearer TU_CLAVE_API

La clave API de BigModel tiene formato xxxxxxxx.xxxxxxxxxxxxxxxx (dos bloques separados por punto). No uses el prefijo sk-, pero funciona igual en el header.

URL base

https://open.bigmodel.cn/api/paas/v4/

El endpoint de chat:

POST https://open.bigmodel.cn/api/paas/v4/chat/completions

Tu primera solicitud

Usando curl

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {
        "role": "user",
        "content": "Escribe una función en Python que encuentre todos los números primos hasta n usando la Criba de Eratóstenes."
      }
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

Usando Python (requests)

import os
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [
            {
                "role": "user",
                "content": "Escribe una función en Python que encuentre todos los números primos hasta n usando la Criba de Eratóstenes."
            }
        ],
        "max_tokens": 1024,
        "temperature": 0.7
    }
)

result = response.json()
print(result["choices"][0]["message"]["content"])

Usando el SDK de OpenAI (recomendado)

Puedes usar el SDK oficial de OpenAI para Python con URL base personalizada:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Escribe una función en Python que encuentre todos los números primos hasta n usando la Criba de Eratóstenes."
        }
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)

Este método es ideal: el SDK maneja reintentos, timeouts y parsing de respuestas automáticamente.

Formato de respuesta

La estructura es idéntica a OpenAI:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve_of_eratosthenes(n):\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 215,
    "total_tokens": 247
  }
}

Accede al texto con: result["choices"][0]["message"]["content"].

El campo usage muestra el conteo de tokens. Monitorea esto para controlar tu consumo, ya que GLM-5.1 cobra 3x cuota durante horas pico (14:00-18:00 UTC+8).

Respuestas en streaming

Para peticiones largas (por ejemplo, generación de código), habilita streaming para recibir tokens conforme se generan.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

stream = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Explica cómo funciona un índice B-tree en una base de datos, con un ejemplo de código."
        }
    ],
    stream=True,
    max_tokens=2048
)

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

print()  # Nueva línea al finalizar

Cada chunk contiene solo los nuevos tokens. El último chunk tiene finish_reason: "stop" (o "length" si se alcanza el límite).

Streaming con requests raw

import os
import json
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [{"role": "user", "content": "Escribe una ordenación por mezcla en Python."}],
        "stream": True,
        "max_tokens": 1024
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode("utf-8")
        if line.startswith("data: "):
            data = line[6:]
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0]["delta"]
            if "content" in delta:
                print(delta["content"], end="", flush=True)

Llamada a herramientas

GLM-5.1 soporta llamada a herramientas: permite que el modelo solicite ejecución de funciones durante la conversación. Es clave para flujos agénticos (ejecutar código, buscar en bases de datos, llamar APIs externas, etc).

Definiendo herramientas

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "run_python",
            "description": "Ejecuta código Python y devuelve la salida. Usa esto para probar, perfilar o comparar código.",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "description": "El código Python a ejecutar"
                    }
                },
                "required": ["code"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Lee el contenido de un archivo",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Ruta del archivo a leer"
                    }
                },
                "required": ["path"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Escribe una función para calcular números de Fibonacci, pruébala para n=10 y muéstrame la salida."
        }
    ],
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message
print(f"Razón de finalización: {response.choices[0].finish_reason}")

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"\nHerramienta llamada: {tool_call.function.name}")
        print(f"Argumentos: {tool_call.function.arguments}")

Manejo de las respuestas de llamadas a herramientas

Cuando GLM-5.1 solicita una herramienta, ejecuta la función y retorna el resultado en el siguiente mensaje:

import subprocess

def execute_tool(tool_call):
    """Ejecuta la herramienta y devuelve el resultado."""
    name = tool_call.function.name
    args = json.loads(tool_call.function.arguments)

    if name == "run_python":
        result = subprocess.run(
            ["python3", "-c", args["code"]],
            capture_output=True,
            text=True,
            timeout=10
        )
        return result.stdout or result.stderr

    elif name == "read_file":
        try:
            with open(args["path"]) as f:
                return f.read()
        except FileNotFoundError:
            return f"Error: archivo {args['path']} no encontrado"

    return f"Herramienta desconocida: {name}"


def run_agent_loop(user_message, tools, max_iterations=20):
    """Ejecuta un bucle completo de agente con llamadas a herramientas."""
    messages = [{"role": "user", "content": user_message}]

    for i in range(max_iterations):
        response = client.chat.completions.create(
            model="glm-5.1",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            max_tokens=4096
        )

        message = response.choices[0].message
        messages.append(message.model_dump())

        if response.choices[0].finish_reason == "stop":
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            for tool_call in message.tool_calls:
                tool_result = execute_tool(tool_call)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": tool_result
                })

    return "Se alcanzó el número máximo de iteraciones"


result = run_agent_loop(
    "Escribe una implementación de Quicksort, pruébala con una lista aleatoria de 1000 enteros y reporta el tiempo.",
    tools
)
print(result)

Este patrón explota la fortaleza agéntica de GLM-5.1: el modelo decide cuándo llamar herramientas y sigue hasta terminar o encontrar solución.

Parámetros clave

Parámetro	Tipo	Predeterminado	Descripción
model	cadena	requerido	Usa "glm-5.1"
messages	array	requerido	Historial de conversación
max_tokens	entero	1024	Tokens a generar (hasta 163.840)
temperature	flotante	0.95	Aleatoriedad (0.0-1.0)
top_p	flotante	0.7	Muestreo de núcleo (recom. 0.7 para codificación)
stream	booleano	falso	Habilitar streaming
tools	array	nulo	Definiciones de funciones para llamada a herramientas
tool_choice	cadena/objeto	"auto"	"auto", "none", o herramienta específica
stop	cadena/array	nulo	Secuencias de detención personalizadas

Configuración recomendada para tareas de codificación:

{
    "model": "glm-5.1",
    "temperature": 1.0,
    "top_p": 0.95,
    "max_tokens": 163840  # contexto completo para ejecuciones agénticas largas
}

Para generación determinista, baja la temperatura a 0.2-0.4.

Usando GLM-5.1 con asistentes de codificación

Puedes enrutar Claude Code, Cline, Kilo Code y otros asistentes IA vía la API de BigModel para usar GLM-5.1 como backend de codificación.

Configuración de Claude Code

En ~/.claude/settings.json:

{
  "model": "glm-5.1",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "apiKey": "tu_clave_api_de_bigmodel"
}

Configuración de Cline / Roo Code

En la configuración de VS Code o la extensión Cline:

{
  "cline.apiProvider": "openai",
  "cline.openAIBaseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "cline.openAIApiKey": "tu_clave_api_de_bigmodel",
  "cline.openAIModelId": "glm-5.1"
}

Consumo de cuota

GLM-5.1 usa sistema de cuotas Z.AI:

• Horas pico (14:00-18:00 UTC+8): 3x cuota
• Fuera de pico: 2x cuota
• Promoción hasta abril 2026: 1x fuera de pico

Para cargas pesadas, programa tareas largas fuera de horas pico.

Probando la API de GLM-5.1 con Apidog

Testear integraciones agénticas requiere simular múltiples tipos de respuesta: normal, streaming, llamadas a herramientas, errores, etc. Hacerlo contra la API real gasta cuota y depende de conexión activa.

Smart Mock de Apidog permite definir estos estados y probar sin tocar la API real.

Configurando el endpoint mock

1. En Apidog, crea un endpoint: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
2. Añade una expectativa de mock para respuesta estándar:

{
  "id": "chatcmpl-test123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve(n): ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 120,
    "total_tokens": 152
  }
}

1. Añade expectativa para llamada a herramienta:

{
  "id": "chatcmpl-tool456",
  "object": "chat.completion",
  "created": 1744000001,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc",
            "type": "function",
            "function": {
              "name": "run_python",
              "arguments": "{\"code\": \"print(2+2)\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 35,
    "total_tokens": 83
  }
}

1. Añade respuesta de límite de tasa (HTTP 429):

{
  "error": {
    "message": "Límite de tasa excedido. Inténtalo de nuevo después de 60 segundos.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Probando el bucle completo del agente

Usa los Escenarios de Prueba de Apidog para encadenar solicitudes:

1. Paso 1: POST a /chat/completions con el mensaje inicial, verifica 200 y finish_reason == "tool_calls"
2. Paso 2: POST con el resultado de la herramienta, verifica 200 y finish_reason == "stop"
3. Paso 3: Extrae el contenido final y verifica que incluye el código esperado

Así pruebas todo el ciclo agéntico sin consumir cuota. Para manejo de errores, simula mocks que devuelvan 429 y verifica el reintento.

Con Escenarios de Prueba puedes pasar variables entre pasos (por ejemplo, IDs de llamada a herramienta) y simular el flujo real de un agente.

Manejo de errores

La API usa códigos HTTP estándar:

Estado	Significado	Acción
200	Éxito	Procesa la respuesta
400	Solicitud incorrecta	Revisa el formato de tu solicitud
401	No autorizado	Verifica tu clave API
429	Límite de tasa	Reintenta tras el valor del header Retry-After
500	Error servidor	Reintenta con retroceso exponencial
503	Servicio no disp.	Reintenta con retroceso exponencial

Ejemplo de reintentos:

import time
import requests

def call_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://open.bigmodel.cn/api/paas/v4/chat/completions",
                headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}",
                         "Content-Type": "application/json"},
                json=payload,
                timeout=120
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Límite de tasa. Esperando {retry_after}s...")
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            wait = 2 ** attempt
            print(f"Tiempo de espera en el intento {attempt + 1}. Reintentando en {wait}s...")
            time.sleep(wait)

    raise Exception("Número máximo de reintentos excedido")

Para ejecuciones largas, usa un timeout alto (120-300s). El modelo puede requerir ese tiempo para generar un archivo de código o analizar benchmarks.

Conclusión

La API compatible con OpenAI de GLM-5.1 permite integraciones rápidas si ya usas GPT o Claude. La diferencia es el endpoint (open.bigmodel.cn) y el sistema de cuotas en vez de tokens.

Para aplicaciones agénticas con muchas llamadas a herramientas, la optimización a largo plazo de GLM-5.1 es clave. Combínalo con pruebas robustas usando Smart Mock y Escenarios de Prueba de Apidog para asegurar que tu integración cubre todos los casos antes de producción.

Consulta más detalles sobre GLM-5.1 y benchmarks en la descripción general del modelo GLM-5.1. Aprende sobre flujos de trabajo de agentes IA y pruebas en cómo funciona la memoria del agente de IA.

Preguntas frecuentes

¿La API de GLM-5.1 es compatible con OpenAI?

Sí. El formato de solicitud, respuesta, streaming y llamadas a herramientas es igual que OpenAI. Usa el SDK oficial de OpenAI apuntando a https://open.bigmodel.cn/api/paas/v4/.

¿Cuál es el nombre del modelo?

Usa "glm-5.1".

¿Cómo funciona el precio?

GLM-5.1 usa cuotas: 3x durante horas pico (14:00-18:00 UTC+8), 2x fuera de pico, 1x promocional fuera de pico hasta abril 2026.

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

200.000 tokens de entrada; salida máxima: 163.840 tokens. Para tareas largas, usa max_tokens grande (32.768+).

¿Soporta llamadas a funciones/herramientas?

Sí. Especifica herramientas con esquema type: "function" en el array tools y maneja respuestas con finish_reason: "tool_calls".

¿Cómo pruebo la API sin gastar cuota?

Usa Smart Mock de Apidog para simular respuestas de éxito, herramienta, límite de tasa y errores. Ejecuta tu suite de pruebas contra el mock y solo valida con la API real al final.

¿Dónde están los pesos del modelo GLM-5.1?

En HuggingFace bajo zai-org/GLM-5.1, licencia MIT, compatibles con vLLM y SGLang para inferencia local.