Embedding API Key erstellen: Registrierung, Rechte, Rotation (2026)

Ein Embedding-API-Key unterscheidet sich auf den meisten Plattformen nicht von einem Key für Chat-Modelle: Er ist ein Identitätsnachweis. Was Sie tatsächlich aufrufen dürfen, bestimmen Kontorechte und der Modellparameter in der Anfrage. Vektorisierungsaufgaben laufen jedoch oft im Hintergrund und verarbeiten große Dokumentmengen. Wird ein Key kompromittiert oder falsch konfiguriert, sind Schaden und Fehlersuche entsprechend aufwendig.

Dieser Artikel erklärt der Reihe nach: wo Sie sich registrieren, was beim Anlegen eines Keys auszufüllen ist, wie Rechte verteilt werden, wie der Key in Umgebungsvariablen gehört, wie Sie 401-Fehler eingrenzen, wie Sie zwischen offiziellem Key und Gateway-Key wählen und wie Rotation sowie Leak-Behandlung ablaufen.

Hinweis: OpenAI und weitere genannte Marken gehören ihren jeweiligen Rechteinhabern. Dieser Artikel dient der technischen Erläuterung und steht in keiner Verbindung zu den Anbietern. Schnittstellen, Rechte und Preise richten sich nach der offiziellen Dokumentation der Plattformen und den Seiten von ZSQH.

1. Zuerst klären: Braucht Embedding einen eigenen Key?

Die meisten OpenAI-kompatiblen Plattformen verwenden dieselbe Authentifizierung: Derselbe Key ruft sowohl /v1/chat/completions als auch /v1/embeddings auf. Entscheidend sind Kontoguthaben, Modellrechte und Plattformrichtlinien, nicht der Key-Typ.

Einige Plattformen rechnen Vektordienste separat ab oder schalten sie getrennt frei. Prüfen Sie vor dem Anlegen im Kundenportal drei Punkte:

Ob der aktuelle Tarif oder das Guthaben die Embedding-Modelle abdeckt.
Ob der Key einer Modell-Whitelist oder einem Projektbereich unterliegt.
Ob Embedding und Chat dasselbe Kontingent nutzen.

Bietet das Portal keine feingranularen Rechte, isolieren Sie nach dem Prinzip „ein Verwendungszweck, ein Key“. Damit sind zumindest Limits und eine getrennte Deaktivierung möglich.

2. Registrierung und Zugang zum Kundenportal

Am Beispiel des ZSQH AI Gateway:

Öffnen Sie https://ai.zhongshangqihang.com, registrieren Sie sich mit E-Mail und schließen Sie die Verifizierung ab.
Melden Sie sich an und öffnen Sie im Kundenportal die Seite „API-Keys“.
Prüfen Sie unter „Guthaben“ oder „Aufladen“ den Kontostand; für Tests genügt zunächst ein kleiner Betrag.
Öffnen Sie das Nutzungsprotokoll und vergewissern Sie sich, dass Modell, Token und Kosten sichtbar sind.

Die Registrierung ist auch direkt über den Registrierungslink möglich. Wenn Sie zunächst nur die Schnittstelle prüfen und noch nicht aufladen möchten, legen Sie einen Test-Key mit niedrigem Limit an und passen Sie ihn nach erfolgreichem Test an.

3. Was beim Anlegen eines Keys auszufüllen ist

Nach einem Klick auf „Neuen Key erstellen“ erscheinen üblicherweise folgende Felder:

Name: Verwendungszweck und Umgebung eindeutig benennen, etwa rag-prod-backend oder embedding-batch-dev. Namen wie „Test1“ vermeiden.
Ausgabenlimit: Zunächst niedrig ansetzen und erst nach Kenntnis des tatsächlichen Verbrauchs der Batch-Aufgaben erhöhen.
Ablaufdatum: Für temporäre Skripte 7 oder 30 Tage; auch Produktions-Keys brauchen einen festen Rotationszyklus.
Modell- oder Projektbereich: Falls unterstützt, nur Embedding-Modelle und die notwendigen Projekte auswählen.
Speichern und kopieren: Der vollständige Key wird meist nur einmal angezeigt. Ohne Speicherung bleibt nur Löschen und Neuanlegen.

