Entwickeln / Referenz

Embeddings

Erzeugt Vektor-Embeddings im OpenAI-Format; der Eingabetext erreicht den Anbieter unmaskiert.

POST /v1/embeddings
Familie
embeddings
Maskierung
nein
Streaming
nein
Format
JSON
Abrechnung
Tokens (Eingabe)

Anfrage

Das Gateway nimmt den Body im Format der OpenAI Embeddings API an. model ist Pflicht und muss ein Modell der Familie embeddings aus GET /v1/models sein. Ein Chat-Modell auf diesem Endpunkt beantwortet das Gateway mit 400 wrong_endpoint_for_model, ebenso ein Embedding-Modell auf einem Chat-Endpunkt.

Weitere Felder wie encoding_format oder dimensions leitet das Gateway an den Anbieter weiter. Ob das Modell sie unterstützt, entscheidet der Anbieter.

Shell
curl https://api.noirdoc.de/v1/embeddings \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-m3",
    "input": [
      "Die Kündigungsfrist beträgt drei Monate.",
      "Der Vertrag endet zum Quartalsende."
    ]
  }'
Python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noirdoc.de/v1",
    api_key=os.environ["NOIRDOC_API_KEY"],
)

response = client.embeddings.create(
    model="BAAI/bge-m3",
    input=[
        "Die Kündigungsfrist beträgt drei Monate.",
        "Der Vertrag endet zum Quartalsende.",
    ],
)
print(len(response.data[0].embedding))
TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.noirdoc.de/v1",
  apiKey: process.env.NOIRDOC_API_KEY,
});

const input: string[] = [
  "Die Kündigungsfrist beträgt drei Monate.",
  "Der Vertrag endet zum Quartalsende.",
];

const response = await client.embeddings.create({
  model: "BAAI/bge-m3",
  input,
});
console.log(response.data[0].embedding.length);

Was Noirdoc ändert

BereichVerhalten
ModellDas Gateway löst die Modell-ID über den Katalog auf und sendet dem Anbieter dessen eigenen Modellnamen. Nennt die Antwort im Feld model diesen Namen, setzt das Gateway dort wieder die ID ein, die Sie gesendet haben.
AnbieterDer Header X-Noirdoc-Provider in der Antwort nennt den Anbieter. Siehe Anbieter & Routing.
MaskierungKeine. Senden Sie X-Noirdoc-Mask: on, lehnt das Gateway die Anfrage mit 403 masking_not_supported_for_endpoint ab, statt sie unmaskiert weiterzuleiten. Mit der Maskierungsrichtlinie enforced lehnt es jede Anfrage auf diesem Endpunkt so ab. Mit default_on und default_off leitet es Anfragen ohne diesen Header unmaskiert weiter.
StreamingKeines. "stream": true beantwortet das Gateway mit 400 streaming_not_supported_for_endpoint.
AbrechnungDas Gateway rechnet die Eingabe-Tokens aus usage ab. Meldet der Anbieter keine Nutzung, schätzt es die Eingabe-Tokens aus dem Body.
HeaderDas Gateway entfernt Ihren Schlüssel und X-Noirdoc-Mask, bevor es die Anfrage weiterleitet.

Unterrouten

Keine. Andere Pfade unter /v1/embeddings/ beantwortet das Gateway mit 404 unsupported_endpoint.

Fehler auf diesem Endpunkt

StatusCodeBedeutung
400model_requiredDie Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld).
400wrong_endpoint_for_modelDas Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt.
400streaming_not_supported_for_endpointDie Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht.
400invalid_request_bodyDer Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert.
402insufficient_creditDas Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage.
402key_budget_exhaustedDas Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus.
403model_not_allowed_for_keyDas Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels.
403provider_not_allowed_for_tenantDie Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet.
403provider_not_allowed_for_keyDie Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus.
403masking_not_supported_for_endpointDer Endpunkt kann nicht maskieren, aber die Maskierungsrichtlinie ist enforced oder die Anfrage sendet X-Noirdoc-Mask: on.
404model_not_availableDie Modell-ID ist für die Organisation nicht verfügbar.
502provider_unreachableDas Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
504provider_timeoutDer Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet.

OpenAI-Referenz

Alle übrigen Felder von Anfrage und Antwort beschreibt die API-Referenz von OpenAI: Embeddings (geprüft am 30.09.2026).