Die OpenAI-Schnittstelle

Jeder veröffentlichte Endpunkt stellt seine eigene Schnittstelle bereit, die dem Format der OpenAI-API folgt. Programme, die schon mit einem solchen Dienst sprechen können — Entwicklungsbibliotheken, Automatisierungswerkzeuge wie n8n, Agenten-Baukästen — lassen sich damit anbinden, ohne dass jemand Code für Ihre Plattform schreiben muss. Getauscht werden nur zwei Angaben: die Adresse und der Schlüssel.

Einschalten

Eingerichtet wird die Schnittstelle im Endpunkt-Editor im Reiter OpenAI-API. Der Reiter ist ohne Expertenmodus sichtbar.

Oben steht die Erreichbarkeit. Sie nennt als Satz die erste Bedingung, die noch nicht erfüllt ist — geprüft wird der Reihe nach:

1. Ist der Endpunkt veröffentlicht?
2. Sind Serverschlüssel für ihn zugelassen?
3. Gibt es mindestens einen aktiven Serverschlüssel?
4. Ist die Schnittstelle für Ihren Arbeitsbereich überhaupt freigeschaltet? Das entscheidet der Habicht-Support, nicht die Administration.

Darunter stehen unveränderlich die geltende Drosselung und das Wochenbudget. Die Drosselung gilt für den ganzen Endpunkt, gemeinsam mit dem Widget — sie ist kein zusätzliches Kontingent für angebundene Programme. Gesetzt werden beide Werte im Reiter Limits & Compliance.

Serverschlüssel zulassen

Der Schalter Serverschlüssel zulassen entscheidet, ob Aufrufe mit einem Serverschlüssel angenommen werden. Er gehört zum Betrieb, nicht zum Entwurf: Er wirkt sofort, ohne Speichern und Veröffentlichen, und wird protokolliert. Steht er aus, werden solche Aufrufe mit dem Code api_access_disabled abgewiesen.

Bei einem neu angelegten Endpunkt ist der Schalter zunächst aus; ihn einzuschalten ist ein bewusster Schritt. Bestehende Endpunkte sind zugelassen.

Der Schalter schließt den Endpunkt nicht. Er betrifft ausschließlich die Serverschlüssel. Die öffentlichen Schlüssel des Widgets arbeiten weiter — ein öffentlicher Schlüssel steht im Quelltext der Seite, auf der er eingebettet ist, und die mitgesendete Herkunft lässt sich fälschen. Die Herkunftsfreigabe schützt vor fremder Einbettung, sie ist keine Zugangssperre. Wollen Sie einen Endpunkt vollständig schließen, sperren Sie seine Schlüssel oder setzen Sie ihn in den Zustand stillgelegt.

Eigene Werkzeuge des Programms erlauben

Der zweite Schalter, Eigene Werkzeuge des Programms erlauben, ist Verhalten und damit Teil des Entwurfs: Er wirkt erst, wenn Sie speichern und veröffentlichen. Nehmen Sie eine Version zurück, gilt wieder die Einstellung jener Version, auf die Sie zurückgehen.

Steht er aus, wird eine Anfrage, die eigene Funktionen mitschickt, mit dem Code client_tools_disabled abgewiesen — die Meldung nennt den beanstandeten Parameter, damit das Programm weiß, was es weglassen muss. Worum es dabei geht, steht weiter unten unter „Eigene Werkzeuge des anfragenden Programms".

Adresse, Modellname und Beispiele

Im selben Reiter stehen die Basisadresse und der Modellname mit Kopierschaltflächen sowie fertige Beispiele für Python, JavaScript und die Kommandozeile. Die Beispiele tragen einen Platzhalter statt eines echten Schlüssels — den setzen Sie beim Einfügen selbst ein.

Auch die Serverschlüssel verwalten Sie hier. Die öffentlichen Schlüssel liegen im Reiter Widget, direkt beim Einbettungs-Schnipsel.

Die Adresse

Die Basisadresse trägt zwei Kürzel: das Ihres Arbeitsbereichs und das des Endpunkts.

https://ihre-adresse.example/v1/endpoints/ihr-arbeitsbereich/ihr-endpunkt-kuerzel

Sie finden sie im Reiter OpenAI-API mit einer Kopierschaltfläche — kopieren Sie sie von dort, statt sie zusammenzusetzen. Das angebundene Programm setzt zusätzlich einen Modellnamen; dort tragen Sie nur das Endpunkt-Kürzel ein, nicht die ganze Adresse.

Warum beide Kürzel? Das Endpunkt-Kürzel muss nur in Ihrem Arbeitsbereich eindeutig sein — ein anderer Arbeitsbereich derselben Plattform darf dasselbe verwenden. Erst beide zusammen benennen genau einen Endpunkt. Das Kürzel Ihres Arbeitsbereichs wird beim Anlegen automatisch aus seinem Namen gebildet; es liegt fest, sobald darunter etwas veröffentlicht ist, weil es dann in fremdem Code steht.

Der Grund dafür ist der wichtigste Unterschied zu einem reinen Modellzugang: Ein Endpunkt ist kein Modell, sondern eine fertig eingerichtete Auskunftsstelle. Er bringt seine Anweisung mit, sein freigegebenes Wissen, seine Werkzeuge, seine Grenzen und seine Kostenstelle. Deshalb bietet er genau einen Namen an, und ein anderer Name wird abgelehnt statt stillschweigend ersetzt — sonst sähe eine falsch eingetragene Adresse aus wie eine funktionierende.

Der Schlüssel

Ein Serverschlüssel (siehe Schlüssel verwalten) wird als Zugangsschlüssel eingetragen. Drosselung, Wochenbudget und Protokollierung gelten dabei unverändert.

Die Herkunftsfreigabe gilt hier dagegen nicht: Sie ist der Schutz der öffentlichen Schlüssel im Browser. Ein Serverschlüssel wird aus Ihrem eigenen Backend gesendet, wo es keine Herkunft zu prüfen gibt — sein Schutz besteht allein darin, dass er geheim bleibt.

Ein Beispiel

Python:

from openai import OpenAI

client = OpenAI(
    base_url="https://ihre-adresse.example/v1/endpoints/ihr-arbeitsbereich/ihr-endpunkt-kuerzel",
    api_key="hab_live_…",
)

antwort = client.chat.completions.create(
    model="ihr-endpunkt-kuerzel",
    messages=[{"role": "user", "content": "Bis wann läuft die Frist?"}],
)
print(antwort.choices[0].message.content)

JavaScript:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL:
    "https://ihre-adresse.example/v1/endpoints/ihr-arbeitsbereich/ihr-endpunkt-kuerzel",
  apiKey: "hab_live_…",
});

const antwort = await client.chat.completions.create({
  model: "ihr-endpunkt-kuerzel",
  messages: [{ role: "user", content: "Bis wann läuft die Frist?" }],
});

Beides funktioniert wahlweise mit fortlaufender Ausgabe (stream: true) oder als eine vollständige Antwort auf einmal.

Ohne Angabe kommt eine vollständige Antwort zurück, so wie es die Bibliotheken der Programme erwarten. Wer die Antwort Wort für Wort mitlesen will, setzt stream: true ausdrücklich.

Nachbesserung: vollständige Antwort gegen fortlaufende Ausgabe

Die Plattform prüft eine fertige Antwort, bevor sie sie als endgültig betrachtet — etwa, ob jede Quellenangabe belegt ist — und bessert sie bei Bedarf in einem zweiten Durchgang nach. Wie das beim anfragenden Programm ankommt, hängt von der Ausgabeart ab:

Ausgabeart	Nachbesserung
Vollständige Antwort (ohne stream)	Findet statt. Das Programm erhält nur die endgültige Fassung.
Fortlaufende Ausgabe (stream: true)	Findet nicht statt. Der Text steht beim Programm schon, während er entsteht; Quellenverweise ohne Beleg werden entfernt.
Eingebettetes Fenster	Findet statt. Das Fenster ersetzt die erste Fassung sichtbar durch die nachgebesserte.

Kommt es Ihnen auf die geprüfte Fassung an, lassen Sie das Programm ohne stream anfragen.

Die fortlaufende Ausgabe läuft etwas hinter dem Modell her. Die Plattform hält jeweils die letzten rund 32 Wörter zurück und prüft sie, bevor sie sie weitergibt. Beginnt das Modell, sich zu wiederholen, oder wird der Text unlesbar, endet die Antwort an dieser Stelle mit dem Hinweis (Ausgabe hier gekürzt — sie war nicht mehr lesbar.) bzw. (… sie begann sich zu wiederholen.) — je nach Sprache der Anfrage auch auf Englisch. Das Programm erhält keinen Entwurf, der danach durch einen zweiten ersetzt würde, und keine interne Werkzeug-Syntax des Modells.

Was dabei intern passiert

Eine Anfrage über diese Schnittstelle durchläuft denselben Ablauf wie eine Frage im Chat: Das freigegebene Wissen wird durchsucht und zitiert, die freigeschalteten Werkzeuge werden aufgerufen, Ablehnungsregeln und Filter greifen, und es antwortet das für den Endpunkt eingestellte Modell.

Das anfragende Programm bekommt also nicht ein Sprachmodell, sondern Ihre eingerichtete Auskunft — mit Ihrem Wissen und Ihren Regeln.

Eigene Werkzeuge des anfragenden Programms

Manche Programme bringen eigene Funktionen mit und erwarten, dass die Auskunftsstelle sie anfordert, statt sie selbst auszuführen — etwa ein Automatisierungswerkzeug, das einen Datensatz in einem Ihrer Fachverfahren anlegen kann.

Ob ein Endpunkt das annimmt, entscheidet der Schalter Eigene Werkzeuge des Programms erlauben im Reiter OpenAI-API. Steht er aus, wird eine solche Anfrage abgewiesen, statt die Funktionen stillschweigend zu übergehen — sonst wartete das Programm auf eine Aufforderung, die nie käme.

Ist er an, gilt Folgendes: Das Modell sieht diese Funktionen, und wenn es eine davon wählt, endet die Antwort mit der Aufforderung, sie auszuführen. Das anfragende Programm führt sie aus und schickt das Ergebnis in der nächsten Anfrage mit.

Zwei Dinge sind dabei zu wissen:

• Die Funktionsbeschreibungen, die das Programm mitschickt, erreichen wörtlich das Modell. Sie sind damit Teil der Anweisung und sollten so sorgfältig formuliert sein wie Ihre eigene.
• Wählt das Modell in derselben Runde eine eigene Funktion der Plattform und eine des Programms, wird nur die des Programms angefordert; die andere wird zurückgestellt und in der nächsten Runde erneut gewählt, falls sie noch gebraucht wird. Anders ginge es nicht: Das Programm kann nur beantworten, wonach es gefragt wurde.

Funktionen angebundener Fremdsysteme

Werkzeuge aus angebundenen Fremdsystemen stehen einem Endpunkt nur zur Verfügung, wenn sie ohne persönliche Zugangsdaten aufrufbar sind — also entweder ohne Anmeldung oder mit einem fest hinterlegten Kopfzeilenwert, der dem Arbeitsbereich gehört.

Der Grund ist keine technische Einschränkung, sondern eine Entscheidung: Ein Endpunkt antwortet anonymen Anfragenden. Er hat keine angemeldete Person, deren Zugangsdaten er verwenden könnte — und die einer anderen Person zu benutzen hieße, in deren Namen zu handeln; das Protokoll des Fremdsystems würde genau das ausweisen.

Ein Fremdsystem, das ein persönliches Zugangstoken verlangt, wird deshalb übersprungen. Sie erfahren das beim Veröffentlichen als Hinweis in der Prüfung und finden es im Protokoll wieder — die Funktion würde sonst gebunden aussehen und nie aufgerufen werden.

Was nicht unterstützt wird

Die Schnittstelle akzeptiert alle gängigen Einstellungen (Temperatur, Längenbegrenzung, Stoppzeichen, Zufallszahl, Antwortformat). Einstellungen, für die es hier keine Entsprechung gibt, werden angenommen, aber nicht angewendet — und das Programm erfährt es: Die Antwort nennt in einer eigenen Kopfzeile genau die Einstellungen, die ohne Wirkung geblieben sind. Eine unbekannte Angabe wird dagegen abgelehnt, damit sie nicht unbemerkt verschwindet.

Nicht angeboten werden reine Modellzugänge (Einbettungen, Textvervollständigung ohne Chat-Verlauf). Sie würden am Endpunkt vorbei direkt auf das Modell zugreifen und damit weder Ihr Wissen noch Ihre Regeln berücksichtigen.

Wie viel Text eine Anfrage tragen darf

Es gibt keine feste Zeichengrenze je Nachricht. Ein Programm darf ein ganzes Dokument in eine Nachricht legen; die Grenze ist das Kontextfenster des Modells, das dem Endpunkt zugeordnet ist. Passt eine Unterhaltung nicht mehr hinein, werden — wie im Chat der Plattform — zunächst ältere Beiträge zusammengefasst und dann weggelassen. Reicht auch das nicht, wird der Aufruf mit dem Code context_overflow abgewiesen, und das Programm muss seine Anfrage kürzen. Unabhängig davon darf eine einzelne Anfrage höchstens 8 MB groß sein; das genügt für die größten heute konfigurierbaren Kontextfenster.

Wenn ein Aufruf abgewiesen wird

Fehler kommen im selben Format zurück, das die angebundenen Programme von anderen Anbietern kennen — sie unterscheiden dadurch selbstständig zwischen „zu viele Anfragen" (später erneut versuchen) und „Anfrage fehlerhaft" (nicht wiederholen).

Meldung im Feld code	Bedeutung
invalid_authentication	Schlüssel fehlt, ist falsch oder wurde gesperrt
endpoint_not_active	Der Endpunkt ist nicht veröffentlicht
model_not_found	Der eingetragene Modellname ist nicht das Endpunkt-Kürzel
unknown_parameter	Eine Einstellung, die diese Schnittstelle nicht kennt
rate_limit_exceeded	Eine Drosselung greift — die eigene oder die des Modell-Dienstes. Die Antwort nennt die Wartezeit, gängige Bibliotheken warten selbstständig ab.
api_access_disabled	Serverschlüssel sind für diesen Endpunkt nicht zugelassen
client_tools_disabled	Eigene Werkzeuge des Programms sind nicht erlaubt
context_overflow	Die Anfrage passt auch gekürzt nicht in das Kontextfenster des Modells — das Programm muss sie verkleinern, nicht wiederholen

Bricht eine bereits laufende Antwort ab, erhält das Programm einen Fehler mitten im Datenstrom statt einer stillschweigend verkürzten Antwort.