Keys beginnen häufig mit sk-, aber das Präfix belegt nicht die Echtheit. Achten Sie beim Kopieren auf Leerzeichen oder Zeilenumbrüche am Anfang und Ende; sie gehören zu den häufigsten Ursachen für 401.

4. Rechte und Kontingente sinnvoll gestalten

Vektorisierungsaufgaben sind durch „viel Lesen, wenig Schreiben, Batch-Betrieb und häufige Wiederholungen“ gekennzeichnet. Ziel der Rechtevergabe ist nicht nur der Schutz vor Angriffen von außen, sondern die Begrenzung des Schadens, den ein einziger Key in allen Umgebungen anrichten kann.

Szenario	Key-Name	Kontingent	Ablage	Rotation
Lokale Entwicklung	`emb-dev-name`	Niedrigste Stufe	Lokale `.env`	30 Tage
Testumgebung	`emb-staging`	Niedrig	CI/CD-Secret	60 Tage
Produktion Batch	`emb-prod-batch`	Nach Budget	Key-Management-Dienst	90 Tage
Produktion Abfrage	`emb-prod-query`	Nach Budget	Key-Management-Dienst	90 Tage

Einige Grundsätze:

Entwicklung und Produktion trennen: Ein kompromittierter Test-Key beeinflusst nicht die Produktionsrechnung.
Batch und Abfrage trennen: Batch-Aufgaben werden häufig wiederholt; ein eigenes Limit erleichtert die Lokalisierung ungewöhnlichen Verbrauchs.
Minimale Rechte: Wenn nur Embedding nötig ist, Chat-Modelle nicht freischalten; wenn eine Projektbegrenzung möglich ist, keine Kontorechte vergeben.
Nicht ins Frontend: Keys in Browsern, Apps und Mini-Programmen werden zwangsläufig extrahiert. Vektorisierungsanfragen müssen über das eigene Backend laufen.
Keine gemeinsamen persönlichen Keys: Bei Austritt oder Geräteverlust lässt sich ein geteilter Key nicht individuell sperren.

5. Den Key in Umgebungsvariablen ablegen

Nicht fest im Code hinterlegen. In einem Python-Projekt lässt sich der Key so lesen:

import os
from openai import OpenAI

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

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Erster Textabschnitt", "Zweiter Textabschnitt"],
)
print(len(resp.data[0].embedding))

Bei lokaler Nutzung einer .env-Datei diese in .gitignore aufnehmen und nur .env.example committen. In der Produktion bevorzugt Container-Secrets, den Key-Management-Dienst des Cloud-Anbieters oder einen Dienst wie Vault verwenden. Keys gehören nicht in Dockerfiles, Image-Schichten, Frontend-Builds oder CI-Logs.

Außerdem gilt: Nach einer Änderung der Umgebungsvariablen muss der Prozess neu gestartet werden. Viele Fälle von „online 401, lokal funktioniert es“ entstehen, weil der Dienst noch die alten Variablen liest oder die Deployment-Plattform sie nicht in die Laufzeitumgebung injiziert.

6. Vorgehen bei 401

Bei 401 Unauthorized in dieser Reihenfolge prüfen; meist ist die Ursache in wenigen Minuten gefunden:

Prüfen, ob der Request-Header Authorization: Bearer sk-... lautet und zwischen Bearer und Key genau ein Leerzeichen steht.
Den Key erneut kopieren und auf Leerzeichen, Zeilenumbrüche, Anführungszeichen oder unsichtbare Zeichen prüfen.
Bestätigen, dass der Key nicht gelöscht, deaktiviert oder abgelaufen ist.
Prüfen, ob der Key zur Plattform der aktuellen Base URL gehört; einen Key von Plattform A nicht an Plattform B senden.
Sicherstellen, dass der Prozess die Umgebungsvariable tatsächlich liest und nicht einen leeren String erhält.
Prüfen, ob Reverse-Proxy, Gateway oder SDK den Authorization-Header verändert.
Wenn nur ein Teil der Anfragen fehlschlägt: prüfen, ob ein Key im Frontend offengelegt und daraufhin vom Risikomanagement gesperrt wurde.

Ergänzend: 401 ist ein Identitätsproblem, 403 meist ein Rechte- oder Regionsproblem, 429 häufig eine Rate- oder Kontingentfrage. Nicht jeder Fehler liegt am Key.

7. Offizieller Key oder Gateway-Key

Beide Wege funktionieren; die Unterschiede liegen bei Einkauf, Netzwerk und Wartung:

