OpenAI & Anthropic SDK.
Richte die offiziellen Python- und TypeScript-SDKs auf das Gateway, lies Antwort-Header aus, empfange Server-Sent Events ohne Pufferung und behandle Gateway-Fehler.
OpenAI-SDK.
Installiere openai (pip install openai bzw. npm install openai) und zeige mit base_url (https://api.noirdoc.de/v1) sowie api_key auf deinen px--Schlüssel; alternativ lesen beide SDKs OPENAI_BASE_URL und OPENAI_API_KEY ohne Code-Änderung aus der Umgebung. Der Client deckt Chat Completions, client.responses.create (POST /v1/responses), client.embeddings.create (POST /v1/embeddings), Audio, Bilder und Dateien ab. Antwort-Header wie X-Noirdoc-Provider und X-Noirdoc-Shield liest du über with_raw_response (Python) bzw. .withResponse() (TypeScript).
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
default_headers={"X-Noirdoc-Shield": "on"},
)
# Antwort-Header lesen und Shield pro Anfrage übersteuern
raw = client.chat.completions.with_raw_response.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Prüfe § 4 auf Fristen."}],
extra_headers={"X-Noirdoc-Shield": "off"},
)
print(raw.headers.get("x-noirdoc-provider"))
res = raw.parse()import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
defaultHeaders: { "X-Noirdoc-Shield": "on" },
});
// Antwort-Header lesen und Shield pro Anfrage übersteuern
const { data, response } = await client.chat.completions
.create(
{
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Prüfe § 4 auf Fristen." }],
},
{ headers: { "X-Noirdoc-Shield": "off" } },
)
.withResponse();
console.log(response.headers.get("x-noirdoc-provider"));X-Noirdoc-Mask bleibt als kompatibler Alias für X-Noirdoc-Shield erhalten. Ob der Header greift, bestimmt die fünfstufige Shield-Vorrangfolge.
Endpunkte ohne Shield:
/v1/images/generationslehntX-Noirdoc-Shield: on(undX-Noirdoc-Mask: on) mit Status403(masking_not_supported_for_endpoint) ab;/v1/audio/*und/v1/fileslehnenenforcedsowieX-Noirdoc-Mask: onab und leiten sonstige Anfragen ungeprüft weiter. Verwende für die Bildgenerierung einen eigenen Client ohnedefault_headers.
Anthropic-SDK.
Installiere anthropic (pip install anthropic) oder @anthropic-ai/sdk (npm install @anthropic-ai/sdk) und setze base_url auf https://api.noirdoc.de ohne /v1, da das SDK /v1/messages selbst anhängt. Übergib den px--Schlüssel als auth_token (Authorization: Bearer) oder api_key (x-api-key) bzw. über ANTHROPIC_BASE_URL und genau eine der Variablen ANTHROPIC_AUTH_TOKEN oder ANTHROPIC_API_KEY (nicht beide gleichzeitig, sonst sendet das SDK beide Header).
import os
from anthropic import Anthropic
anthropic_client = Anthropic(
base_url="https://api.noirdoc.de",
auth_token=os.environ["NOIRDOC_API_KEY"],
default_headers={"X-Noirdoc-Shield": "on"},
)
count = anthropic_client.messages.count_tokens(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "Prüfe § 4 auf Fristen."}],
)
msg = anthropic_client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Prüfe § 4 auf Fristen."}],
)
print(count.input_tokens, msg.content[0].text)import Anthropic from "@anthropic-ai/sdk";
const anthropicClient = new Anthropic({
baseURL: "https://api.noirdoc.de",
authToken: process.env.NOIRDOC_API_KEY,
defaultHeaders: { "X-Noirdoc-Shield": "on" },
});
const count = await anthropicClient.messages.countTokens({
model: "claude-sonnet-5-5",
messages: [{ role: "user", content: "Prüfe § 4 auf Fristen." }],
});
const msg = await anthropicClient.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Prüfe § 4 auf Fristen." }],
});
console.log(count.input_tokens, msg.content);POST /v1/messages akzeptiert Claude-Modelle über Google Vertex AI aus GET /v1/models sowie eigene Anthropic-kompatible BYOK-Anbieter (OpenAI-Modelle liefern 400 wrong_endpoint_for_model). POST /v1/messages/count_tokens überspringt Shield und kostet 0 €.
Streaming (SSE).
Mit "stream": true liefern POST /v1/chat/completions, POST /v1/responses und POST /v1/messages Server-Sent Events (SSE) im Originalformat des Anbieters. Alle anderen Endpunkte (/v1/embeddings, /v1/rerank, /v1/audio/transcriptions inkl. Formularfeld stream, /v1/audio/speech inkl. stream_format, /v1/images/generations) lehnen Streaming mit Status 400 (streaming_not_supported_for_endpoint) ab; auf Endpunkten ohne Shield hat Status 403 (masking_not_supported_for_endpoint) Vorrang, wenn enforced oder X-Noirdoc-Mask: on (auf /v1/images/generations auch X-Noirdoc-Shield: on) aktiv ist.
# OpenAI-SDK: POST /v1/chat/completions
stream = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Schreibe ein Anschreiben."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
# Anthropic-SDK: POST /v1/messages
with anthropic_client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Schreibe ein Anschreiben."}],
) as s:
for text in s.text_stream:
print(text, end="", flush=True)// OpenAI-SDK: POST /v1/chat/completions
const stream = await client.chat.completions.create({
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Schreibe ein Anschreiben." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
// Anthropic-SDK: POST /v1/messages
const msgStream = anthropicClient.messages.stream({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Schreibe ein Anschreiben." }],
});
msgStream.on("text", (t) => process.stdout.write(t));
await msgStream.finalMessage();curl -N https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"stream": true,
"messages": [
{"role": "user", "content": "Schreibe ein Anschreiben."}
]
}'| Verhalten | Regel im Noirdoc-Gateway |
|---|---|
| Shield-Prüfung ohne Pufferung | Noirdoc Shield prüft nur die Anfrage vorab (block-Treffer liefern vor Stream-Start 403 shield_violation) und reicht jedes SSE-Chunk samt Tool-Aufrufen sofort ungepuffert durch. Bestandsorganisationen mit klassischer Maskierung bis 2026-11-30 erhalten bei <<TYP_N>>-Platzhaltern weiterhin satzweise gepufferte Events (max. 2.000 Zeichen, Tool-Argumente nach Abschluss) mit Deprecation: true und Sunset. |
stream_options.include_usage | Auf POST /v1/chat/completions aktiviert das Gateway stream_options.include_usage intern für die Abrechnung und entfernt das zusätzliche Nutzungs-Event wieder, sofern deine Anfrage die Option nicht selbst gesetzt hat. |
Keep-Alive (: ping) & Anbieter-Kommentar | Antwortet der Anbieter nicht binnen 15 s mit Headern, sendet das Gateway Status 200 und alle 15 s die Kommentarzeile : ping (SDKs und eventsource-parser ignorieren :; überspringe :-Zeilen in eigenen Parsern). Wurde 200 vorab gesendet, entfällt der HTTP-Header X-Noirdoc-Provider und erscheint stattdessen als : provider=<slug> direkt vor dem ersten Daten-Event. |
| Zeitlimits | Streams ("stream": true) warten über alle Failover-Versuche insgesamt höchstens 600 Sekunden; Anfragen ohne Streaming behalten das Limit von 120 Sekunden. |
| Failover vor dem ersten Byte | Vor dem ersten Antwort-Byte wechselt das Gateway bei Netzwerkfehlern, 401, 402, 429 und 5xx automatisch zum nächsten Anbieter (Failover), auch wenn bereits : ping-Kommentarzeilen gesendet wurden. Scheitern alle Anbieter vor Status 200, kommt ein regulärer HTTP-JSON-Fehler zurück. |
| Fehler im offenen Stream | Nach Stream-Beginn bleibt der Anbieter fest: Abbrüche liefern stream_interrupted, Fehler nach vorab gesendetem 200 ihren regulären code (samt retry_after in Sekunden im Fehlerobjekt) und laufende Deployments beim Warten auf den Anbieter gateway_restarting mit retry_after: 5. Format: /v1/chat/completions sendet data: {"error": {...}} + data: [DONE] (löst APIError aus); /v1/responses sendet event: error + data: [DONE] (im OpenAI-Python-SDK flaches Event mit type: "error" ohne Ausnahme: in der Schleife prüfen); /v1/messages sendet event: error + message_stop. |
Fehlerbehandlung und Wiederholungen.
Jede Fehlerantwort liefert type, code und message (auf Anthropic-Routen zusätzlich request_id: /v1/messages und /v1/skills nutzen immer das Anthropic-Format, /v1/files folgt x-api-key vs. Bearer, alle anderen Routen nutzen das OpenAI-Format). Prüfe im Code immer code statt message: Das OpenAI-SDK stellt code direkt am Fehler bereit, während das Anthropic-SDK ihn unter error.code im Antwort-Body ablegt.
import openai
try:
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Hallo"}],
)
except openai.APIStatusError as e:
if e.code == "provider_rejected_request":
prov = e.response.headers.get("x-noirdoc-provider")
print("Anbieter lehnt ab:", prov, e.body["message"])
else:
print("Fehler:", e.status_code, e.code)try {
const res = await client.chat.completions.create({
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Hallo" }],
});
} catch (err) {
if (!(err instanceof OpenAI.APIError)) throw err;
if (err.code === "provider_rejected_request") {
const prov = err.headers?.get("x-noirdoc-provider");
console.log("Anbieter lehnt ab:", prov, err.message);
} else {
console.log("Fehler:", err.status, err.code);
}
}import anthropic
try:
msg = anthropic_client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hallo"}],
)
except anthropic.APIStatusError as e:
err = e.body["error"]
if err["code"] == "provider_rejected_request":
prov = e.response.headers.get("x-noirdoc-provider")
print("Anbieter lehnt ab:", prov, err["message"])
else:
print("Fehler:", e.status_code, err["code"])type GatewayBody = {
error?: { type?: string; code?: string; message?: string };
};
try {
const msg = await anthropicClient.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hallo" }],
});
} catch (err) {
if (!(err instanceof Anthropic.APIError)) throw err;
const body = err.error as GatewayBody | undefined;
if (body?.error?.code === "provider_rejected_request") {
const prov = err.headers?.get("x-noirdoc-provider");
console.log("Anbieter lehnt ab:", prov, body.error.message);
} else {
console.log("Fehler:", err.status, body?.error?.code);
}
}Anbieter-Fehler übersetzt das Gateway einheitlich: Kapazitätsgrenzen als 429 resource_exhausted und Überlast als 503 (auf /v1/messages Status 529) provider_overloaded jeweils mit Retry-After, fachlich abgelehnte Anfragen als provider_rejected_request mit der Originalmeldung (auf BYOK-Routen auch für 401, 402, 403 und 429 des Anbieters; siehe Fehlerformat) und sonstige Fehler als 502 provider_error. Beide SDKs wiederholen Status 408, 409, 429 und 5xx bis max_retries (Standard: 2, nach dem Gateway-Failover) und beachten Retry-After bis 60 Sekunden, darüber greift exponentielles Backoff. Fehler mit Status 401 (invalid_api_key) oder 402 (insufficient_credit, key_budget_exhausted) behebt keine Wiederholung; behandle diese Codes direkt im Programm.
| Status | Code | Bedeutung |
|---|---|---|
| 400 | wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. |
| 400 | streaming_not_supported_for_endpoint | Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht. |
| 400 | provider_rejected_request | Der Anbieter hat die Anfrage selbst abgelehnt, etwa wegen eines ungültigen Parameters oder eines zu langen Kontexts. Die Antwort trägt den Statuscode des Anbieters (400, 404, 409, 413, 422 oder einen anderen Statuscode 4xx außer 401, 402, 403 und 429), und message enthält die Meldung des Anbieters in gekürzter und bereinigter Form, höchstens 500 Zeichen. Auf Routen mit eigenem Anbieter-Schlüssel (BYOK) meldet das Gateway auch die Statuscodes 401, 402, 403 und 429 des Anbieters so, weil Schlüssel, Guthaben und Kontingent dem Kunden gehören; bei 429 kommt Retry-After hinzu. |
| 401 | invalid_api_key | Der Schlüssel fehlt, ist ungültig oder deaktiviert, oder die Organisation ist nicht aktiv. |
| 402 | insufficient_credit | Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage (einschließlich Noirdoc Shield, auch auf BYOK-Routen mit aktivem Shield). |
| 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 | shield_violation | Noirdoc Shield hat die Anfrage vor der Weiterleitung an den Anbieter blockiert, weil ein aktiver Schutzfilter mit der Aktion block angeschlagen hat; message nennt die ausgelöste Regel (secrets, pii, ner, injection oder custom). |
| 403 | masking_not_supported_for_endpoint | Der Endpunkt unterstützt weder Noirdoc Shield noch die klassische Maskierung, aber die Richtlinie steht auf enforced oder die Anfrage sendet X-Noirdoc-Mask: on (auf /v1/images/generations auch X-Noirdoc-Shield: on). Während der Übergangsfrist der klassischen Maskierung bis zum 30.11.2026 betrifft das auf Bestandsorganisationen ohne Shield auch /v1/embeddings und /v1/rerank. |
| 404 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 429 | resource_exhausted | Der Anbieter hat Kapazitätsprobleme oder ein erschöpftes Guthaben gemeldet (Statuscode 429 oder 402), auch nach Failover über bis zu drei Anbieter. Die Antwort enthält Retry-After mit der Wartezeit in Sekunden. |
| 502 | stream_interrupted | Der Stream des Anbieters ist nach dem Beginn der Antwort abgebrochen oder hat einen Fehler gemeldet. Der Fehler steht im Stream selbst, weil der Statuscode 200 dann bereits gesendet ist. stream_interrupted trägt kein retry_after; nur Fehler im Stream, die einem HTTP-Fehler mit Wartezeit entsprechen, tragen es. |
| 503 | provider_overloaded | Der Anbieter hat Überlast gemeldet (Statuscode 503 oder 529), auch nach Failover über bis zu drei Anbieter. Der Statuscode ist 503 bei OpenAI-Endpunkten und 529 bei /v1/messages und /v1/skills. Die Antwort enthält Retry-After mit dem Wert des Anbieters zwischen 1 und 60 Sekunden, sonst 5 Sekunden. |
| 503 | gateway_restarting | Das Gateway wurde neu gestartet (Deployment), während der Stream noch auf die Antwort des Anbieters wartete. Der Fehler steht im laufenden Stream, weil der Statuscode 200 dann bereits gesendet ist. Das Fehlerobjekt enthält retry_after mit 5 Sekunden. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |