llms.txt
# noirdoc — The Sovereign AI Gateway
> Ein Endpunkt zu allen KI-Modellen, betrieben in Europa, mit nutzungsbasierter Abrechnung.
Startet wie ein Prototyp. Skaliert bis Enterprise-Compliance. noirdoc bündelt die Modelle europäischer Anbieter und Hyperscaler — wie Azure, Google Vertex, IONOS, weber.cloud, AKI.IO und Infercom — hinter einem OpenAI- und Anthropic-kompatiblen Endpunkt: `https://api.noirdoc.de/v1`. Die Verträge dahinter liegen bei uns. Die Integration ändert eine Zeile Code (`base_url` und API-Key), die Anfrage- und Antwortformate bleiben die der jeweiligen Anbieter-API. Der Zugang ist per Selbstbedienung buchbar — null Monate Wartezeit auf Verträge.
## Kontrolle
Einmal integriert, entscheidest du jederzeit neu, welches Modell du wo nutzt und was es kosten darf.
- **Enterprise Quotas.** Rechenkapazität in Europa ist begrenzt. Mit uns startest du direkt mit Enterprise Availability.
- **Deterministic Failover.** Automatischer Wechsel bei Ausfall — strikt innerhalb deiner Compliance-Leitplanken.
- **Hard EU Residency.** Geografisch garantierte Endpunkte. Kein stilles Routing in Ausweichregionen.
- **Granular Budgeting.** Automatische Hard Caps pro Key für saubere Kostenrechnung pro Projekt oder Kunde. Die Kappung stoppt Kosten sofort, der Verbrauch ist pro Key, Modell und Anbieter einsehbar.
## Gebaut für Verschwiegenheit
AVV, Verschwiegenheitserklärung und Zero Data Retention sind bei uns Standard — damit sogar Anwälte, Steuerberater und Ärzte bedenkenlos arbeiten können.
- **By Contract.** AVV nach DSGVO und Verschwiegenheitserklärung nach § 203 StGB gehören zum Standardvertrag. Erfüllen Anbieter die Anforderungen für Berufsgeheimnisträger nicht, filtern wir sie raus.
- **By Architecture.** Durch Zero Data Retention werden Inhalte bei uns nicht gespeichert und nicht fürs Training genutzt. Jede Anfrage wird protokolliert und auf Wunsch werden personenbezogene Daten zu `<<PERSON_1>>` maskiert, bevor sie das Modell erreichen.
- Die Maskierung ist optional und je Organisation und Anfrage steuerbar; die Zuordnung der Platzhalter bleibt über eine Konversation hinweg konsistent.
- Zu jedem Modell im Katalog sind die Region des Rechenzentrums und der Stand der Verschwiegenheitszusage ausgewiesen.
## Ein Zugang zu einer großen Modellauswahl
Die OpenAI-kompatible API ermöglicht den Zugriff auf Modelle verschiedener Provider — mit transparenter Datenresidenz. Wir ersetzen eigene Konten und Verträge durch einen zentralisierten Zugang.
- Modellfamilien im Katalog, derzeit u. a.: GPT-5, GPT-OSS, Gemini, Llama, Qwen, Mistral, Gemma, DeepSeek, GLM, MiniMax, Apertus, FLUX und Whisper — Claude folgt über Google Vertex.
- Unterstützt werden Chat Completions, Responses, Anthropic Messages, Embeddings, Reranking, Bildgenerierung, Speech-to-Text, Text-to-Speech, Dateien und Streaming über SSE.
- Die Modellwahl steuert das `model`-Feld der Anfrage; ein Anbieterwechsel ist eine Änderung dieses Werts, kein Integrationsprojekt.
- Ergänzend lassen sich eigene Schlüssel für jeden OpenAI- oder Anthropic-kompatiblen Anbieter hinterlegen (BYOK); für diese Routen gelten die Bedingungen des jeweiligen Anbieters.
## Listenpreis ohne Aufschlag
Du zahlst nur, was du benutzt — und auch nur zu den Listenpreisen der Anbieter.
- 0 € Aufschlag, Grundgebühr, Mindestabnahme.
- 0 € für AVV und § 203-Vereinbarung.
- Kein Lock-in — Base-URL zurücktauschen, fertig.
- Kosten sind minutengenau sichtbar im Account; jeder API-Key bekommt ein Budget, bei dem wir Kosten sofort stoppen.
- Mit 5 € Startguthaben direkt loslegen und auf alle Modelle zugreifen: hello@noirdoc.de
## Für Entwickler
Die Entwickler-Doku unter https://www.noirdoc.de/docs/ ist die maßgebliche Quelle. Diese Zusammenfassung verweist auf die Seiten dort.
- Basis-URL: `https://api.noirdoc.de/v1`. Anfragen und Antworten folgen dem Format der OpenAI- bzw. Anthropic-API.
- Authentifizierung: API-Schlüssel beginnen mit `px-`. Admins erstellen sie im Portal unter **Models → API-Schlüssel**. Das Gateway liest den Schlüssel aus einem dieser Header: `Authorization: Bearer px-...` (OpenAI-SDK), `x-api-key: px-...` (Anthropic-SDK) oder `api-key: px-...` (Azure-OpenAI-Client).
- Modellwahl: Das Feld `model` wählt das Modell. `GET /v1/models` listet die Modelle, die der Schlüssel aufrufen darf.
- Anbieter: Das Gateway wählt je Anfrage einen Anbieter für das Modell. Eigene Anbieter-Schlüssel (BYOK) haben Vorrang, danach entscheidet der Preis. Ist ein Anbieter nicht erreichbar oder antwortet er mit 429 oder 5xx, bevor Ihre Anwendung Daten der Antwort erhalten hat, fällt das Gateway auf den nächsten Anbieter zurück (Failover). Von einem eigenen Anbieter-Schlüssel wechselt es dabei nie auf einen von Noirdoc verwalteten Anbieter. Der Antwort-Header `X-Noirdoc-Provider` nennt den Anbieter, der geantwortet hat.
- Maskierung: Die Maskierungsrichtlinie der Organisation (Portal: **Models → Datenschutz**) legt fest, ob das Gateway maskiert. `enforced` (Portal: „Erzwungen“) maskiert immer. `default_on` („Standard an“) maskiert, außer die Anfrage sendet `X-Noirdoc-Mask: off`. `default_off` („Standard aus“) maskiert erst, wenn die Anfrage `X-Noirdoc-Mask: on` sendet. Das Gateway entfernt diesen Header vor der Weiterleitung an den Anbieter. Der Antwort-Header `X-Noirdoc-Masked` (`true` oder `false`) zeigt, ob die Maskierung für die Anfrage aktiv war.
- Budgets: Jeder API-Schlüssel kann ein Budget mit einem Ausgabenlimit in Euro haben, optional täglich, wöchentlich (montags) oder monatlich (am 1.) zurückgesetzt, jeweils um 00:00 UTC. Es zählen nur Anfragen über von Noirdoc verwaltete Anbieter, nicht über eigene Anbieter-Schlüssel. Ist das Budget aufgebraucht oder könnte die Anfrage den Rest überschreiten, antwortet das Gateway mit 402 und dem Fehlercode `key_budget_exhausted`. Reicht das Guthaben der Organisation nicht, lautet der Fehlercode `insufficient_credit`.
- Fehler: Das Gateway beantwortet jeden Fehler selbst, auch den eines Anbieters, mit einem Fehlerobjekt `{"error": {"type", "code", "message"}}`. Der Pfad bestimmt das Format: `/v1/messages` und `/v1/skills` antworten im Anthropic-Format, `/v1/files` folgt dem Header `x-api-key`, alle anderen Endpunkte antworten im OpenAI-Format.
Prüfen Sie programmatisch `error.code`, nicht `message`. Fehler des Anbieters erscheinen als `resource_exhausted` (429), `provider_overloaded` (503, bei `/v1/messages` und `/v1/skills` 529), `provider_rejected_request` oder `provider_error`. Bei `resource_exhausted` und `provider_overloaded` nennt `Retry-After` die Wartezeit in Sekunden.
Ungültige Bodys an `/v1/detect` und `/v1/pseudonymize` beantwortet das Gateway mit 422 und `{"detail": [...]}`. Alle Codes stehen unter [Fehlercodes](https://www.noirdoc.de/docs/referenz/fehlercodes/).
## Endpunkte
- `POST /v1/chat/completions`: Chat Completions im OpenAI-Format, mit Maskierung und Streaming (SSE). Gespeicherte Completions unter `/v1/chat/completions/{id}` und `/v1/chat/completions/{id}/messages`.
- `POST /v1/responses`: Responses im OpenAI-Format, mit Maskierung und Streaming (SSE). Unterrouten: `input_tokens`, `compact`, `{id}`, `{id}/cancel`, `{id}/input_items`.
- `POST /v1/messages`: Messages im Anthropic-Format, mit Maskierung und Streaming (SSE). Dazu `POST /v1/messages/count_tokens`, das Claude Code nutzt. Token-Zählungen (`count_tokens`, `input_tokens`) rechnet das Gateway nicht ab.
- `POST /v1/embeddings`: Embeddings, ohne Maskierung und ohne Streaming.
- `POST /v1/rerank`: Reranking von Dokumenten zu einer Suchanfrage, nur Text, abgerechnet nach Eingabe-Tokens oder je Anfrage, ohne Maskierung und ohne Streaming.
- `POST /v1/audio/transcriptions`: Transkription (Speech-to-Text), Body als `multipart/form-data`, abgerechnet nach Audiodauer, ohne Maskierung und ohne Streaming.
- `POST /v1/audio/speech`: Sprachausgabe (Text-to-Speech), antwortet mit Audiodaten, abgerechnet nach Zeichen der Eingabe, ohne Maskierung und ohne Streaming.
- `POST /v1/images/generations`: Bildgenerierung, je nach Modell abgerechnet pro Bild oder nach Megapixeln, ohne Maskierung und ohne Streaming.
- `/v1/files` und `/v1/skills` (Skills: Anthropic): Das Gateway reicht diese Anfragen ohne Maskierung an den Anbieter durch. Erlaubt die Organisation keine Dateiinhalte, antwortet es mit 403 und `file_content_not_allowed`.
- `GET /v1/models`: Modelle, die der Schlüssel aufrufen darf, mit ihrer Familie im Feld `endpoint_family`.
- `GET /v1/prices`: öffentliche Preisliste, ohne Schlüssel abrufbar.
- `POST /v1/detect` und `POST /v1/pseudonymize`: erkennen bzw. maskieren personenbezogene Daten in einem Text, ohne ein Modell aufzurufen.
Auf Embeddings, Rerank, Audio und Bildgenerierung antwortet das Gateway mit 403 und `masking_not_supported_for_endpoint`, wenn die Maskierungsrichtlinie `enforced` ist oder die Anfrage `X-Noirdoc-Mask: on` sendet. Bei `/v1/files` und `/v1/skills` gilt das für Aufrufe mit Inhalt wie das Hochladen; Auflisten, Abrufen, Herunterladen und Löschen bleiben erlaubt.
## Dokumentation
- [Übersicht](https://www.noirdoc.de/docs/): Einstieg in die Entwickler-Doku.
- [Schnellstart](https://www.noirdoc.de/docs/schnellstart/): Schlüssel erstellen, erste Anfrage, maskierte Anfrage, `X-Noirdoc-Provider` lesen.
Anleitungen:
- [OpenAI-SDK](https://www.noirdoc.de/docs/anleitungen/openai-sdk/): Python und TypeScript mit der Basis-URL des Gateways.
- [Anthropic-SDK & Claude Code](https://www.noirdoc.de/docs/anleitungen/anthropic-sdk/): Anthropic-SDK und Claude Code über das Gateway, inklusive `count_tokens`.
- [Maskierung einschalten](https://www.noirdoc.de/docs/anleitungen/maskierung/): Header und Maskierungsrichtlinie, Ergebnis mit `/v1/detect` prüfen.
- [Modelle & Anbieter einschränken](https://www.noirdoc.de/docs/anleitungen/modelle-einschraenken/): erlaubte Modelle und Anbieter je Schlüssel und die Einstufung als Berufsgeheimnisträger (§ 203 StGB) aus Entwicklersicht.
- [Budgets je Schlüssel](https://www.noirdoc.de/docs/anleitungen/budgets/): ein Schlüssel je Anwendung, Ausgabenlimit, Rücksetzung, 402 behandeln.
- [Streaming](https://www.noirdoc.de/docs/anleitungen/streaming/): Antworten als SSE empfangen.
- [Dateien](https://www.noirdoc.de/docs/anleitungen/dateien/): Dateien inline oder über `/v1/files` senden, **Dateiinhalte zulassen** und Dateianalyse-Modus.
- [Audio & Bilder](https://www.noirdoc.de/docs/anleitungen/audio-bilder/): Audio transkribieren, Text vorlesen lassen und Bilder erzeugen.
- [Lokale Werkzeuge](https://www.noirdoc.de/docs/anleitungen/lokale-werkzeuge/): `noirdoc`-CLI und Claude-Code-Plugin.
Referenz:
- [Authentifizierung & Header](https://www.noirdoc.de/docs/referenz/authentifizierung/): `px-`-Schlüssel, Header für den Schlüssel, `X-Noirdoc-Mask`, `X-Noirdoc-Provider` und `X-Noirdoc-Masked`.
- [Chat Completions](https://www.noirdoc.de/docs/referenz/chat-completions/), [Responses](https://www.noirdoc.de/docs/referenz/responses/), [Messages](https://www.noirdoc.de/docs/referenz/messages/): was das Gateway an diesen Endpunkten ergänzt oder ändert.
- [Embeddings](https://www.noirdoc.de/docs/referenz/embeddings/), [Rerank](https://www.noirdoc.de/docs/referenz/rerank/), [Audio](https://www.noirdoc.de/docs/referenz/audio/), [Bilder](https://www.noirdoc.de/docs/referenz/bilder/), [Dateien & Skills](https://www.noirdoc.de/docs/referenz/dateien-skills/): Endpunkte ohne Maskierung und durchgereichte Endpunkte.
- [Modelle & Preise](https://www.noirdoc.de/docs/referenz/modelle-preise/): `GET /v1/models` und die öffentliche Preisliste `GET /v1/prices`.
- [Erkennen & Pseudonymisieren](https://www.noirdoc.de/docs/referenz/erkennen-pseudonymisieren/): `POST /v1/detect` und `POST /v1/pseudonymize`.
- [Maskierte Felder](https://www.noirdoc.de/docs/referenz/maskierung-felder/): welche Felder das Gateway je Endpunkt maskiert.
- [Fehlercodes](https://www.noirdoc.de/docs/referenz/fehlercodes/): Statuscode, Bedeutung und Abhilfe für jeden Fehlercode des Gateways.
- [Grenzen](https://www.noirdoc.de/docs/referenz/grenzen/): Größen-, Zeit- und Mengengrenzen, die das Gateway selbst prüft.
Konzepte:
- [Maskierung](https://www.noirdoc.de/docs/konzepte/maskierung/): wie das Gateway personenbezogene Daten durch Platzhalter wie `<<PERSON_1>>` ersetzt und in der Antwort zurückübersetzt.
- [Anbieter & Routing](https://www.noirdoc.de/docs/konzepte/anbieter-routing/): Reihenfolge der Anbieter, Failover und `X-Noirdoc-Provider`.
- [Organisation & Schlüssel](https://www.noirdoc.de/docs/konzepte/organisation-schluessel/): was an der Organisation hängt und was am API-Schlüssel.
- [Guthaben & Abrechnung](https://www.noirdoc.de/docs/konzepte/guthaben/): Guthaben, Kontostand, Startguthaben und Abrechnung.
- [Berufsgeheimnisträger (§ 203 StGB)](https://www.noirdoc.de/docs/konzepte/berufsgeheimnistraeger/): welche Anbieter das Gateway für Berufsgeheimnisträger ausfiltert und welche Fehler dabei entstehen.
## Wichtige Seiten
- [Übersicht](https://www.noirdoc.de/): das Gateway, die Anbieter, Compliance und Preise auf einer Seite.
- [Modelle und Anbieter](https://www.noirdoc.de/modelle/): jedes Modell mit Anbieter, Datenresidenz, § 203-Status und Listenpreis; eine Seite je Modell (`/modelle/<modell>/`), je Hersteller (`/modelle/<hersteller>/`) und je Anbieter (`/anbieter/<anbieter>/`).
- [Berufsgeheimnisträger (§ 203 StGB)](https://www.noirdoc.de/berufsgeheimnistraeger/): Einordnung für Kanzleien, Steuerberatung, Arztpraxen, Kliniken und Wirtschaftsprüfung.
- [KI für Steuerkanzleien](https://www.noirdoc.de/steuerberater/): was Steuerberater mit dem Gateway erledigen (Belege, Bescheide, Schriftverkehr, Recherche), Verschwiegenheit nach § 203 Abs. 3 StGB, Modelle und Preise.
- [Portal (Anmelden)](https://portal.noirdoc.de/de/sign-in): Konto anlegen, API-Schlüssel erstellen, Guthaben aufladen.
- [Demo vereinbaren](https://www.noirdoc.de/demo/): Termin für ein technisches Gespräch.
- [AVV](https://www.noirdoc.de/avv/): Auftragsverarbeitungsvertrag nach Art. 28 DSGVO im Wortlaut.
- [AGB](https://www.noirdoc.de/agb/): allgemeine Geschäftsbedingungen.
- [Datenschutz](https://www.noirdoc.de/datenschutz/): Datenschutzerklärung der Website und des Dienstes.
- [Impressum](https://www.noirdoc.de/impressum/): Anbieterkennzeichnung.
## Kontakt
- hello@noirdoc.de — wir antworten in der Regel innerhalb eines Werktags.
- [Portal (Anmelden)](https://portal.noirdoc.de/de/sign-in)
- [Demo vereinbaren](https://www.noirdoc.de/demo/)