Offizielle Direktverbindung: Konto, Rechnung und Modelle verwaltet der Hersteller. Geeignet für Teams mit Auslandszahlungsmöglichkeit, die Netzwerk und Compliance selbst abdecken können. Nachteil: Modelle verteilen sich auf mehrere Plattformen, Keys und Abrechnung müssen getrennt verwaltet werden.
Gateway-Zugang: Eine Base URL und ein Key für mehrere Modelle, bequemer Zugang aus China und Abrechnung in RMB, zentralisierte Logs und Limits. Der Preis ist eine zusätzliche Abhängigkeit; Datenrichtlinien, Verfügbarkeit und Störungsbehandlung des Anbieters müssen geprüft werden.

Nicht nur auf den Preis achten. Klären Sie mindestens: ob Daten aufbewahrt werden, ob Rechnungen möglich sind, wie bei Störungen informiert wird, ob Modellabkündigungen vorher angekündigt werden und ob sich Nutzungsdaten exportieren lassen. Modelle und Preise richten sich nach der aktuellen Preisübersicht. Preise ändern sich; budgetieren Sie nicht mit Zahlen aus älteren Artikeln.

8. Rotation und Umgang mit Leaks

Machen Sie Rotation zu einer festen Routine, nicht zu einer Reaktion auf Vorfälle:

Im Ursprungsportal einen neuen Key mit gleichen Rechten anlegen.
Umgebungsvariablen oder den Wert im Key-Management aktualisieren.
Dienst neu starten oder neu deployen und einmal die Embedding-Schnittstelle erfolgreich aufrufen.
Das Nutzungsprotokoll 24 bis 48 Stunden beobachten und auf Auffälligkeiten prüfen.
Den alten Key löschen und den Rotationszeitpunkt dokumentieren.

Bei Verdacht auf ein Leak ist die Reihenfolge umgekehrt: zuerst den alten Key deaktivieren, dann Nutzungsprotokoll und Repository-Historie prüfen, erst danach einen neuen Key anlegen. Das Löschen einer Zeichenkette im Code genügt nicht; der Key kann bereits in CI-Logs, Image-Schichten oder Caches von Drittanbietern gelandet sein.

Häufige Fragen

Braucht Embedding zwingend einen eigenen Key?

Nicht unbedingt. Die meisten OpenAI-kompatiblen Plattformen erlauben denselben Key für Embedding und Chat. Ob Sie getrennt anlegen, hängt davon ab, ob Sie Limits, Audits oder eine separate Deaktivierung brauchen.

Ist der vollständige Key nach der Erstellung noch sichtbar?

Meist nicht. Der vollständige Key wird nur bei der Erstellung angezeigt, danach bleibt nur ein Präfix oder eine Maske. Wenn Sie ihn nicht gespeichert haben, löschen Sie ihn und legen Sie einen neuen an; suchen Sie nicht in Logs danach.

Kann ein Key mehrere Embedding-Modelle aufrufen?

In der Regel ja; das Modell wird im Feld model der Anfrage angegeben. Verfügbare Modelle und Dimensionen richten sich nach der Plattformdokumentation und der Preisübersicht.

Lokal funktioniert curl, online kommt 401 – warum?

Zuerst drei Dinge prüfen: ob die Umgebungsvariablen online injiziert werden, ob der Reverse-Proxy den Authorization-Header beibehält und ob online ein anderer, gelöschter oder abgelaufener Key verwendet wird. Danach prüfen, ob die Base URL auf die falsche Plattform zeigt.

Reicht Löschen nach einem Key-Leak?

Nein. Zuerst den Key deaktivieren, dann im Nutzungsprotokoll auf ungewöhnliche Aufrufe prüfen, Repository, CI-Logs und Image-Historie untersuchen und schließlich alle möglicherweise betroffenen Keys rotieren. Bei aufgeladenem Guthaben zusätzlich prüfen, ob das Limit angepasst werden muss.

Nächster Schritt

Wer noch kein Konto hat, kann über die Registrierungsseite starten, einen Key mit niedrigem Limit anlegen und zunächst mit einem einzelnen Text /v1/embeddings testen. Danach das passende Modell anhand der Preisübersicht wählen. Für den weiteren Ablauf der Vektorisierung siehe die verlinkten Anleitungen.

Weiterlesen: