Entwickeln / Referenz

Chat Completions

Erzeugt eine Modellantwort im OpenAI-Chat-Format und maskiert die Nachrichten, wenn die Maskierung für die Anfrage aktiv ist.

POST /v1/chat/completions
Familie
chat
Maskierung
ja
Streaming
ja, SSE
Format
JSON
Abrechnung
Tokens

Anfrage

Das Gateway nimmt den Body im Format der OpenAI Chat Completions API an. Die Basis-URL ist https://api.noirdoc.de/v1.

model ist Pflicht. Setzen Sie eine Modell-ID aus GET /v1/models ein. Das Modell muss zur Familie chat gehören und bei einem Anbieter im OpenAI-Format laufen.

Den Schlüssel senden Sie als Authorization: Bearer px-.... Die anderen Header-Formen stehen unter Authentifizierung & Header.

Das Beispiel schaltet die Maskierung mit X-Noirdoc-Mask: on für diese eine Anfrage ein. Ob der Header wirkt, legt die Maskierungsrichtlinie Ihrer Organisation fest (siehe Maskierung einschalten).

Shell
curl https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Mask: on" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [
      {
        "role": "user",
        "content": "Was schreibt Herr Müller der Kanzlei?"
      }
    ]
  }'
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.chat.completions.create(
    model="qwen3.8-27b",
    messages=[
        {
            "role": "user",
            "content": "Was schreibt Herr Müller der Kanzlei?",
        }
    ],
    # Maskierung für diese Anfrage einschalten
    extra_headers={"X-Noirdoc-Mask": "on"},
)
print(response.choices[0].message.content)
TypeScript
import OpenAI from "openai";

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

const response = await client.chat.completions.create(
  {
    model: "qwen3.8-27b",
    messages: [
      {
        role: "user",
        content: "Was schreibt Herr Müller der Kanzlei?",
      },
    ],
  },
  // Maskierung für diese Anfrage einschalten
  { headers: { "X-Noirdoc-Mask": "on" } },
);
console.log(response.choices[0].message.content);

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.
AnbieterDas Gateway wählt den Anbieter. Der Header X-Noirdoc-Provider in der Antwort nennt ihn, auch bei einem Fehler des Anbieters. Die Reihenfolge beschreibt Anbieter & Routing.
FailoverAntwortet ein Anbieter mit 429 oder 5xx oder ist er nicht erreichbar, bevor die Antwort beginnt, versucht das Gateway den nächsten Anbieter für dasselbe Modell, höchstens drei Anbieter pro Anfrage. Eigene Anbieter (BYOK) und von Noirdoc verwaltete Anbieter mischt es dabei nicht.
MaskierungIst die Maskierung aktiv, ersetzt das Gateway personenbezogene Daten in messages durch Platzhalter wie <<PERSON_1>>. In der Antwort stellt es die Originalwerte wieder her, auch im Stream. Die Felder listet Maskierte Felder.
SystemnachrichtHat das Gateway Platzhalter gesetzt, stellt es eine Systemnachricht an den Anfang von messages. Sie weist das Modell an, die Platzhalter wie echte Werte zu behandeln.
StreamingBei "stream": true setzt das Gateway stream_options.include_usage, um die Tokens abzurechnen. Haben Sie das nicht selbst angefordert, entfernt es das zusätzliche Event mit den Nutzungsdaten aus dem Stream.
Dateien und BilderTeile vom Typ image_url, file und input_audio in messages sind nur erlaubt, wenn Admins Ihrer Organisation unter Models → Datenschutz die Option Dateiinhalte zulassen eingeschaltet haben. Details: Dateien.
Datei-VerweiseBei von Noirdoc verwalteten Anbietern muss eine file_id in einem file-Teil über Ihre Organisation hochgeladen worden sein. Sonst antwortet das Gateway mit 404 object_not_found.
HeaderDas Gateway entfernt Ihren Schlüssel und X-Noirdoc-Mask, bevor es die Anfrage weiterleitet.
Fehler des AnbietersStatuscode und Body eines Anbieterfehlers reicht das Gateway unverändert durch. Eigene Fehler des Gateways erkennen Sie an "type": "proxy_error".

Unterrouten

MethodePfadZweck
POST/v1/chat/completionsAntwort erzeugen
GET/v1/chat/completionsgespeicherte Chat Completions auflisten
GET/v1/chat/completions/{id}eine gespeicherte Chat Completion abrufen
DELETE/v1/chat/completions/{id}eine gespeicherte Chat Completion löschen
GET/v1/chat/completions/{id}/messagesdie Nachrichten einer gespeicherten Chat Completion abrufen

Die Unterrouten für gespeicherte Chat Completions ("store": true) funktionieren nur mit einem eigenen Anbieter-Schlüssel (BYOK). Das Gateway leitet sie an den ältesten aktiven Anbieter im OpenAI-Format weiter, den Ihre Organisation selbst verbunden hat. Ohne eigenen Anbieter antwortet es mit 403 endpoint_not_available_on_platform, weil sich alle Organisationen die Anbieter-Konten von Noirdoc teilen. Ist gar kein Anbieter im OpenAI-Format verfügbar, antwortet es mit 502 provider_not_configured.

Beim Abrufen stellt das Gateway keine Originalwerte wieder her. War die ursprüngliche Anfrage maskiert, enthält die abgerufene Chat Completion die Platzhalter.

Andere Pfade unter /v1/chat/completions/ 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.
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.
403endpoint_not_available_on_platformDer Aufruf würde Daten aus dem gemeinsamen Konto eines von Noirdoc verwalteten Anbieters lesen und ist dort gesperrt.
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.
403file_content_not_allowedDie Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu.
403file_pii_blockedEine Datei enthält personenbezogene Daten, und der Dateianalyse-Modus der Organisation ist block.
404object_not_foundDas Objekt (Datei, Skill oder gespeicherte Antwort) existiert nicht oder gehört nicht Ihrer Organisation.
404model_not_availableDie Modell-ID ist für die Organisation nicht verfügbar.
422file_unprocessableEine Datei ließ sich für die Prüfung nicht verarbeiten: Sie ist zu groß, nicht lesbar oder hat ein Format ohne Analyse. Das Gateway hat die Anfrage nicht weitergeleitet.
500detection_errorDie Erkennung personenbezogener Daten ist fehlgeschlagen; das Gateway hat die Anfrage nicht weitergeleitet.
502provider_not_configuredFür diese Anfrage ist in der Organisation kein passender Anbieter eingerichtet.
502provider_unreachableDas Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
503ownership_check_unavailableDas Gateway konnte gerade nicht prüfen, ob das Objekt Ihrer Organisation gehört, und hat die Anfrage abgelehnt.
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: Chat Completions (geprüft am 30.09.2026).