Schnellstart

Das Gateway ist unter https://api.noirdoc.de/v1 erreichbar und spricht das Format der OpenAI-API. Sie brauchen einen Zugang zum Noirdoc-Portal und curl, Python oder Node.js.

1. Schlüssel erstellen

   Melden Sie sich im Portal an; ohne Konto führt die Seite über Konto erstellen durch die Registrierung. Beim ersten Anmelden führt Sie die Seite Erste Schritte durch die Einrichtung. Beantworten Sie dort zuerst die Frage zu § 203 StGB und erstellen Sie danach Ihren ersten Schlüssel. Die Antwort zu § 203 StGB bestimmt, welche Anbieter Ihrer Organisation zur Verfügung stehen (siehe Berufsgeheimnisträger).

   Weitere Schlüssel erstellen Sie unter Models → API-Schlüssel mit Neuer Schlüssel. Das Portal zeigt einen Schlüssel einmal an, direkt nach dem Erstellen.

   Legen Sie den Schlüssel in einer Umgebungsvariablen ab. Alle Beispiele dieser Dokumentation lesen ihn aus NOIRDOC_API_KEY. Der Wert beginnt mit px-.

   Ergebnis: Die Umgebungsvariable NOIRDOC_API_KEY enthält Ihren Schlüssel.

   Shell

   export NOIRDOC_API_KEY="px-..."

2. Modell auswählen

   GET /v1/models listet die Modelle, die Ihr Schlüssel aufrufen darf. Jedes Element der Liste hat eine id. Diese Modell-ID setzen Sie in Anfragen als model ein.

   Die Beispiele verwenden qwen3.8-27b. Steht diese ID nicht in Ihrer Liste, setzen Sie eine andere Modell-ID aus der Liste ein.

   Ergebnis: Sie kennen eine Modell-ID, die Ihr Schlüssel aufrufen darf.

   Shell

   curl https://api.noirdoc.de/v1/models \
     -H "Authorization: Bearer $NOIRDOC_API_KEY"

3. Erste Anfrage senden

   Senden Sie eine Anfrage an POST /v1/chat/completions. Im OpenAI-SDK setzen Sie dafür base_url auf https://api.noirdoc.de/v1 und api_key auf Ihren Schlüssel.

   Ergebnis: Die Antwort hat das Format der OpenAI-API. Der Text steht in choices[0].message.content.

   curl Python TypeScript

   Shell

   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": "Hallo"}]
     }'

   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": "Hallo"}],
   )
   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: "Hallo" }],
   });
   console.log(response.choices[0].message.content);

4. Maskierte Anfrage senden

   Senden Sie den Header X-Noirdoc-Mask: on. Das Gateway ersetzt dann personenbezogene Daten durch Platzhalter wie <<PERSON_1>>, bevor die Anfrage das Modell erreicht. In der Antwort setzt es die Originalwerte wieder ein.

   Sie senden

   Beantworten Sie die Mail von Jonas Becker.

   Das Modell sieht

   Beantworten Sie die Mail von <<PERSON_1>>.

   Neue Organisationen starten mit der Maskierungsrichtlinie default_off: Das Gateway maskiert, wenn die Anfrage den Header mit on sendet. Welche Richtlinien es gibt, beschreibt Maskierung einschalten.

   Ergebnis: Das Modell erhält Platzhalter statt der Originalwerte. In der Antwort an Ihre Anwendung stehen wieder die Originalwerte.

   curl Python TypeScript

   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": "Beantworten Sie die Mail von Jonas Becker."
       }]
     }'

   Python

   response = client.chat.completions.create(
       model="qwen3.8-27b",
       messages=[{
           "role": "user",
           "content": "Beantworten Sie die Mail von Jonas Becker.",
       }],
       extra_headers={"X-Noirdoc-Mask": "on"},
   )
   print(response.choices[0].message.content)

   TypeScript

   const response = await client.chat.completions.create(
     {
       model: "qwen3.8-27b",
       messages: [
         {
           role: "user",
           content: "Beantworten Sie die Mail von Jonas Becker.",
         },
       ],
     },
     { headers: { "X-Noirdoc-Mask": "on" } },
   );
   console.log(response.choices[0].message.content);

5. Anbieter aus der Antwort lesen

   In curl zeigt -i die Header an. In den SDKs lesen Sie Header über die rohe Antwort. Nach welcher Regel das Gateway den Anbieter wählt, beschreibt Anbieter & Routing.

   Ergebnis: Die Antwort enthält den Header X-Noirdoc-Provider. Er nennt den Anbieter, der die Anfrage beantwortet hat.

   curl Python TypeScript

   Shell

   curl -i 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": "Hallo"}]
     }'

   Python

   raw = client.chat.completions.with_raw_response.create(
       model="qwen3.8-27b",
       messages=[{"role": "user", "content": "Hallo"}],
   )
   print(raw.headers.get("x-noirdoc-provider"))
   response = raw.parse()

   TypeScript

   const { data, response } = await client.chat.completions
     .create({
       model: "qwen3.8-27b",
       messages: [{ role: "user", content: "Hallo" }],
     })
     .withResponse();
   console.log(response.headers.get("x-noirdoc-provider"));

Fehler beheben

Ein fehlender oder ungültiger Schlüssel ergibt Statuscode 401 mit dem Body {"detail": "..."}. Fehler, die das Gateway bei Modell-Anfragen selbst meldet, haben ein Fehlerobjekt mit "type": "proxy_error" und einem code. Diese Codes treten beim Einstieg am häufigsten auf:

Alle Codes stehen unter Fehlercodes.

Nächste Schritte

• OpenAI-SDK: Client einrichten, Header setzen und Fehler behandeln
• Anthropic-SDK & Claude Code: /v1/messages und Claude Code über das Gateway
• Streaming: Antworten als SSE empfangen, auch mit Maskierung
• Maskierung einschalten: Maskierung je Anfrage oder für die ganze Organisation