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

TL;DR

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

Introducción

GLM-5.1 es el modelo agéntico insignia de Z.AI, lanzado en abril de 2026. Ocupa el puesto número 1 en SWE-Bench Pro y supera a GLM-5 en todos los principales benchmarks de codificación. Si estás construyendo un asistente de codificación de IA, un agente autónomo o cualquier aplicación que se beneficie de la ejecución de tareas a largo plazo, vale la pena integrar GLM-5.1.

La buena noticia para los desarrolladores: la API es compatible con OpenAI. Si ya has construido sobre GPT-4 o Claude, puedes cambiar a GLM-5.1 cambiando la URL base y el nombre del modelo. No hay un nuevo SDK que aprender. No hay un formato de respuesta diferente que manejar.

Requisitos previos

Antes de realizar tu primera llamada, necesitas:

1. Una cuenta de BigModel en bigmodel.cn. El registro es gratuito.
2. Una clave API desde la consola de BigModel en "API Keys".
3. Python 3.8+ o Node.js 18+ (los ejemplos cubren ambos).
4. El SDK de OpenAI o las librerías estándar requests/fetch (la API de GLM-5.1 es compatible con OpenAI).

Configura tu clave API como una variable de entorno:

export BIGMODEL_API_KEY="tu_clave_api_aquí"

Nunca codifiques las claves API en tu código fuente.

Autenticación

Cada solicitud necesita un token Bearer en el encabezado de autorización:

Authorization: Bearer TU_CLAVE_API

El formato de la clave API de BigModel se parece a xxxxxxxx.xxxxxxxxxxxxxxxx, una cadena de dos partes separadas por un punto. Esto es diferente del formato `sk-` de OpenAI pero funciona de la misma manera en el encabezado.

URL base

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

El endpoint de finalización de chat es:

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)

Dado que la API es compatible con OpenAI, puedes usar el SDK oficial de OpenAI para Python con una 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 es el enfoque más limpio. El SDK de OpenAI maneja los reintentos, la gestión de tiempos de espera y el análisis de respuestas. Obtienes todo eso de forma gratuita simplemente apuntándolo a la URL base de BigModel.

Formato de respuesta

La estructura de la respuesta es idéntica a la de 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 de la respuesta a través de result["choices"][0]["message"]["content"].

El campo usage muestra el recuento de tokens de la solicitud. Realiza un seguimiento de esto para monitorear tu consumo de cuota, ya que GLM-5.1 cobra 3 veces la cuota durante las horas pico (14:00-18:00 UTC+8).

Respuestas en streaming

Para tareas de generación de código largas, el streaming te entrega tokens a medida que llegan en lugar de esperar la respuesta completa. Esto es esencial para cualquier aplicación orientada al usuario.

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 después de que se complete el streaming

Cada fragmento en el stream es un delta que contiene solo los nuevos tokens desde el último fragmento. El fragmento final tiene finish_reason establecido en "stop" (o "length" si se alcanza el límite de tokens).

Streaming con solicitudes raw

Si prefieres no usar el SDK de OpenAI:

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 admite la llamada a herramientas: la capacidad de solicitar la ejecución de funciones a mitad de la conversación. Este es el mecanismo central para los flujos de trabajo agénticos donde el modelo necesita ejecutar código, buscar en bases de datos, llamar a APIs externas o realizar acciones en el mundo real.

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 llamada a herramientas, tú ejecutas la función y luego devuelves 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":
            # El modelo ha terminado
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            # Ejecuta cada llamada a herramienta y añade los resultados
            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 se adapta directamente a la fortaleza de GLM-5.1 como modelo agéntico. Permites que el modelo decida cuándo llamar a las herramientas, procesar los resultados y continuar hasta que encuentre una solución o decida que ha terminado.

Parámetros clave

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
}

Z.AI utiliza esta configuración en sus propias evaluaciones de benchmark. Para la generación de código determinista, reduce la temperatura a 0.2-0.4.

Usando GLM-5.1 con asistentes de codificación

El Plan de Codificación de Z.AI te permite enrutar Claude Code, Cline, Kilo Code y otros asistentes de codificación de IA a través de GLM-5.1 mediante la API de BigModel. Esto es útil si quieres un modelo de codificación potente a un coste menor que ejecutar directamente Claude Opus o GPT-5.4.

Configuración de Claude Code

En tu archivo de configuración de Claude Code (~/.claude/settings.json o equivalente):

