La clave de API de GLM es la credencial que permite invocar los modelos GLM de Zhipu. A simple vista es solo una cadena de caracteres, pero en la práctica determina tres cosas: si la petición supera la autenticación, a qué cuenta se cargan los costos y qué tan grave resulta una filtración. Muchas fallas de integración no provienen del modelo ni de la red, sino de una clave del tipo equivocado, guardada de forma incorrecta o que nunca se rotó.
Este artículo sigue el orden «elegir tipo, crear, guardar, rotar y diagnosticar», explica las dos vías de obtención (la plataforma oficial y ZSQH AI Gateway) y cierra con una lista de configuración segura que se puede aplicar tal cual.
Nota: Zhipu, GLM y BigModel son marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica afiliación, representación ni patrocinio de Zhipu. El punto de creación de claves, los requisitos de autenticación y los criterios de facturación se rigen por la documentación oficial de la plataforma abierta de Zhipu.
1. Primero, define qué tipo de clave necesitas
La plataforma abierta de Zhipu gestiona por separado las claves de los planes personales, los planes de equipo y la API estándar de modelos; no son intercambiables. Antes de crear una clave, confirma para qué la vas a usar; de lo contrario es fácil terminar con una clave «válida» que no puede llamar al endpoint que necesitas.
- Clave de API estándar: para servicios backend, scripts, agentes y tareas por lotes. Se factura según el consumo real y cubre la gran mayoría de las integraciones técnicas.
- Clave de Coding Plan: para herramientas de programación como Claude Code. Funciona con los beneficios del plan y no sirve para llamar a interfaces de negocio generales.
- Claves de equipo o empresa: para colaboración entre varias personas y administración centralizada. Los permisos y la titularidad de la facturación difieren de los de una clave personal.
Si usas una clave de Coding Plan para solicitar la API estándar, lo habitual es recibir un fallo de autenticación o un aviso de que el plan no incluye ese modelo. Ante ese error, revisa primero el tipo de producto de la clave y después si la copiaste completa.
2. Crear la clave en la plataforma abierta de Zhipu
La vía oficial conviene a los equipos que solo usan GLM y quieren acceder a los modelos y funciones nuevas cuanto antes. Los pasos básicos son:
- Abre la plataforma abierta de Zhipu, regístrate e inicia sesión.
- Entra en la página API Keys de la consola y confirma el proyecto o espacio activo.
- Pulsa para crear una clave y nómbrala por entorno y servicio, por ejemplo
prod-atencion-cliente. - Copia la clave completa y guárdala de inmediato en un gestor de contraseñas o en el sistema de secretos del servidor.
- Revisa el saldo o el estado del paquete de recursos en la página de facturación, para no crear una clave que después no pueda llamar.
- Valida la clave con una petición mínima antes de escribirla en la configuración definitiva.
Hay dos advertencias: la clave suele mostrarse completa solo al crearla, y al cerrar la página puede que ya no sea visible; además, los requisitos de verificación de identidad personal o de empresa cambian según el producto y las políticas, así que guíate por los avisos de la plataforma y por la documentación oficial.
3. Crear la clave a través de un gateway
Si el equipo usa varios modelos a la vez, o si quieres unificar cuotas, facturación y comprobantes de pago, puedes registrarte en ZSQH AI Gateway. Dentro de la página de claves de API, crea una clave, define un límite de consumo y una fecha de vencimiento, y luego revisa en precios de modelos qué modelos de la familia GLM están disponibles y cómo se facturan.
Una clave de gateway solo es válida con la base URL de ZSQH AI Gateway; no sirve para llamar a la dirección oficial de Zhipu. A la inversa, una clave oficial tampoco funciona directamente en el gateway. Nombrar y almacenar por separado ambos conjuntos de claves es la forma más sencilla de evitar confusiones.
4. Guardar la clave en variables de entorno
La práctica más peligrosa es escribir la clave en el código fuente, en el bundle del frontend o en un historial de chat. Conviene usar variables de entorno o un servicio de gestión de secretos, de modo que el código solo haga referencia al nombre de la variable.
# .env solo en local, y añadido a .gitignore
GLM_API_KEY=your_key_here
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url=os.getenv("GLM_BASE_URL"),
)
Como mínimo, al implementar: no subir .env a Git; usar en producción el Secret Manager, KMS o los secretos del orquestador de contenedores del proveedor de nube; emplear variables cifradas independientes en CI/CD; enmascarar la cabecera Authorization en los registros; y no incluir nunca una clave de servidor en el código del frontend.
5. Aislamiento de permisos, rotación y auditoría
Usar una sola clave para todo ahorra trabajo a corto plazo, pero complica el diagnóstico a largo plazo. La recomendación es separar de la siguiente manera.
| Práctica | Problema que resuelve | Recomendación de implementación |
|---|---|---|
| Separar pruebas y producción | El tráfico de pruebas contamina la facturación y puede borrar datos | Dos claves y dos cuotas |
| Una clave por servicio | No se puede localizar el origen de las llamadas | Nombrar por servicio o repositorio |
| Fijar un límite de consumo | Un uso anómalo consume presupuesto muy rápido | Configurar límites y alertas en la consola |
| Rotar periódicamente | Riesgo de filtración prolongada | Rotar cada trimestre; revocar de inmediato al cambiar de responsable |
| Conservar registros de llamadas | Resolución de disputas y análisis de fallas | Registrar fecha, modelo y consumo, nunca la clave en texto plano |
Al rotar, no borres la clave antigua de inmediato. Crea primero la nueva, migra el tráfico de forma gradual, confirma que la cuota, los permisos de modelo y la facturación funcionan, y solo entonces revoca la anterior. Así, si la nueva configuración falla, puedes volver atrás con rapidez.
6. Error 401 y otros mensajes frecuentes
Un HTTP 401 solo indica que la autenticación no pasó; el motivo concreto está en el código de negocio del cuerpo de la respuesta. En los códigos oficiales de Zhipu, 1000 significa fallo de verificación de identidad, 1001 indica que falta información de autenticación en la cabecera, 1003 corresponde a un token inválido y 1005 a una cuenta con verificación en dos pasos activada. El diagnóstico sigue este orden:
- Confirma que la cabecera sea
Authorization: Bearer <key>, sin espacios ni comillas adicionales. - Confirma que copiaste la clave completa y que no tomaste el nombre ni la máscara como clave.
- Confirma que el tipo de clave coincide con la interfaz; no mezcles claves de API estándar con claves de plan.
- Confirma que la base URL corresponde al origen de la clave: clave oficial con dirección oficial, clave de gateway con dirección del gateway.
- Confirma el estado de la cuenta: la falta de saldo devuelve 1113 y la limitación de velocidad devuelve 1302 o 1305.
Además, 1211 indica que el modelo no existe, normalmente por un nombre mal escrito o porque el modelo no está habilitado; 1261 indica que la entrada es demasiado larga y conviene comprimir el contexto o dividirla. Registrar los códigos de negocio en los logs acelera mucho el diagnóstico.
7. Lista de verificación antes de salir a producción
- La clave existe solo en el servidor o en el servicio de gestión de secretos.
- Pruebas, producción y CI usan claves distintas.
- Cada clave tiene un límite de consumo y un responsable identificado.
- Hay alertas configuradas para saldo bajo y aumento repentino del consumo.
- Se ensayó al menos una vez la revocación y el reemplazo de una clave.
- Los logs no contienen claves completas, números de teléfono ni otros datos sensibles.
- Al salir o transferir responsabilidades de un miembro del equipo, sus claves fueron revocadas.
8. Preguntas frecuentes (FAQ)
1. ¿Dónde se crea la clave de API de GLM?
En la plataforma abierta de Zhipu, en la página API Keys de la consola. Si usas ZSQH AI Gateway, se crea en la página de claves de API de la consola del gateway. Ambas claves no son intercambiables.
2. ¿Puedo poner la clave en el frontend o en una miniaplicación?
No. El código del frontend puede ser inspeccionado por cualquier usuario, así que toda clave incluida allí debe considerarse filtrada. Lo correcto es que el frontend llame a tu propio backend, y que el backend guarde la clave y reenvíe las llamadas al modelo.
3. ¿Una sola clave puede compartirse entre varios proyectos?
Técnicamente sí, pero no es recomendable. Una clave compartida impide distinguir el origen de las llamadas, una filtración afecta a todo el negocio y la facturación resulta difícil de repartir. Como mínimo, separa por servicio y por entorno.
4. ¿Qué hago si la clave se filtró?
Revoca o elimina la clave de inmediato en la consola, crea una nueva y actualiza la configuración del servidor; revisa también la facturación y los registros de llamadas para detectar consumo anómalo; si hace falta, contacta al soporte de la plataforma y explica la situación.
5. ¿Se pueden mezclar claves oficiales y claves de gateway?
No. Los sistemas de autenticación, las base URL y las cuentas de facturación son distintos. La manifestación más común de una mezcla es un error 401, seguida de peticiones enviadas a una dirección de servicio equivocada.
