Schnellstart.
Eine Basis-URL und ein API-Schlüssel aus dem Portal genügen: Bestehende OpenAI- und Anthropic-Clients laufen unverändert über das Noirdoc-Gateway.
Erste Anfrage senden.
Erstelle im Noirdoc-Portal unter Models → API-Schlüssel einen px--Schlüssel und lege ihn als NOIRDOC_API_KEY ab (die Selbstregistrierung setzt eine EU-/EFTA-Verbindung ohne VPN, Private Relay, Proxy oder Rechenzentrums-IP voraus; beim ersten Start legst du den §-203-StGB-Modus fest). Setze base_url auf https://api.noirdoc.de/v1 und übergib eine Modell-ID wie qwen3.8-27b.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Prüfe § 4 auf Fristen."}],
)
print(res.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 res = await client.chat.completions.create({
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Prüfe § 4 auf Fristen." }],
});
console.log(res.choices[0].message.content);curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "Prüfe § 4 auf Fristen."}]
}'// 200 OK · Header: X-Noirdoc-Provider: ionos
{
"id": "chatcmpl-8e21a9",
"object": "chat.completion",
"model": "qwen3.8-27b",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "§ 4 setzt eine Kündigungsfrist von drei Monaten.",
},
"finish_reason": "stop",
},
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 16,
"total_tokens": 30,
},
}Die Antwort nennt den ausführenden Anbieter im Header X-Noirdoc-Provider. Alle Modell-IDs stehen im Modellkatalog und live unter GET /v1/models.
Startguthaben: Deine erste Organisation erhält ein Startguthaben mit einem Limit von 5 Anfragen pro Minute und 25 pro Tag UTC (sonst Status
429starter_rate_limit_exceeded). Vor der ersten bestätigten Aufladung sind bei verwalteten Anbietern nur freigegebene Startmodelle wieqwen3.8-27baufrufbar; Modelle mit der Kennzeichnung Ab Aufladung antworten mit Status403starter_model_not_allowed. Die erste Aufladung und eigene Anbieter-Schlüssel (BYOK) heben beide Grenzen sofort auf; Details unter Guthaben & Abrechnung.
Eingaben mit Shield prüfen.
Mit dem Header X-Noirdoc-Shield: on prüft Noirdoc Shield eingehende Texte zustandslos vor der Weiterleitung an den Anbieter. Personenbezogene Daten schwärzt das Gateway standardmäßig mit Platzhaltern wie [PERSON] oder [PHONE], erkannte Zugangsdaten und Prompt-Injections stoppt es mit Status 403 (shield_violation).
Bitte rufe Jonas Becker unter +49 30 901820 zurück.
Bitte rufe [PERSON] unter [PHONE] zurück.
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[
{
"role": "user",
"content": "Rufe Jonas Becker unter +49 30 901820 zurück.",
}
],
extra_headers={"X-Noirdoc-Shield": "on"},
)const res = await client.chat.completions.create(
{
model: "qwen3.8-27b",
messages: [
{
role: "user",
content: "Rufe Jonas Becker unter +49 30 901820 zurück.",
},
],
},
{ headers: { "X-Noirdoc-Shield": "on" } },
);curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "qwen3.8-27b",
"messages": [{
"role": "user",
"content": "Rufe Jonas Becker unter +49 30 901820 zurück."
}]
}'Neue Organisationen starten mit default_off. Dauerhafte Regeln je Schlüssel, Request-Tag oder Organisation setzt du unter Models → Shield; siehe Richtlinie und Vorrangfolge.
Authentifizierung und Header.
Jede Anfrage (außer GET /v1/prices) benötigt einen aktiven px--Schlüssel; sonst antwortet das Gateway mit Status 401 (invalid_api_key) und message "Missing or invalid API key" (kein Header mit Präfix px-) oder "Invalid or inactive API key" (unbekannter/deaktivierter Schlüssel oder inaktive Organisation). Das Gateway prüft die drei Schlüssel-Header in der Reihenfolge der Tabelle und entfernt deinen Schlüssel sowie X-Noirdoc-*, User-Agent, Cookies und eigene X-*-Header vor dem Versand an den Anbieter.
| Header | Richtung | Wirkung |
|---|---|---|
Authorization: Bearer px-... | Anfrage | Standard für OpenAI-SDK und curl (wird zuerst geprüft). |
x-api-key: px-... | Anfrage | Standard für Anthropic-SDK (zweite Prüfung; wählt auf /v1/files das Anthropic-Format). |
api-key: px-... | Anfrage | Kompatibel mit Azure-OpenAI-Clients (dritte Prüfung). |
X-Noirdoc-Shield | Anfrage & Antwort | Anfrage: on oder off (true/false/1/0) übersteuert default_on/default_off unterhalb von enforced, Schlüssel und Tag. Antwort: redacted=<n> bei Vollprüfung, partial; redacted=<n> bei ungeprüften Binär-/Referenzanhängen ohne enforced, sonst abwesend. |
X-Noirdoc-Mask | Anfrage | Kompatibler Alias für X-Noirdoc-Shield. Steuert auf Bestandsorganisationen mit klassischer Maskierung bis 2026-11-30 die reversible Maskierung (Antworten tragen Deprecation: true und Sunset: Mon, 30 Nov 2026 23:59:59 GMT). |
X-Noirdoc-Tags | Anfrage | Ordnet 1 bis 5 kommagetrennte Tags (^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$) für Budgets, Modellfilter und Shield zu (403 request_tags_disabled ohne Freischaltung; siehe Request-Tags). |
X-Noirdoc-Provider | Antwort | Slug des Anbieters, der geantwortet oder zuletzt einen Fehler gemeldet hat (fehlt auf /v1/files, /v1/skills, Gateway-Routen, Vorab-Fehlern und bei Streams nach 15 s zugunsten von : provider=<slug>). |
X-Noirdoc-Masked | Antwort | true bei vollständiger Shield-Prüfung (redacted=<n>) oder aktiver klassischer Maskierung; false bei partial, ungeprüften Anfragen und Fehlern vor dem Routing. |
An den Anbieter leitet das Gateway nur Content-Type, Accept, anthropic-version (bei Anthropic fest 2023-06-01, auf Google Vertex AI samt anthropic-beta in den Body übertragen), anthropic-beta und OpenAI-Beta weiter; OpenAI-Organization, OpenAI-Project und Idempotency-Key bleiben ausschließlich bei eigenen Anbieter-Schlüsseln (BYOK) erhalten. Auf allen Modell-Endpunkten bestimmt model den Anbieter, nicht der gewählte Auth-Header (/v1/skills geht immer an Anthropic, /v1/files folgt x-api-key vs. Bearer/api-key oder X-Provider; siehe Dateien & Skills). Verwende px--Schlüssel nur serverseitig und begrenze Ausgaben je Anwendung über Budgets je Schlüssel.
| Status | Code | Bedeutung |
|---|---|---|
| 400 | model_required | Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld). |
| 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). |
| 403 | model_not_allowed_for_key | Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels. |
| 403 | starter_model_not_allowed | Die Organisation nutzt noch ausschließlich das Startguthaben, und das Modell bzw. sein verwalteter Anbieter ist im Startguthaben nicht freigegeben. |
| 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). |
| 404 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 429 | starter_rate_limit_exceeded | Die Organisation nutzt noch ausschließlich das Startguthaben und hat die Grenze von 5 Anfragen je Minute oder 25 Anfragen je Tag (UTC) für verwaltete Anbieter erreicht. Die Antwort enthält Retry-After mit der Wartezeit in Sekunden. |
Endpunkte.
Alle Endpunkte liegen unter https://api.noirdoc.de/v1 (das Anthropic-SDK setzt https://api.noirdoc.de als Basis-URL und ergänzt /v1 selbst). Jede Referenzseite beschreibt die Abweichungen und Grenzen gegenüber dem Upstream-Format.
| Endpunkt | Format | Dokumentation |
|---|---|---|
POST /v1/chat/completions | OpenAI | Chat Completions |
POST /v1/responses | OpenAI | Responses |
POST /v1/messages, POST /v1/messages/count_tokens | Anthropic | Messages |
POST /v1/embeddings | OpenAI | Embeddings |
POST /v1/rerank | Rerank | Rerank |
POST /v1/audio/transcriptions, POST /v1/audio/speech | OpenAI | Audio |
POST /v1/images/generations | OpenAI | Bilder |
/v1/files, /v1/skills | OpenAI, Anthropic | Dateien & Skills |
POST /v1/shield/inspect, /v1/shield/policy | Noirdoc | Shield Inspect, Shield Policy |
GET /v1/models, GET /v1/prices | OpenAI, Noirdoc (öffentlich) | Modelle & Preise |
/v1/tags | Noirdoc (Preview) | Request-Tags |