Brane AIF Entwickler-API

1. Überblick

Die Box stellt ein OpenAI-kompatibles Gateway unter /api/v1 bereit. Jedes Werkzeug, das das OpenAI-Chat-Completions-Protokoll spricht — IDE-Erweiterungen (Continue, Cline), SDKs (openai, @ai-sdk/openai-compatible), n8n, eigene Anwendungen — kann die Box als Modell-Provider verwenden.

2. Base URL

https://<your-box-domain>/api/v1

Alle folgenden Endpoints sind relativ zu dieser Base URL (/api/v1/chat/completions, /api/v1/models usw.).

3. Authentifizierung

Bei jeder Anfrage ein Bearer-Token:

Authorization: Bearer brn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Einen Key erzeugen Sie im Admin-Dashboard unter Admin → API Keys (/admin/api-keys). Keys sind gescoped (chat:completions), können ein eigenes Rate-Limit pro Key tragen und jederzeit widerrufen werden. Der Klartext-Key wird nur einmal bei der Erstellung angezeigt — bewahren Sie ihn sicher auf.

4. Modelle auflisten — GET /v1/models

Listet die Modelle auf, die die Box bereitstellt. Die meisten SDKs und IDE-Erweiterungen rufen diesen Endpoint beim Einrichten auf, um den Key zu validieren und die Modellauswahl zu befüllen.

curl https://<your-box>/api/v1/models \
  -H "Authorization: Bearer $BRANE_KEY"

{
  "object": "list",
  "data": [
    { "id": "vllm:gemma-4-26b-awq", "object": "model", "created": 1750000000, "owned_by": "local" },
    { "id": "openrouter:anthropic/claude-sonnet-4.5", "object": "model", "created": 1750000000, "owned_by": "openrouter" }
  ]
}

Die sichtbare Menge respektiert den Admin-ZDR-Filter und die OpenRouter-Allowlist — ein Key sieht nie ein Modell, an das die Box ohnehin nicht routen würde. owned_by: "local" kennzeichnet lokale vLLM-Modelle.

5. Chat Completions — POST /v1/chat/completions

Standard OpenAI Chat Completions. Unterstützt messages, stream, temperature, max_tokens, top_p sowie Content-Parts vom Typ Text und image_url.

curl https://<your-box>/api/v1/chat/completions \
  -H "Authorization: Bearer $BRANE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vllm:gemma-4-26b-awq",
    "messages": [{ "role": "user", "content": "Refactor this function: ..." }],
    "stream": true
  }'

Streaming liefert Server-Sent Events im Format chat.completion.chunk, abgeschlossen durch data: [DONE]. Ohne Streaming erhalten Sie ein einzelnes chat.completion-Objekt mit usage.

6. Souveränitäts-Verhalten

1. Das model-Feld ist ein Wunsch

Der Guardian entscheidet den tatsächlichen Provider anhand des Routing-Modus der Box (local-only, local-preferred, …) und des Inhalts der Anfrage. Wenn Sie ein Cloud-Modell anfordern, das Routing die Anfrage aber lokal hält (z. B. weil sensibler Inhalt erkannt wurde), erhalten Sie das lokale Modell. Das model-Feld in der Antwort spiegelt wider, was tatsächlich ausgeführt wurde.

2. PII wird vor der Cloud redigiert

Wenn der Guardian an ein Cloud-Modell routet und die PII-Policy anonymize lautet, werden personenbezogene Daten durch Tokens ersetzt (<PERSON_1>, <EMAIL_1>), bevor die Anfrage die Box verlässt, und in der Antwort wiederhergestellt. Das Cloud-Modell sieht nie echte Daten. Im Modus local-only verlässt gar nichts die Box — es ist keine Redaktion nötig.

7. IDE-Integration

Continue.dev (VS Code / JetBrains)

~/.continue/config.json:

{
  "models": [
    {
      "title": "Brane AIF (sovereign)",
      "provider": "openai",
      "model": "vllm:gemma-4-26b-awq",
      "apiBase": "https://<your-box>/api/v1",
      "apiKey": "brn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  ]
}

provider: "openai" plus eine eigene apiBase richten Continue auf die Box aus. Chat, Erklären und Refactoring funktionieren bereits heute.

Cline / Roo

Wählen Sie den Provider „OpenAI Compatible“, setzen Sie die Base URL auf https://<your-box>/api/v1 und fügen Sie den Key ein.

8. Aktuelle Einschränkungen

Ehrlicher Umfang dessen, was das Gateway noch nicht leistet:

Funktion	Status
Chat (fragen, erklären, refactoren)	verfügbar
GET /v1/models Discovery	verfügbar
Tool- / Function-Calling (tools, tool_calls)	noch nicht — erforderlich für agentisches Coding (Cline Agent Mode, Continue Agent)
Inline-Autocomplete (FIM /v1/completions)	noch nicht
Embeddings (/v1/embeddings, @codebase)	noch nicht
Streaming usage / stream_options	wird nicht ausgegeben
max_completion_tokens (neueres SDK-Feld)	bitte max_tokens verwenden

9. Fehler

OpenAI-typischer Fehler-Envelope:

{ "error": { "message": "Invalid API Key", "type": "auth_error" } }

Status	type	Ursache
400	invalid_request_error	Fehlerhafter Body / fehlerhafte bekannte Felder (unbekannte Top-Level-Felder werden stillschweigend ignoriert)
401	auth_error	Key fehlt oder ist ungültig
403	auth_error	Key fehlt der Scope chat:completions
403	user_disabled	Nutzer wurde deaktiviert
429	rate_limit_error	Rate-Limit pro Key oder am Gateway überschritten (Retry-After: 60)
500	server_error	Interner Fehler (Details werden serverseitig geloggt, nie zurückgegeben)

Fragen zur Integration?

Unser Team unterstützt Sie bei der Anbindung Ihrer Werkzeuge.

Support kontaktieren