API-Referenz
Endpunkt-für-Endpunkt-Dokumentation für StellarCloud. OpenAI-kompatibel, wo möglich. REST + JSON durchgängig.
Base URL
Managed-Bereitstellungen: https://api.stellarcloud.ai/v1
Selbst gehostete Bereitstellungen: https://your-domain/v1
Die Versionierung erfolgt pfadbasiert. Breaking Changes wechseln auf /v2 mit einem Deprecation-Fenster von mindestens 12 Monaten.
Authentifizierung
Bearer-Token im Authorization-Header. API-Schlüssel werden in der Admin-UI mit Scopes, Rate Limits und Ablaufdatum pro Schlüssel verwaltet.
Schlüssel sind entweder organisationsweit oder Base-bezogen. Best Practice: ein Schlüssel pro Dienst / Anwendung, vierteljährlich rotiert.
Übersicht der Endpunkte
Chat & Completions
| Endpunkt | Zweck |
|---|---|
POST /chat/completions | OpenAI-kompatible Chat-Completion |
POST /completions | Legacy-Text-Completion (nicht empfohlen) |
POST /embeddings | OpenAI-kompatible Embeddings |
StellarCloud-spezifisch
| Endpunkt | Zweck |
|---|---|
POST /ocr | StellarOCR — Dokument zu strukturierter Ausgabe |
POST /detect-language | Spracherkennung |
POST /ner | Named Entity Recognition |
POST /entity-linking | Entitäten mit kanonischen IDs verknüpfen |
POST /lemmatize | Lemmatisierung |
POST /rerank | Cross-Encoder-Re-Ranking |
POST /image-embeddings | Bild-Embeddings |
Plattform
| Endpunkt | Zweck |
|---|---|
POST /search | Hybride Suche über eine Base |
POST /sources | Datenquellen-Konnektoren verwalten |
POST /agents | Agenten erstellen / aktualisieren |
POST /workflows/<id>/trigger | Einen Workflow ausführen |
GET /audit-log | Audit-Log abfragen |
StellarGate
| Endpunkt | Zweck |
|---|---|
POST /gate/anonymize | Modus 2 — Anonymisierung ohne Weiterleitung |
POST /gate/deanonymize | Modus 2 — Tokens mit map_id auflösen |
POST /gate/dictionaries | Eigene Wörterbücher verwalten |
POST /gate/hitl/queue | HITL-Freigabewarteschlange |
Für Modus 1 (Transparent Proxy) verwenden Sie POST /chat/completions — StellarGate übernimmt die Anonymisierung transparent.
Konventionen für Request / Response
- Alle Requests und Responses sind JSON, UTF-8-kodiert
- Zeitstempel sind ISO 8601 in UTC
- IDs sind undurchsichtige Zeichenketten, Groß-/Kleinschreibung wird beachtet
- Paginierung über den Parameter
cursor;next_cursorin der Response - Rate Limits werden über
X-RateLimit-*-Header kommuniziert
Fehler
Standard-HTTP-Statuscodes + JSON-Fehlertext:
| Status | Bedeutung |
|---|---|
| 400 | Bad Request — ungültiges JSON oder Parameter |
| 401 | Fehlender oder ungültiger API-Schlüssel |
| 403 | API-Schlüssel hat keine Berechtigung für die Ressource |
| 404 | Ressource nicht gefunden |
| 409 | Conflict (z. B. gleichzeitige Änderung) |
| 422 | Eingabe hat die Schema-Validierung nicht bestanden |
| 429 | Rate Limit überschritten — Wiederholung nach Retry-After Sekunden |
| 500 | Interner Serverfehler — bei Persistenz an den Support melden |
| 502 / 503 | Upstream-Anbieter nicht verfügbar |
Fehlertext: code (maschinenlesbar), message (menschenlesbar), request_id (zur Korrelation mit dem Support).
Rate Limits
Standardwerte:
- 50 Requests pro Sekunde pro API-Schlüssel
- 100 gleichzeitige Verbindungen pro API-Schlüssel
- Tägliches Ausgabenlimit pro Schlüssel konfigurierbar
Höhere Limits auf Anfrage verfügbar.
Streaming
Chat-Completions unterstützen Server-Sent-Events-(SSE-)Streaming über stream: true. Einzelne Tokens werden im Standard-OpenAI-SSE-Format gestreamt. Endet mit data: [DONE].
Idempotenz
Nicht-idempotente Endpunkte (POST, die Ressourcen erstellen) akzeptieren einen Idempotency-Key-Header. Sehen wir denselben Schlüssel innerhalb von 24 Stunden, geben wir die zwischengespeicherte Response zurück, anstatt erneut auszuführen.
Webhooks
Bei lang laufenden Operationen (große OCR-Jobs, Workflow-Läufe) benachrichtigen Webhooks Ihren Endpunkt bei Abschluss. Konfigurieren Sie Webhook-URLs in der Admin-UI. Payloads sind HMAC-signiert — verifizieren Sie die Signatur, bevor Sie ihnen vertrauen.
SDKs
Offizielle SDKs umhüllen die REST-API mit sprachspezifischer Ergonomie:
- Python —
stellarbaseauf PyPI - TypeScript / Node —
@stellarbase/sdkauf npm - Go, Java, .NET, Rust — Beta
Alle SDKs unterstützen die OpenAI-Kompatibilitätsschicht — wenn Sie bereits openai-python oder openai-node verwenden, ist die minimale Änderung nur die Base URL.
OpenAPI-Spec
Vollständige OpenAPI-3.1-Spec verfügbar unter https://api.stellarcloud.ai/v1/openapi.json. In Postman, Insomnia oder einen beliebigen Code-Generator importieren, um Client-Code zu generieren.