Skip to main content
Die Localmind API stellt eine OpenAI-kompatible Oberfläche bereit. Eine bestehende OpenAI-SDK-Codebasis stellen Sie mit drei Änderungen auf Localmind um: base_url auf Ihre Instanz, api_key auf Ihren persönlichen API-Key und model auf eine Agent-UUID statt eines Modellnamens. 
from openai import OpenAI

client = OpenAI(
    base_url="https://<deine-instanz>-api.localmind.ai/v1",  # Staging: https://v3-api.localmind.dev/v1
    api_key="sk-…",
)
In Localmind wählt der model-Parameter keinen Modellnamen wie gpt-4, sondern einen Agent über dessen UUID. Welches Sprachmodell der Agent nutzt, ist in der Library am Agent hinterlegt und läuft hinter einem LiteLLM-Proxy. Die UUIDs der für Sie zugänglichen Agenten liefert GET /v1/models.

​
GET /v1/models

Listet alle Agenten, auf die Ihr API-Key Zugriff hat (nicht gelöscht, keine System-Agenten), im OpenAI-/models-Format. Das Feld name spart einen zusätzlichen Lookup; owned_by ist die Org-ID.
​
Authorization
string
required
Bearer sk-… — Ihr persönlicher API-Key.
curl "https://<deine-instanz>-api.localmind.ai/v1/models" \
  -H "Authorization: Bearer sk-…"

{
  "object": "list",
  "data": [
    {
      "id": "{agent_id}",
      "name": "Bürgerservice Assistent",
      "object": "model",
      "created": 1781346834,
      "owned_by": "{org_id}"
    }
  ]
}
​
object
string
Immer "list".
​
data
array
Die zugänglichen Agenten. Jeder Eintrag hat die folgenden Felder.
​
data[].id
string
Die Agent-UUID. Diesen Wert verwenden Sie als model in POST /v1/chat/completions.
​
data[].name
string
Anzeigename des Agents (nur zur Lesbarkeit, nicht zum Routing).
​
data[].object
string
Immer "model".
​
data[].created
integer
Erstellungszeitpunkt als Unix-Timestamp.
​
data[].owned_by
string
Die Organisation, der der Agent gehört (Org-ID).
Die Liste ist auf das verengt, was Ihr Key erreicht: Ein Key mit dem Scope „ausgewählte Spaces” zeigt nur Agenten aus diesen Spaces. Wie der Key Rollen und Spaces einschränkt, beschreibt Authentifizierung und Rollen.

​
POST /v1/chat/completions

OpenAI-kompatibler Chat-Endpunkt — stateless und single-shot: Es gibt keinen serverseitigen Conversation-State. Den bisherigen Verlauf senden Sie bei jedem Aufruf vollständig im messages-Array mit.
​
Authorization
string
required
Bearer sk-… — Ihr persönlicher API-Key.
​
model
string
required
Die Agent-UUID aus GET /v1/models. Kein Modellname-Routing. Eine unbekannte UUID liefert 404 {"detail":"Model '…' not found"}.
​
messages
array
required
Die Nachrichten der Konversation. Jede Nachricht hat ein role (system, user oder assistant) und ein content.
​
stream
boolean
default:"false"
Bei true wird die Antwort als Server-Sent-Events (SSE) gestreamt.
​
temperature
number
Überschreibt den am Agent hinterlegten Default.
​
max_tokens
integer
Maximale Anzahl generierter Tokens; überschreibt den Agent-Default. Das Alias max_completion_tokens wird ebenfalls akzeptiert.
​
response_format
object
JSON-Mode über {"type": "json_object"}. Wird via LiteLLM an das Modell durchgereicht — die strikte Gültigkeit ist modellabhängig und wird nicht hart erzwungen.
​
stream_options
object
Mit {"include_usage": true} enthält der Stream am Ende einen zusätzlichen Chunk mit den Usage-Zahlen.
Die Parameter top_p, stop, presence_penalty, frequency_penalty, seed, n und logit_bias werden akzeptiert, aber ignoriert — sie lösen keinen 422-Fehler aus, haben aber keine Wirkung.

​
Hinweise zum Verhalten

  • Tools laufen intern. Ruft der Agent ein Tool auf (z. B. Hybrid Search über seine Wissensquellen), geschieht das serverseitig. Im Response ist tool_calls deshalb immer null — es gibt keine function_call-Ausgabe.
  • Kein Conversation-State. Der Endpunkt persistiert nichts. Für mehrstufige Chats senden Sie den Verlauf im messages-Array mit. Siehe auch Agenten.
curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "{agent_id}",
    "messages": [
      {"role": "user", "content": "Wie beantrage ich einen Reisepass?"}
    ],
    "stream": false,
    "temperature": 0.7,
    "max_tokens": 2048
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1781435623,
  "model": "{agent_id}",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Einen Reisepass beantragen Sie …",
        "tool_calls": null,
        "refusal": null
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 3787,
    "completion_tokens": 6,
    "total_tokens": 3793
  },
  "system_fingerprint": null,
  "service_tier": null
}
​
id
string
Eindeutige ID der Antwort (chatcmpl-…).
​
object
string
Immer "chat.completion" (nicht-gestreamt).
​
model
string
Die angefragte Agent-UUID.
​
choices
array
Die generierten Antworten. choices[0].message.content enthält den Text des Agents; tool_calls ist immer null; finish_reason ist typischerweise "stop".
​
usage
object
Token-Verbrauch mit prompt_tokens, completion_tokens und total_tokens.

​
Streaming

Mit "stream": true antwortet der Endpunkt als Server-Sent-Events. Jede Zeile beginnt mit data: und enthält ein chat.completion.chunk-Objekt; der jeweilige Text-Teil steht in choices[0].delta. Mit stream_options.include_usage folgt am Ende ein Chunk mit den Usage-Zahlen. Den Abschluss markiert die Zeile data: [DONE].
Stream (gekürzt)
data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}],"usage":null}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Einen "}}],"usage":null}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Reisepass …"}}],"usage":null}

data: {"object":"chat.completion.chunk","choices":[{"delta":{}}],"usage":{"prompt_tokens":3787,"completion_tokens":6,"total_tokens":3793}}

data: [DONE]

​
Fehler

{ "detail": "Model '{agent_id}' not found" }
Eine unbekannte oder nicht zugängliche model-UUID liefert 404. Listen Sie die gültigen Agenten erneut mit GET /v1/models. Alle Statuscodes und das Fehlermodell beschreibt Konventionen und Fehler.

​
Verwandte Seiten

Quickstart

Key erstellen, Agenten auflisten und die erste Anfrage senden.

Agenten

Agenten programmatisch finden und ihre vollständige Konfiguration lesen.

Use Cases

Fertige Rezepte: OpenAI-Drop-in, RAG, Chatbot, n8n.

Authentifizierung und Rollen

Wie Ihr Key Rollen erbt, an die Org gebunden ist und den Zugriff verengt.