Entwickeln / Referenz
Chat Completions
Erzeugt eine Modellantwort im OpenAI-Chat-Format und maskiert die Nachrichten, wenn die Maskierung für die Anfrage aktiv ist.
/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).
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?"
}
]
}'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)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
| Bereich | Verhalten |
|---|---|
| Modell | Das 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. |
| Anbieter | Das 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. |
| Failover | Antwortet 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. |
| Maskierung | Ist 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. |
| Systemnachricht | Hat 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. |
| Streaming | Bei "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 Bilder | Teile 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-Verweise | Bei 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. |
| Header | Das Gateway entfernt Ihren Schlüssel und X-Noirdoc-Mask, bevor es die Anfrage weiterleitet. |
| Fehler des Anbieters | Statuscode und Body eines Anbieterfehlers reicht das Gateway unverändert durch. Eigene Fehler des Gateways erkennen Sie an "type": "proxy_error". |
Unterrouten
| Methode | Pfad | Zweck |
|---|---|---|
POST | /v1/chat/completions | Antwort erzeugen |
GET | /v1/chat/completions | gespeicherte 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}/messages | die 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
| Status | Code | Bedeutung |
|---|---|---|
| 400 | model_required | Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld). |
| 400 | wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. |
| 400 | invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. |
| 402 | insufficient_credit | Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage. |
| 402 | key_budget_exhausted | Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus. |
| 403 | endpoint_not_available_on_platform | Der Aufruf würde Daten aus dem gemeinsamen Konto eines von Noirdoc verwalteten Anbieters lesen und ist dort gesperrt. |
| 403 | model_not_allowed_for_key | Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels. |
| 403 | provider_not_allowed_for_tenant | Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet. |
| 403 | provider_not_allowed_for_key | Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. |
| 403 | file_content_not_allowed | Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu. |
| 403 | file_pii_blocked | Eine Datei enthält personenbezogene Daten, und der Dateianalyse-Modus der Organisation ist block. |
| 404 | object_not_found | Das Objekt (Datei, Skill oder gespeicherte Antwort) existiert nicht oder gehört nicht Ihrer Organisation. |
| 404 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 422 | file_unprocessable | Eine 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. |
| 500 | detection_error | Die Erkennung personenbezogener Daten ist fehlgeschlagen; das Gateway hat die Anfrage nicht weitergeleitet. |
| 502 | provider_not_configured | Für diese Anfrage ist in der Organisation kein passender Anbieter eingerichtet. |
| 502 | provider_unreachable | Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen. |
| 503 | ownership_check_unavailable | Das Gateway konnte gerade nicht prüfen, ob das Objekt Ihrer Organisation gehört, und hat die Anfrage abgelehnt. |
| 504 | provider_timeout | Der 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).