API: Embeddings

OpenAI-kompatibler Embeddings-Endpunkt der Kasimir Public API für 1024-dimensionale Vektor-Embeddings.

Der Embeddings-Endpunkt der Kasimir Public API wandelt Text in numerische Vektor-Embeddings um, die du für semantische Suche, Clustering, Klassifikation oder eigene RAG-Pipelines verwenden kannst. Die Schnittstelle ist wire-kompatibel zur OpenAI Embeddings API: Du kannst das offizielle OpenAI Python SDK (oder jeden OpenAI-kompatiblen Client) unverändert verwenden und lediglich base_url und api_key auf Kasimir umstellen. Intern wird die Anfrage durch den DSGVO-konformen LiteLLM-Proxy an das eingebundene Embedding-Modell weitergeleitet, mit Mandanten-Governance (Modell-Freigabe, EU-Gate) und Verbrauchsabrechnung pro Aufruf.

Endpunkt

Authentifizierung

Alle Aufrufe werden über einen Firmen-API-Key authentifiziert, der im Header Authorization: Bearer <key> mitgesendet wird.

• Keys werden von Workspace-Inhabern oder -Admins unter Verwaltung → Zugriff (/administration/access) erzeugt.

• Das Format ist kasi_ gefolgt von 32 Zeichen (z. B. kasi_a3f9k2m7q4t6w8x1c5v9b2n4z6s8d0f2). Der Klartext wird nur einmal bei der Erstellung angezeigt — danach speichert Kasimir lediglich einen SHA-256-Hash.

• Neue Keys erhalten standardmäßig die Scopes chat:read und chat:write. Für Embeddings ist chat:write zwingend erforderlich.

• Widerrufene Keys (revoked_at gesetzt) werden mit 401 abgewiesen.

Request

Header

Body-Parameter

Response

Die Antwort entspricht dem OpenAI-Embeddings-Schema. Das Feld model in der Antwort enthält den Kasimir-Slug (nicht die interne Upstream-Modell-ID).

Jedes Element in data:

Beispiele

curl — einzelner Text

curl https://kasimir.ai/api/v1/embeddings \
  -H "Authorization: Bearer kasi_DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "self-hosted-bge-m3",
    "input": "Die DSGVO regelt den Umgang mit personenbezogenen Daten."
  }'

curl — Batch (mehrere Texte)

curl https://kasimir.ai/api/v1/embeddings \
  -H "Authorization: Bearer kasi_DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "self-hosted-bge-m3",
    "input": [
      "Erster Absatz zum Embedden.",
      "Zweiter Absatz zum Embedden."
    ]
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://kasimir.ai/api/v1",
    api_key="kasi_DEIN_API_KEY",
)

resp = client.embeddings.create(
    model="self-hosted-bge-m3",
    input="Die DSGVO regelt den Umgang mit personenbezogenen Daten.",
)

vector = resp.data[0].embedding
print(len(vector))   # 1024
print(resp.usage.prompt_tokens)

Batch mit dem Python SDK

texts = [
    "Erster Absatz zum Embedden.",
    "Zweiter Absatz zum Embedden.",
]

resp = client.embeddings.create(model="self-hosted-bge-m3", input=texts)

for item in resp.data:
    print(item.index, len(item.embedding))

Beispiel-Antwort

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789, "...weitere 1021 Werte..."]
    }
  ],
  "model": "self-hosted-bge-m3",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

Modelle auflisten

Welche Slugs für deinen Workspace freigegeben sind, ermittelst du über den Modell-Endpunkt. Er gibt Chat- und Embedding-Modelle zurück (gefiltert nach Mandanten-Freigabe und EU-Gate):

curl https://kasimir.ai/api/v1/models \
  -H "Authorization: Bearer kasi_DEIN_API_KEY"

client.models.list()

Fehler

Fehler werden im OpenAI-Fehlerformat zurückgegeben, damit Standard-SDKs sie normal behandeln:

{
  "error": {
    "message": "Missing scope: chat:write",
    "type": "permission_error",
    "code": null
  }
}

Der HTTP-Statuscode bestimmt das type-Feld:

Governance & Abrechnung

• Modell-Freigabe: Es gelten dieselben Regeln wie im In-App-Modell-Picker — Workspace-Scope, active, Verwendungszweck embedding, die Deny-Liste disabled_model_slugs sowie das EU/Nicht-EU-Gate (allow_non_eu_models).

• EU-Gate: Nicht-EU-Modelle (eu_hosted = false) werden mit 403 abgelehnt, solange der Workspace sie nicht ausdrücklich freigeschaltet hat. Das Standard-Embedding-Modell ist EU-gehostet.

• Metering: Jeder erfolgreiche Aufruf wird im Verbrauchs-Ledger (api_usage) erfasst — mit prompt_tokens aus der Upstream-Antwort und den EUR-Kosten gemäß den Modell-Raten. Das Metering ist „best-effort" und blockiert die Antwort nie.