GLM-5 es la nueva generación de modelos generales de la familia GLM de Zhipu. Muchos equipos se hacen tres preguntas: dónde se obtiene la clave, qué base URL hay que configurar y si el SDK de OpenAI existente se puede reutilizar. La respuesta: la familia GLM ofrece desde hace tiempo una interfaz compatible con OpenAI, así que en la mayoría de los casos solo hay que cambiar tres cosas: la base URL, la clave y el nombre del modelo.

Este artículo sigue el orden de integración: primero explica qué es la API de GLM-5, después recorre el proceso de obtener la clave y ejecutar la primera petición, y al final incluye una lista de comprobación para diagnosticar errores y controlar costes.

Nota: Zhipu y GLM son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica de la integración. Los nombres de modelo, la longitud de contexto y los criterios de facturación deben verificarse en la documentación oficial y en la página de precios de modelos del sitio. Los nombres de modelo de los ejemplos deben comprobarse en la consola antes de usarlos.

1. Qué es la API de GLM-5

La API de GLM-5 es la interfaz de invocación de modelos que la plataforma abierta de Zhipu ofrece a los desarrolladores. Sus capacidades habituales incluyen:

  • Conversación multiturno y seguimiento de instrucciones;
  • Resumen, reescritura y traducción de textos largos;
  • Extracción estructurada y salida en JSON;
  • Generación y explicación de código;
  • Nodos de razonamiento en agentes y flujos de trabajo.

No es lo mismo que el producto web: la versión web se cobra por suscripción de cuenta, mientras que la API se factura por tokens o por volumen de llamadas. La clave solo representa una credencial de invocación y no equivale a los beneficios de una membresía. Antes de integrar, conviene definir el uso, la concurrencia y el presupuesto, y después decidir si se usa el acceso oficial o una pasarela agregadora.

2. Dos caminos para obtener la clave de API de GLM

Camino uno: plataforma abierta de Zhipu

  1. Regístrate e inicia sesión en la plataforma abierta de Zhipu y completa la verificación de identidad o de empresa según lo que exija la plataforma.
  2. Crea una clave de API en la consola y ponle un nombre por proyecto o entorno.
  3. Revisa el saldo de la cuenta y los modelos disponibles; recarga si es necesario.
  4. Guarda la clave en una variable de entorno del servidor, nunca en el frontend.

La base URL oficial suele ser https://open.bigmodel.cn/api/paas/v4; confirma siempre la versión vigente en la documentación oficial.

Camino dos: pasarela de IA de ZSQH

Si ya utilizas varios modelos o quieres unificar la facturación y la gestión de claves, puedes registrarte en la pasarela de IA de ZSQH, crear una clave y comprobar en la página de precios de modelos si la familia GLM está disponible y cómo se escribe el nombre del modelo.

Ninguno de los dos caminos es mejor en términos absolutos: si usas un solo modelo y el acceso oficial funciona bien, la conexión directa es más sencilla; si necesitas alternar entre modelos, unificar cuotas y disponer de una entrada estable, la pasarela ahorra trabajo.

3. Configuración compatible con OpenAI

La interfaz de GLM se parece a OpenAI Chat Completions; al migrar solo hay que cambiar tres elementos:

Elemento Acceso oficial Pasarela ZSQH
Base URL https://open.bigmodel.cn/api/paas/v4 https://ai.zhongshangqihang.com/v1
Clave de API Creada en la plataforma Zhipu Creada en la consola de la pasarela
Nombre del modelo Según la documentación oficial Según la página de precios del sitio
SDK SDK de OpenAI compatible SDK de OpenAI compatible

Presta atención al final de la base URL: algunos SDK añaden /chat/completions automáticamente y otros esperan la ruta completa. Mezclar la dirección oficial con la de la pasarela suele producir errores 401 o 404.

4. Llamada con curl

export ZSQH_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "system", "content": "Eres un editor técnico; responde de forma concreta."},
      {"role": "user", "content": "Explica en tres puntos qué equipos se benefician de una pasarela de API"}
    ],
    "temperature": 0.6,
    "max_tokens": 800
  }'

Sustituye model por el identificador real de GLM-5 disponible en la página de precios. Si recibes model not found, revisa primero mayúsculas, minúsculas y el sufijo de versión.

5. Llamada con Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="glm-5",  # según la página de precios del sitio
    messages=[
        {"role": "system", "content": "Eres un asistente de control de calidad; responde solo con JSON."},
        {"role": "user", "content": "Clasifica el sentimiento de esta frase: la logística es lenta, pero la atención al cliente es buena."},
    ],
    temperature=0.2,
    response_format={"type": "json_object"},
)

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

