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-nvfp4", "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. owned_by: "local" kennzeichnet lokale vLLM-Modelle. Hinweis: Der Routing-Modus wird hier nicht angewendet — im Modus local-only können Cloud-Modelle gelistet sein, obwohl jede Anfrage lokal ausgeführt wird.

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

Standard OpenAI Chat Completions. Unterstützt messages und stream mit Text-Content. temperature, max_tokens und top_p werden akzeptiert, aber derzeit nicht an das Modell weitergereicht; Bild-Eingaben (image_url) sind noch nicht verfügbar (beides Roadmap).

curl https://<your-box>/api/v1/chat/completions \
  -H "Authorization: Bearer $BRANE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vllm:gemma-4-26b-nvfp4",
    "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. Das usage-Feld verwendet derzeit die Feldnamen des Vercel AI SDK (inputTokens/outputTokens), nicht das OpenAI-Format (prompt_tokens/completion_tokens).

6. Souveränitäts-Verhalten

1. Das model-Feld ist rein informativ

Der Guardian wählt das tatsächliche Modell allein anhand des Routing-Modus der Box (local-only, local-preferred, …) und des Inhalts der Anfrage: lokal das konfigurierte Box-Modell, in der Cloud das vom Admin konfigurierte Cloud-Modell. Ihr angefordertes Modell wird nicht direkt angesteuert — auch dann nicht, wenn das Routing in die Cloud geht. Das model-Feld in der Antwort nennt das tatsächlich ausgeführte Modell; über x_brane.model_requested bzw. die X-Brane-Overridden-Header erkennen Sie eine Abweichung.

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-nvfp4",
      "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:

9. Fehler

OpenAI-typischer Fehler-Envelope:

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

Fragen zur Integration?

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

Support kontaktieren