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.

Python
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)
TypeScript
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
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."}]
  }'
JSON
// 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 429 starter_rate_limit_exceeded). Vor der ersten bestätigten Aufladung sind bei verwalteten Anbietern nur freigegebene Startmodelle wie qwen3.8-27b aufrufbar; Modelle mit der Kennzeichnung Ab Aufladung antworten mit Status 403 starter_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).

Deine Eingabe

Bitte rufe Jonas Becker unter +49 30 901820 zurück.

Geht an das Modell

Bitte rufe [PERSON] unter [PHONE] zurück.

Shield pro Anfrage einschalten
Python
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"},
)
TypeScript
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
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.

HeaderRichtungWirkung
Authorization: Bearer px-...AnfrageStandard für OpenAI-SDK und curl (wird zuerst geprüft).
x-api-key: px-...AnfrageStandard für Anthropic-SDK (zweite Prüfung; wählt auf /v1/files das Anthropic-Format).
api-key: px-...AnfrageKompatibel mit Azure-OpenAI-Clients (dritte Prüfung).
X-Noirdoc-ShieldAnfrage & AntwortAnfrage: 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-MaskAnfrageKompatibler 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-TagsAnfrageOrdnet 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-ProviderAntwortSlug 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-MaskedAntworttrue 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.

EndpunktFormatDokumentation
POST /v1/chat/completionsOpenAIChat Completions
POST /v1/responsesOpenAIResponses
POST /v1/messages, POST /v1/messages/count_tokensAnthropicMessages
POST /v1/embeddingsOpenAIEmbeddings
POST /v1/rerankRerankRerank
POST /v1/audio/transcriptions, POST /v1/audio/speechOpenAIAudio
POST /v1/images/generationsOpenAIBilder
/v1/files, /v1/skillsOpenAI, AnthropicDateien & Skills
POST /v1/shield/inspect, /v1/shield/policyNoirdocShield Inspect, Shield Policy
GET /v1/models, GET /v1/pricesOpenAI, Noirdoc (öffentlich)Modelle & Preise
/v1/tagsNoirdoc (Preview)Request-Tags