{
  "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 tu VS Code o en la configuración de 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 utiliza el sistema de cuotas de Z.AI en lugar de la facturación por token: - Horas pico (14:00-18:00 UTC+8): 3x cuota por solicitud - Fuera de horas pico: 2x cuota por solicitud - Tarifa promocional hasta abril de 2026: 1x durante fuera de horas pico

Para cargas de trabajo agénticas pesadas, programa tareas de larga duración para horas fuera de pico. Una ejecución de optimización de 600 iteraciones como la demostrada por Z.AI cuesta significativamente más cuota en horas pico.

Probando la API de GLM-5.1 con Apidog

Probar una integración de API agéntica requiere manejar correctamente múltiples tipos de respuesta: finalizaciones normales, fragmentos de streaming, solicitudes de llamadas a herramientas, mensajes de resultados de herramientas y estados de error. Probar todo esto contra la API real consume cuota y requiere una conexión en vivo.

Smart Mock de Apidog te permite definir todos estos estados de respuesta y probarlos sin afectar la API real.

Configurando el endpoint mock

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

{
  "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 una segunda expectativa para una respuesta de 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 una 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 múltiples solicitudes. Para una prueba de bucle de agente:

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

Esto prueba el bucle completo del agente sin gastar ninguna cuota. También puedes probar el manejo de errores cambiando el mock para que devuelva 429, y luego verificando que tu lógica de reintento se active correctamente.

Para flujos de trabajo agénticos de varios pasos, los Escenarios de Prueba de Apidog te permiten pasar datos entre pasos usando variables, de modo que los valores de request_id o tool_call_id del paso 1 fluyen automáticamente al paso 2. Esto simula cómo funciona un bucle de agente real y detecta errores de integración antes de la producción.

Manejo de errores

La API devuelve códigos de estado HTTP estándar:

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 agénticas largas donde los pasos individuales pueden tomar de 30 a 60 segundos, siempre establece un tiempo de espera generoso (120-300 segundos). El modelo puede necesitar tiempo para generar un archivo de código completo o analizar un resultado de benchmark complejo.

Conclusión

La API compatible con OpenAI de GLM-5.1 significa que puedes integrarla en minutos si ya has trabajado con GPT o Claude. La diferencia clave es el endpoint (open.bigmodel.cn) y el sistema de cuotas en lugar de la facturación por token.

Para aplicaciones agénticas donde el modelo realiza cientos de llamadas a herramientas durante una sesión larga, la capacidad de optimización a largo plazo de GLM-5.1 es una ventaja real. Combínala con pruebas adecuadas a través de Smart Mock y los Escenarios de Prueba de Apidog para asegurarte de que tu integración maneja todos los casos extremos antes de que se ejecute sin supervisión.

Para obtener información sobre qué es GLM-5.1 y cómo se comparan sus benchmarks, consulta la descripción general del modelo GLM-5.1. Para obtener más información sobre cómo construir y probar flujos de trabajo de agentes de IA con Apidog, consulta 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 la solicitud, la estructura de la respuesta, el protocolo de streaming y el formato de llamada a herramientas son idénticos a los de la API de finalización de chat de OpenAI. Puedes usar el SDK oficial de OpenAI para Python o cualquier cliente compatible con OpenAI configurando la URL base en https://open.bigmodel.cn/api/paas/v4/.

¿Cuál es el nombre del modelo a usar en las solicitudes de la API?Usa "glm-5.1" como nombre del modelo. No uses un nombre completo con versión; solo glm-5.1 funciona.

¿Cómo funciona el precio de la API de GLM-5.1?La API de BigModel utiliza un sistema de cuotas. GLM-5.1 consume 3x la cuota durante las horas pico (14:00-18:00 UTC+8) y 2x durante las horas no pico. Hasta finales de abril de 2026, el uso fuera de pico se factura a 1x la cuota como tarifa promocional.

¿Cuál es la longitud máxima del contexto?200.000 tokens de contexto de entrada. La salida máxima es de 163.840 tokens. Para ejecuciones agénticas largas, establece max_tokens en un valor grande (32.768 o superior) para evitar truncar la salida del modelo a mitad de tarea.

¿Puedo usar GLM-5.1 para llamadas a funciones / uso de herramientas?Sí. GLM-5.1 admite el mismo formato de llamada a herramientas que la API de OpenAI. Define las herramientas con un esquema type: "function", pásalas en el array tools y maneja las respuestas finish_reason: "tool_calls" en tu bucle de agente.

¿Cómo pruebo las llamadas a la API de GLM-5.1 sin gastar cuota?Usa Smart Mock de Apidog para definir respuestas simuladas para cada estado de la API: éxito, llamadas a herramientas, límites de tasa, errores. Ejecuta tu suite de pruebas contra el mock durante el desarrollo y solo usa la API real para la validación final.

¿Dónde puedo encontrar los pesos del modelo GLM-5.1?Los pesos de código abierto están en HuggingFace en zai-org/GLM-5.1. Se lanzan bajo la Licencia MIT y son compatibles con vLLM y SGLang para inferencia local.