Der GLM API Key ist der Zugang zu den GLM-Modellen von Zhipu. Er sieht nur wie eine Zeichenkette aus, entscheidet aber über drei Dinge: ob eine Anfrage die Authentifizierung passiert, welchem Konto die Kosten zugeordnet werden und wie groß der Schaden bei einer Offenlegung ist. Viele fehlgeschlagene Integrationen liegen nicht am Modell oder am Netz, sondern am falschen Key-Typ, an unsicherer Ablage oder daran, dass ein Key nie rotiert wurde.
Dieser Artikel folgt dem Ablauf „Typ wählen – erstellen – speichern – rotieren – Fehler beheben“ und beschreibt sowohl den offiziellen Weg über die Zhipu-Plattform als auch den Weg über das ZSQH AI Gateway. Am Ende steht eine Checkliste für die sichere Konfiguration.
Hinweis: Zhipu, GLM und BigModel sind Marken der jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeit oder Vertretungsbeziehung zu Zhipu. Maßgeblich für Key-Erstellung, Authentifizierungsanforderungen und Abrechnung sind die offiziellen Dokumente der Zhipu-Plattform.
1. Zuerst den passenden Key-Typ bestimmen
Die Zhipu-Plattform verwaltet Keys für persönliche Pakete, Team-Pakete und die Standard-Modell-API getrennt; sie sind nicht untereinander austauschbar. Vor dem Erstellen sollte der Verwendungszweck feststehen, sonst entsteht schnell der Fall „Key ist gültig, aber der Aufruf schlägt fehl“.
- Standard-Modell-API-Key: für Backend-Dienste, Skripte, Agenten und Batch-Jobs, abgerechnet nach tatsächlichem Volumen. Der Großteil technischer Integrationen fällt hierunter.
- Coding-Plan-Key: für Coding-Werkzeuge wie Claude Code, gebunden an Paketleistungen; nicht für allgemeine Geschäftsschnittstellen gedacht.
- Team- oder Unternehmens-Keys: für Zusammenarbeit und zentrale Verwaltung, mit anderen Rechten und anderer Rechnungszuordnung als persönliche Keys.
Wird ein Coding-Plan-Key gegen die Standard-API verwendet, sind Authentifizierungsfehler oder die Meldung „Paket umfasst dieses Modell nicht“ typisch. Bei solchen Fehlern zuerst den Produkttyp des Keys prüfen und danach, ob der Key vollständig kopiert wurde.
2. Key auf der Zhipu-Plattform erstellen
Der offizielle Weg eignet sich für Teams, die ausschließlich GLM nutzen und neue Modelle und Funktionen früh erhalten möchten. Die Schritte:
- Zhipu-Plattform öffnen, registrieren und anmelden.
- Im Konsolenbereich die Seite „API Keys“ öffnen und Projekt bzw. Arbeitsbereich prüfen.
- Auf „Neuen Schlüssel erstellen“ klicken und nach dem Muster „Umgebung – Dienst“ benennen, etwa
prod-customer-service. - Den vollständigen Key kopieren und sofort in einen Passwortmanager oder ein serverseitiges Secret-Management legen.
- Auf der Abrechnungsseite Guthaben oder Ressourcenpaket prüfen, damit der Key nicht erfolgreich erstellt, aber nicht nutzbar ist.
- Mit einer minimalen Anfrage testen und den Key erst danach in die produktive Konfiguration übernehmen.
Zwei Punkte beachten: Der Key wird meist nur bei der Erstellung vollständig angezeigt und ist nach dem Schließen der Seite möglicherweise nicht mehr sichtbar. Anforderungen an Identitäts- und Unternehmensprüfung ändern sich mit Produkt und Richtlinie; maßgeblich sind die Seitenhinweise und die offizielle Dokumentation.
3. Key über das Gateway erstellen
Nutzt ein Team mehrere Modelle oder möchte es einheitliche Kontingente, Rechnungen und Belege, kann es sich im ZSQH AI Gateway registrieren. Nach dem Öffnen der API-Key-Seite einen Key anlegen, Obergrenze und Ablaufdatum setzen und anschließend in den Modellpreisen prüfen, welche GLM-Modelle verfügbar sind und wie abgerechnet wird.
Ein Gateway-Key gilt nur unter der Base URL von ZSQH und funktioniert nicht gegen die offizielle Zhipu-Adresse; umgekehrt lässt sich ein offizieller Key nicht direkt am Gateway verwenden. Getrennte Benennung und getrennte Ablage der beiden Key-Systeme sind die einfachste Absicherung.
4. Key in Umgebungsvariablen ablegen
Am gefährlichsten ist ein Key im Quellcode, im Frontend-Bundle oder in einem Chatverlauf. Besser sind Umgebungsvariablen oder ein Secret-Manager; der Code referenziert dann nur den Variablennamen.
# .env nur lokal halten und in .gitignore aufnehmen
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"),
)
Mindestens gilt: .env nicht in Git einchecken; in der Produktion Secret Manager, KMS oder Container-Secrets des Cloud-Anbieters verwenden; in CI/CD separate verschlüsselte Variablen nutzen; den Authorization-Header in Logs maskieren; serverseitige Keys niemals im Frontend erscheinen lassen.
5. Rechte trennen, rotieren, auditieren
Ein Key für alles ist kurzfristig bequem, langfristig schwer zu diagnostizieren. Sinnvoll ist diese Aufteilung:
| Praxis | Gelöstes Problem | Umsetzung |
|---|---|---|
| Test und Produktion trennen | Testverkehr verfälscht Rechnungen, versehentliches Löschen | Zwei Keys, zwei Kontingente |
| Ein Key je Dienst | Aufrufer nicht lokalisierbar | Nach Dienst- oder Repository-Namen benennen |
| Obergrenzen setzen | Ungewöhnliche Aufrufe kosten schnell Geld | Limits und Alarme in der Konsole |
| Regelmäßig rotieren | Langfristiges Offenlegungsrisiko | Quartalsweise rotieren, bei Übergabe sofort sperren |
| Aufruflogs aufbewahren | Streitfälle und Störungsanalyse | Zeit, Modell und Volumen speichern, keinen Klartext-Key |
Beim Rotieren den alten Key nicht sofort löschen. Zuerst einen neuen Key anlegen, den Verkehr schrittweise umstellen, Kontingent, Modellrechte und Abrechnung prüfen und erst dann den alten Key sperren. So bleibt bei Problemen ein schneller Rückweg.
6. 401 und andere häufige Fehler
HTTP 401 bedeutet nur „Authentifizierung fehlgeschlagen“; die Ursache steht im Geschäftscode der Antwort. Bei Zhipu steht 1000 für fehlgeschlagene Identitätsprüfung, 1001 für fehlende Authentifizierungsangaben im Header, 1003 für einen ungültigen Token und 1005 für ein Konto mit aktivierter Zwei-Faktor-Authentifizierung. Die Prüfung in dieser Reihenfolge:
- Header auf
Authorization: Bearer <key>prüfen, ohne überzählige Leerzeichen oder Anführungszeichen. - Sicherstellen, dass der vollständige Key kopiert wurde und nicht Name oder Maskierung.
- Key-Typ und Schnittstelle abgleichen; Standard-API und Paket-Key nicht mischen.
- Base URL und Key-Herkunft abgleichen: offizieller Key zur offiziellen Adresse, Gateway-Key zur Gateway-Adresse.
- Kontostatus prüfen: Offene Beträge ergeben 1113, Ratenbegrenzung 1302 oder 1305.
Außerdem steht 1211 für ein nicht vorhandenes Modell, meist durch einen Tippfehler oder eine nicht freigeschaltete Modellversion; 1261 bedeutet eine zu lange Eingabe, die eine Kürzung des Kontexts oder eine Aufteilung erfordert. Wenn der Geschäftscode im Log steht, geht die Fehlersuche deutlich schneller.
7. Checkliste vor dem Produktivstart
- Der Key existiert nur serverseitig oder in einem Secret-Manager.
- Test, Produktion und CI verwenden unterschiedliche Keys.
- Jeder Key hat eine Obergrenze und eine verantwortliche Person.
- Alarme für niedriges Guthaben und plötzliche Nutzungsspitzen sind eingerichtet.
- Sperrung und Austausch eines Keys wurden einmal geübt.
- Logs enthalten keine vollständigen Keys, Telefonnummern oder andere sensible Daten.
- Bei Austritt oder Übergabe von Mitarbeitern wurden die betroffenen Keys zurückgezogen.
8. Häufige Fragen (FAQ)
1. Wo wird der GLM API Key erstellt?
Nach der Anmeldung auf der Zhipu-Plattform im Konsolenbereich unter „API Keys“. Bei Nutzung des ZSQH AI Gateway im dortigen Kontrollzentrum auf der API-Key-Seite; die beiden Key-Systeme sind nicht austauschbar.
2. Darf der Key im Frontend oder in einer Mini-App liegen?
Nein. Frontend-Code ist für Nutzer einsehbar; jeder dort hinterlegte Key gilt als offengelegt. Richtig ist, dass das Frontend das eigene Backend aufruft und das Backend den Key hält und die Modellaufrufe weiterleitet.
3. Kann ein Key von mehreren Projekten gemeinsam genutzt werden?
Technisch ja, empfohlen nein. Ein gemeinsamer Key erlaubt keine Zuordnung der Aufrufer, eine Offenlegung betrifft alle Dienste und die Rechnungen lassen sich kaum aufteilen. Mindestens nach Dienst und Umgebung trennen.
4. Was tun bei einem offengelegten Key?
Den Key sofort in der Konsole sperren oder löschen, einen neuen Key anlegen und die Serverkonfiguration aktualisieren. Gleichzeitig Rechnung und Aufruflog auf ungewöhnliches Volumen prüfen und bei Bedarf den Plattform-Support informieren.
5. Lassen sich offizieller Key und Gateway-Key mischen?
Nein. Authentifizierung, Base URL und Abrechnungskonto unterscheiden sich. Häufigste Folge ist 401, daneben Anfragen an die falsche Dienstadresse.
