Licensed to be used in conjunction with basebox, only.
// integration
Quickstart
Gilt für
Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator
In wenigen Minuten zur ersten erfolgreichen Chat-Completion: API-Schlüssel besorgen, Basis-URL und Realm für Ihre Umgebung bestimmen, eine Anfrage mit curl senden, dann dasselbe mit dem OpenAI-SDK. Alles Weitere – Streaming, Fehler, Tool Calling – steht in den verlinkten Seiten.
1. API-Schlüssel besorgen
API-Schlüssel stellt ein Administrator Ihrer Organisation aus: Administration → API-Schlüssel → „API-Schlüssel erstellen". Der Schlüssel wird nur einmal angezeigt. Er gilt für Ihre Organisation und alle ihr freigegebenen Modelle – siehe API-Berechtigungen.
Auf basebox Server muss die REST-API außerdem aktiviert sein (AISRV_ENABLE_REST_API=true, Aufgabe des Platform Operators); sonst fehlt der Bereich in der Administration.
2. Basis-URL und Realm bestimmen
| basebox Cloud | basebox Server | |
|---|---|---|
| Basis-URL | https://aims.basebox.ai |
Die Adresse Ihrer Installation, z. B. https://basebox.firma.internal |
X-Realm |
Ihre Subdomain, z. B. myorg |
In der Regel primary – nachsehen unter Benutzermenü → „Über", Zeile Realm |
Beide Werte brauchen Sie in jeder Anfrage.
3. Verbindung prüfen
export BASEBOX_URL="https://your-org.basebox.ai"
export BASEBOX_REALM="your-org"
export BASEBOX_API_TOKEN="<your-token>"
curl -s "$BASEBOX_URL/v1/models" \
-H "Authorization: Bearer $BASEBOX_API_TOKEN" \
-H "X-Realm: $BASEBOX_REALM"
Die Antwort listet die Modelle, die Ihre Organisation nutzen darf. Einen dieser Bezeichner verwenden Sie im nächsten Schritt als model. Kommt ein 401, fehlt „Bearer " oder der Schlüssel ist falsch; kommt ein 403, deckt die Lizenz die API nicht ab oder der Realm stimmt nicht.
4. Erste Chat-Completion
curl -s -X POST "$BASEBOX_URL/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BASEBOX_API_TOKEN" \
-H "X-Realm: $BASEBOX_REALM" \
-d '{
"model": "<model-id-from-step-3>",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Say hello in one sentence."}
],
"stream": false
}'
Sie erhalten ein OpenAI-kompatibles chat.completion-Objekt mit choices[0].message.content und einem usage-Block.
5. Dasselbe mit dem OpenAI-SDK
Jede OpenAI-Client-Bibliothek funktioniert, wenn Sie base_url auf /v1 Ihrer Instanz zeigen lassen und den X-Realm-Header als Standard-Header mitgeben:
from openai import OpenAI
import os
client = OpenAI(
base_url=f"{os.environ['BASEBOX_URL']}/v1",
api_key=os.environ["BASEBOX_API_TOKEN"],
default_headers={"X-Realm": os.environ["BASEBOX_REALM"]},
)
models = client.models.list()
model_id = models.data[0].id
response = client.chat.completions.create(
model=model_id,
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)
Node.js, Go, .NET und andere SDKs verhalten sich gleich: Basis-URL, API-Schlüssel, Standard-Header.
6. Interaktiv weiterprobieren
Unter $BASEBOX_URL/v1/api/docs steht Swagger UI: Mit Authorize das Token eintragen, Endpunkte ausführen, Schemata ansehen und den erzeugten curl-Befehl kopieren. Anleitung: Testen mit Swagger UI.
Die REST-Variante
Neben der OpenAI-kompatiblen API gibt es den REST-Endpunkt POST /rest/v1/chat/completions mit demselben Header-Schema. Als Modell dient dort ai.basebox.assistant. Details: REST API · Authentifizierung.
Wie es weitergeht
- Antworten fortlaufend empfangen: Streaming
- Fehler richtig behandeln (401, 403, 404, Timeouts, Kontext zu groß): Fehlerbehandlung
- Denkmodi über die API steuern: Reasoning-Aufwand
- Editor oder Coding-Agent anbinden: IDE-Integration · OpenClaw-Integration
- Vollständige Referenz mit Beispielen und häufigen Fehlern: Benutzerhandbuch
Schlüssel wie ein Passwort behandeln
Nie in Git einchecken, immer über Umgebungsvariablen oder einen Secret-Store laden. Ein kompromittierter Schlüssel wird vom Administrator gelöscht und neu ausgestellt.