Si tu versión del SDK es antigua, es posible que no admita response_format; actualiza primero el paquete openai. Si la pasarela no admite el modo JSON, restringe el formato de salida en el prompt y añade en el código un análisis de respaldo.

6. Cómo elegir el nombre del modelo

La familia GLM suele incluir variantes generales, ligeras y de razonamiento, con nombres que llevan número de versión y sufijo de fecha. Recomendaciones de selección:

Caso de uso Criterio Advertencia
Atención al cliente, resúmenes, reescritura Modelo conversacional general Empieza con temperature baja
Razonamiento complejo, matemáticas Modelo reforzado para razonamiento Más lento y con mayor consumo de tokens
Clasificación de alta concurrencia Modelo ligero Mide la precisión antes de escalar
Tareas de código Versión con buena capacidad de programación Cuidado con los truncamientos en contextos largos

Qué nombre de modelo está disponible, cuánto contexto admite y cuál es su precio unitario son datos que debes consultar siempre en la página de precios del sitio. No copies nombres antiguos de tutoriales: GLM itera sus versiones con rapidez.

7. Errores habituales

Error Causa frecuente Solución
401 Unauthorized Clave incorrecta, falta Bearer o clave eliminada Copia de nuevo la clave y revisa las cabeceras
404 Not Found Sobra o falta /v1 en la base URL Usa la dirección unificada de la documentación
model not found El modelo no existe o no tienes permiso Copia el nombre desde la página de precios
429 Too Many Requests Se superó el límite de concurrencia o frecuencia Reduce la concurrencia y reintenta con retroceso exponencial
insufficient balance Saldo insuficiente Recarga o cambia de clave
Respuesta interrumpida Timeout, red o salida demasiado larga Aumenta el timeout y usa streaming

El orden de diagnóstico debe empezar por la autenticación: valida la clave con la petición mínima, comprueba después el nombre del modelo y solo entonces sospecha de la red. Así evitas modificar el código repetidamente en la dirección equivocada.

8. Control de costes

  1. Configura max_tokens para evitar salidas ilimitadas.
  2. Simplifica el system prompt; si repites instrucciones largas, considera caché o plantillas.
  3. Usa modelos ligeros para tareas por lotes y sube de gama solo en los casos difíciles.
  4. Registra el consumo de tokens de cada petición y separa la factura por línea de negocio.
  5. Fija un límite de cuota por clave para detener automáticamente llamadas anómalas.
  6. Haz una prueba de carga en hora punta antes de salir a producción para confirmar los umbrales de limitación.

El coste no depende solo del precio unitario: los reintentos, el contexto largo y las salidas inútiles amplifican la factura. Primero mejora la tasa de éxito y reduce el promedio de tokens; después negocia el precio.

9. Seguridad y trabajo en equipo

  • Separa las claves por entorno: una para pruebas, una para preproducción y una para producción, sin reutilizarlas.
  • Separa las claves por proyecto para poder medir tokens y costes de cada negocio.
  • Guarda las claves en variables de entorno del servidor o en un gestor de secretos; nunca en Git ni en el paquete del frontend.
  • No imprimas claves completas ni el texto original del usuario en los logs; anonimiza cuando sea necesario.
  • Configura alertas de cuota y avisa al responsable cuando el saldo baje de un umbral.
  • Si alguien deja el equipo o se filtra una clave, desactívala y rótala de inmediato.

El riesgo más habitual en los equipos no es el modelo, sino que la clave acabe copiada en una herramienta de chat, un documento o el código del frontend. Añadir al proceso de integración el paso "la clave solo existe en el servidor" ahorra mucho más trabajo que investigar después.

Preguntas frecuentes

¿Puedo usar el SDK de OpenAI con la API de GLM-5?

En la mayoría de los casos sí: cambia base_url, api_key y model. Algunos parámetros, como ciertos interruptores de razonamiento o campos multimodales, pueden no ser compatibles; consulta la documentación oficial o la del sitio.

¿La clave de API de GLM sirve también para la membresía web?

No. La membresía web es una suscripción al producto y la clave de API es una credencial para desarrolladores; la facturación y los permisos se gestionan por separado.

¿Una sola clave puede llamar a otros modelos?

En la pasarela de ZSQH, una clave puede invocar varios modelos habilitados, indicando cuál en cada petición; el alcance exacto aparece en la página de precios y en la consola.

¿Hace falta configuración adicional para llamar desde China?

Depende del entorno de red y de los términos del servicio. En producción conviene configurar timeouts, reintentos y una ruta alternativa; no concentres todas las peticiones en una sola entrada.

Siguiente paso

Primero regístrate en la pasarela de IA de ZSQH, crea una clave de prueba, ejecuta la petición mínima con curl y después intégrala en el código de tu negocio. Los nombres de modelo y los precios figuran en precios de modelos.

Lecturas relacionadas: