Keural API

Rufen Sie in Keural registrierte Modelle im OpenAI-Chat-Completions-Format auf.

Die Basis-URL hat das Format https://<Ihre öffentliche API-Domain>/llm/v1. Die öffentliche API-Domain unterscheidet sich je nach Umgebung. Fragen Sie Ihren Administrator.

Pfade für Embeddings, Bildgenerierung, Sprache und die Responses-API werden nicht unterstützt. Anfragen an diese Pfade beantwortet die API mit 404.

Ablauf der NutzungAnkerlink kopieren

VoraussetzungenAnkerlink kopieren

API-Schlüssel ausstellenAnkerlink kopieren

1. Öffnen Sie im Kontomenü unten links Einstellungen und wählen Sie API. In der Desktop- und Mobil-App finden Sie den Eintrag in der Gruppe Tools.
2. Wählen Sie auf der Registerkarte API keys den Arbeitsbereich, zu dem der Schlüssel gehört (persönlich oder Organisation), sowie die Model ID.
3. Legen Sie bei Bedarf das New key expiration (optional, Korea time) fest. Bleibt das Feld leer, gilt der Schlüssel bis zum Widerruf.
4. Klicken Sie auf Issue key und bewahren Sie den angezeigten Schlüssel mit Copy key an einem sicheren Ort auf. Der vollständige Schlüssel wird nur in diesem Moment angezeigt und lässt sich nach dem Schließen nicht mehr einsehen.

• Der Schlüssel ist mit dem gewählten Arbeitsbereich und einem Modell verknüpft. Die Nutzung wird der Person zugeordnet, die den Schlüssel ausgestellt hat.
• Je Kombination aus Arbeitsbereich und Modell kann nur ein Schlüssel gültig sein. Existiert bereits einer, wird kein weiterer ausgestellt: Stellen Sie ihn neu aus (Rotate) oder widerrufen Sie ihn (Revoke).
• Verlieren Sie den Schlüssel, können Sie ihn nicht mehr einsehen. Stellen Sie ihn neu aus; der alte Schlüssel funktioniert dann sofort nicht mehr.
• Erscheint die Meldung, dass keine Modelle verfügbar sind, prüfen Sie mit Ihrem Administrator die Sichtbarkeit der Modelle, Ihren Tarif und die API-Berechtigung der Organisation.

API-Berechtigung der OrganisationsmitgliederAnkerlink kopieren

Dies verwalten nur Inhaber und Administratoren der Organisation. Damit ein Mitglied im Organisations-Arbeitsbereich Schlüssel erstellen kann, muss der Administrator dies zuvor erlauben. Neue und bestehende Mitglieder sind standardmäßig gesperrt.

Organisationsverwaltung → Organization API besteht aus folgenden drei Bereichen. Fehlt das Menü, ist die API-Funktion deaktiviert oder Ihr Konto hat keine Organisationsverwaltungsrechte.

Verlässt ein Mitglied die Organisation oder wird es entfernt, werden die von ihm in der Organisation erhaltenen Schlüssel automatisch widerrufen.

Mit einem Client verbindenAnkerlink kopieren

Tragen Sie diese drei Werte in Apps ein, die OpenAI-API-kompatibel sind (Chat-Clients, IDE-Erweiterungen, Automatisierungswerkzeuge usw.).

1. Wählen Sie in den App-Einstellungen das Hinzufügen einer OpenAI-kompatiblen Verbindung (Connection).
2. Tragen Sie Base URL und API Key ein und speichern Sie.
3. Wählen Sie in der Modellliste ein Modell. Die Liste zeigt nur das mit dem Schlüssel verbundene Modell.
4. Senden Sie eine kurze Nachricht, um zu prüfen, ob eine Antwort kommt. Erscheint das ausgestellte Modell in der Modellliste, ist die Verbindung hergestellt.

Die Anfragen lauten wie folgt.

Erste AnfrageAnkerlink kopieren

export KEURAL_API_KEY='ihr_ausgestellter_schlüssel'
export KEURAL_BASE_URL='https://<ihre-api-domain>/llm/v1'
export MODEL_ID='modell-id_aus_dem_ausstellungsbildschirm'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hallo.\"}]}"

Das model im Anfragekörper muss mit dem Modell des Schlüssels übereinstimmen. Steht ein Pfadpräfix davor, wie etwa provider/Modell-ID, wird nur der Teil nach dem letzten / verglichen. Stimmt es nicht überein, liefert die API 403. Die Antwort enthält im Feld model immer die Modell-ID des Schlüssels.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Hallo."}],
)
print(res.choices[0].message.content)

Unterstützte AnfragefelderAnkerlink kopieren

Die API akzeptiert nur diese 18 Felder auf oberster Ebene. Andere Felder führen zu 400. Optionale Felder mit dem Wert null gelten als nicht gesendet.

NachrichtenAnkerlink kopieren

• Eine tool-Nachricht beantwortet jede id der vorherigen tool_calls nur einmal.
• Bildteile (image_url) sind nur in user-Nachrichten von Modellen erlaubt, die Bilder verarbeiten. Verwenden Sie eine http- oder https-Adresse oder eine Base64-Data-URI im Format PNG, JPEG, GIF oder WebP. detail ist auto, low oder high.

AnfragekörperAnkerlink kopieren

Verstoßen Sie gegen die Regeln für den Körper, lautet die Antwort 400, und param ist body.

StreamingAnkerlink kopieren

Mit "stream": true in der Anfrage antwortet die API per SSE. Jeder Abschnitt kommt als Ereignis data: ..., am Ende folgt data: [DONE]. Mit "stream_options": {"include_usage": true} wird kurz vor [DONE] noch ein Abschnitt mit der Token-Nutzung gesendet.

Mit include_usage enthalten alle Abschnitte usage: null, und der letzte Nutzungsabschnitt hat ein leeres Array choices. Nicht gestreamte Antworten enthalten usage nur, wenn Eingabe- und Ausgabe-Token bestätigt sind.

Die id der Antwort hat das Format chatcmpl-<x-request-id>. Alle Antworten enthalten den Header x-request-id.

Tritt während des Streamings ein Fehler auf, kommt ein data:-Ereignis mit dem Fehler-JSON, und die Verbindung endet ohne [DONE]. Überschreitet ein Abschnitt 1 MiB oder die Antwort 16 MiB, endet die Verbindung mit 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hallo.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

NutzungsgrenzenAnkerlink kopieren

Anfragen sind je Benutzer, Organisation und Modell begrenzt: gleichzeitige Anfragen, Anfragen pro Minute (RPM) und Token pro Minute (TPM). Die tatsächlichen Werte unterscheiden sich je nach Umgebung.

Die Token pro Minute werden beim Eingang der Anfrage reserviert. Die Eingabe zählt 1 Token je 4 englische Zeichen, andere Zeichen zählen 1 Token je Zeichen; jedes Bild zählt 2.000 Token. Die Ausgabe wird anhand von max_tokens reserviert (maximal 4.096). Begrenzen Sie die Ausgabe auf das Nötige, bleibt mehr Spielraum innerhalb des Limits.

SchlüsselverwaltungAnkerlink kopieren

Auf der Registerkarte API keys unter Einstellungen → API sehen Sie den Status der ausgestellten Schlüssel (gültig, abgelaufen oder widerrufen) und können sie neu ausstellen oder widerrufen.

Schlüssel sind 51-stellige Zeichenketten, die mit krl_llm_ beginnen. Pro Ausstellungsbereich kann nur ein Schlüssel gültig sein; existiert bereits einer, wird er neu ausgestellt statt ein neuer erstellt. Das Ablaufdatum kann nur ab heute festgelegt werden.

Nutzung einsehenAnkerlink kopieren

Über die API gesendete Anfragen und verbrauchte Token sehen Sie an zwei Stellen.

AbfragebedingungenAnkerlink kopieren

Legen Sie die Bedingungen fest und klicken Sie auf Abfragen. Um eine gerade gesendete Anfrage erneut anzuzeigen, klicken Sie auf Aktualisieren.

Werte auf dem BildschirmAnkerlink kopieren

• Angewendeter Abfragezeitraum: der tatsächlich abgefragte Zeitraum. Wurden Start- oder Endzeit leer gelassen oder überschreitet der Zeitraum 90 Tage, wird der vom Server angepasste Zeitraum angezeigt.
• Anzahl der Anfragen und Summen für Eingabe-Token · Ausgabe-Token · Gesamt-Token: Es werden nur bestätigte Werte addiert. Noch nicht bestätigte Token zählen nicht als 0, sondern werden als Nicht bestätigt angezeigt.
• Anfrageliste: Jede Anfrage steht in einer Zeile mit Uhrzeit, Model ID, Status sowie Eingabe-, Ausgabe- und Gesamt-Token. Pro Seite werden 20 angezeigt; mit Zurück und Weiter blättern Sie.

Mit Anfragedetails in einer Zeile klappen folgende Werte auf.

Streaming-Anfragen werden auch ohne stream_options.include_usage erfasst. Wird eine Anfrage mitten im Vorgang unterbrochen, kann sie als Teilweise bestätigt oder Nicht bestätigt erscheinen.

FehlerformatAnkerlink kopieren

Fehler werden im OpenAI-kompatiblen Format zurückgegeben.

{
  "error": {
    "message": "Für Menschen lesbare Fehlerbeschreibung",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type richtet sich nach dem Statuscode, code nennt die Ursache.

FehlerbehebungAnkerlink kopieren

Lässt sich das Problem nicht lösen, wenden Sie sich mit den folgenden Angaben an Ihren Administrator, damit die Ursache schneller gefunden wird. Senden Sie weder den Schlüsseltext noch den Inhalt der Prompts.

• Zeitpunkt des Auftretens
• Verwendete Modell-ID
• Name und Version der Client-App
• Wert von x-request-id aus dem Antwort-Header
• Auf dem Bildschirm angezeigte Fehlermeldung