Die AI-Zentrale-API anbinden
Sie erstellen einen begrenzten externen API-Schlüssel, konfigurieren einen kompatiblen Client, kopieren einen ausführbaren Beispielaufruf und prüfen Erfolg, Modellgrenze, Budgetfehler sowie Widerruf.
Voraussetzungen
- Eine Rolle mit „Konfiguration verwalten“ für den Bereich Einstellungen → API-Zugriff.
- Eine getrennte Testumgebung mit Secret Store und ohne produktive oder personenbezogene Beispieldaten.
- Basis-URL der eigenen AI-Zentrale-Umgebung und mindestens ein für den Test freigegebenes Modell.
Freigabecheck für einen technischen API-Zugang
Verwenden Sie für Anwendung und Umgebung einen eigenen, widerrufbaren Schlüssel.
Schritt für Schritt
API-Zugriff und vorhandene Schlüssel prüfen
Öffnen Sie Einstellungen → API-Zugriff. Prüfen Sie den übergeordneten API-/Automatisierungs-Budgetrahmen, vorhandene technische Identitäten, deren Status, individuelle Budgets und Anzahl freigegebener Modelle.
Die Schlüsselübersicht verbindet gemeinsamen Budgetrahmen, technische Identitäten, Status, individuelles Budget und Modellanzahl.
Eigene technische Identität für Anwendung und Umgebung anlegen
Erstellen Sie einen separaten externen Schlüssel für genau eine Anwendung und Umgebung. Verwenden Sie einen Namen, der Zweck und Verantwortlichkeit später ohne Kenntnis des Geheimniswerts erkennen lässt.
Modelle und Budget am einzelnen Schlüssel begrenzen
Wählen Sie nur benötigte Chat- und gegebenenfalls Embedding-Modelle. Setzen Sie ein eigenes Budget; der übergeordnete Automatisierungsrahmen begrenzt den Zugang zusätzlich.
Die Detailansicht zeigt die konkrete Modell-Allowlist; Budget und Verbrauch bleiben dem technischen Zugang zugeordnet.
Einmaligen Geheimniswert direkt in den Secret Store übernehmen
Kopieren Sie den erzeugten Schlüssel sofort in den vorgesehenen Secret Store. Speichern Sie ihn nicht im Quellcode, Ticket, Chat, Screenshot oder in der Dokumentation und planen Sie keinen späteren Abruf des Klartexts ein.
Endpunkt und kompatiblen Client auswählen
Ordnen Sie die Aufgabe über die Endpoint-Tabelle einem OpenAI- oder Anthropic-kompatiblen Pfad zu. Verwenden Sie die Basis-URL Ihrer Umgebung und exakt den für den Schlüssel freigegebenen Modellnamen.
Passenden Authentifizierungsheader konfigurieren
Setzen Sie für OpenAI-kompatible Endpunkte Authorization: Bearer und für Anthropic-kompatible Endpunkte x-api-key. Übergeben Sie den Wert ausschließlich aus der Umgebungsvariable des Secret Stores.
Quickstart ausführen und Antwortstruktur prüfen
Ersetzen Sie Basis-URL und Modell im kopierbaren Beispiel. Senden Sie zuerst einen nicht streamenden Test und prüfen Sie, ob die Antwort dem Aufruf und der unten gezeigten kompatiblen Struktur entspricht.
Gesperrtes Modell und Budgetfehler getrennt testen
Rufen Sie in der Testumgebung ein nicht freigegebenes Modell auf und prüfen Sie eine bewusst gesetzte Budgetgrenze. Sichern Sie Status und Antwortkörper, ohne den Schlüsselwert zu protokollieren.
Streaming, Verbrauch und Widerruf verifizieren
Testen Sie Streaming als Server-Sent Events nur, wenn der Client es benötigt. Ordnen Sie Verbrauch dem Schlüssel zu und widerrufen Sie einen nicht mehr benötigten oder offengelegten Zugang unmittelbar.
Kopierbarer Quickstart
Aufruf ausführen und kompatible Antwort erkennen
curl "https://ai-zentrale.ihr-unternehmen.de/v1/chat/completions" \
-H "Authorization: Bearer $AI_ZENTRALE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [{"role": "user", "content": "Hallo"}]
}'import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["AI_ZENTRALE_API_KEY"],
base_url="https://ai-zentrale.ihr-unternehmen.de",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hallo"}],
){
"id": "chatcmpl-…",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "Hallo!" },
"finish_reason": "stop"
}
]
}Kompatible Endpunkte und Authentifizierung zuordnen
Der Endpunkt bestimmt Anfrageformat und Header. Modell-Allowlist und separates Budget gelten weiterhin für den verwendeten externen Schlüssel.
Horizontal wischen, um Pfad, Zweck und Header zu lesen →
| Funktion | Methode | Pfad | Zweck | Authentifizierung |
|---|---|---|---|---|
| Modelle | GET | /v1/models | Für den Schlüssel verfügbare Modelle auflisten. | Authorization: Bearer |
| Chat Completions | POST | /v1/chat/completions | OpenAI-kompatible Chat-Anfrage senden. | Authorization: Bearer |
| Responses | POST | /v1/responses | OpenAI-kompatible Responses-Anfrage senden. | Authorization: Bearer |
| Embeddings | POST | /v1/embeddings | Ein ausdrücklich freigegebenes Embedding-Modell aufrufen. | Authorization: Bearer |
| Messages | POST | /v1/messages | Anthropic-kompatible Nachricht senden. | x-api-key |
| Tokens zählen | POST | /v1/messages/count_tokens | Anthropic-kompatible Tokenanzahl vor dem Aufruf bestimmen. | x-api-key |
Fehlerantworten anhand von Status und Fehlerobjekt einordnen
Fehler werden über den HTTP-Statuscode und ein Fehlerobjekt im Antwortkörper signalisiert. Werten Sie für die Fehlerbehandlung im Client beide Angaben aus.
Horizontal wischen, um den aktuellen Umgang zu lesen →
| Betriebsangabe | Verhalten | Aktueller Umgang |
|---|---|---|
| Fehlercodes | Fehlerfälle für ungültigen Schlüssel, gesperrtes Modell und Budget sind über HTTP-Statuscode und Fehlerobjekt im Antwortkörper prüfbar. | Status, Antwortkörper, Zeitpunkt und betroffenen Schlüssel ohne Geheimniswert für den Fehlerfall sichern. |
| Versionierung | Die kompatiblen Pfade liegen unter /v1. | Client- und Integrationstests vor jeder Umstellung auf einen neuen Endpunkt wiederholen. |
Endzustand: Aufruf, Grenzen und Widerruf sind belegt
Der erlaubte Aufruf liefert eine zuordenbare Antwort, nicht freigegebene Modelle und die getestete Budgetgrenze werden abgewiesen, Verbrauch bleibt dem Schlüssel zugeordnet und der Widerrufsweg ist dokumentiert.
Achtung: Der Geheimniswert wird nur einmal im Klartext angezeigt. Er gehört ausschließlich in den Secret Store der aufrufenden Umgebung.
Achtung: Passen Sie Basis-URL und Modellnamen im Quickstart an Ihre Umgebung und Ihre freigegebenen Modelle an.
Häufige Probleme
Die API weist den Schlüssel zurück.
Prüfen Sie Basis-URL, passenden Header, unveränderte Übernahme aus dem Secret Store und Widerrufsstatus. Geben Sie den Schlüssel nicht zur Diagnose in Logs oder Tickets aus.
Ein Modellaufruf wird abgewiesen.
Vergleichen Sie den Modellnamen im Request mit der Allowlist des verwendeten Schlüssels. Erweitern Sie nicht vorsorglich auf alle Modelle.
Der Aufruf scheitert an einem Budget.
Prüfen Sie individuelles Schlüsselbudget und gemeinsamen Automatisierungsrahmen. Erhöhen Sie nur die belegbar zu knappe Grenze und wiederholen Sie den Soll-Test.
Streaming wird als unvollständige Antwort verarbeitet.
Behandeln Sie die Antwort als Server-Sent Events und lassen Sie den kompatiblen Client die Ereignisse zusammensetzen. Testen Sie zunächst denselben Aufruf ohne Streaming.