Schlüssel, Tags & Budgets.
Organisation und Rollen, API-Schlüssel mit Berechtigungen und Euro-Budgets, Request-Tags (/v1/tags), Guthaben sowie /v1/models und /v1/prices.
Die Organisation bündelt API-Schlüssel, eigene Anbieter (BYOK), Richtlinien und Guthaben; Personen greifen im Portal je Organisation als Admin (Mitglieder und Rollen verwalten, Schlüssel erstellen/widerrufen, BYOK verbinden, Einstellungen ändern, Guthaben aufladen) oder Mitglied (Lesezugriff auf Schlüssel, Nutzung, Einstellungen und Kontostand) darauf zu.
Organisation, Rollen und API-Schlüssel.
Jeder API-Schlüssel beginnt mit px-, gehört zur Organisation und wird unter Models → API-Schlüssel (Neuer Schlüssel) einmalig im Klartext angezeigt; ein widerrufener Schlüssel antwortet sofort mit 401 invalid_api_key und lässt sich reaktivieren oder endgültig löschen:
| Ebene | Einstellung | Wirkung & Ort im Portal |
|---|---|---|
| Organisation | Shield-Richtlinie & Schutzfilter | Standardmodus (default_off, default_on, enforced), fünf Filter und custom_patterns unter Models → Shield (siehe Noirdoc Shield). |
| Organisation | Erweiterte Einstellungen | allow_stored_responses (Responses-API-Speicherung, neu: aus) und allow_file_content (Dateien/Bilder/Audio, Standard: an) unter Models → Shield. |
| Organisation | Eigene Anbieter (BYOK), § 203 & Guthaben | BYOK-Schlüssel mit Vorrang unter Models → Provider, §-203-Einstufung auf Erste Schritte (siehe Anbieter, Routing & § 203) sowie Kontostand unter Abrechnung. |
| API-Schlüssel | Modelle, Anbieter & shield_mode | Modellauswahl, Datenresidenz, CLOUD Act, § 203, Anbieterliste sowie Shield (inherit, on, off) unter Models → API-Schlüssel. |
| API-Schlüssel | Budget (€) | Optionales Ausgabenlimit je Schlüssel mit Rücksetzintervall (402 key_budget_exhausted). |
| API-Schlüssel | can_manage_shield | Shield-Richtlinie per API verwalten schaltet /v1/shield/policy frei; ein auf on festgelegter Schlüssel kann die Richtlinie nicht abschwächen (403 insufficient_key_permissions). |
| API-Schlüssel | can_manage_tags | Tag-Verwaltung erlauben (/v1/tags) schaltet /v1/tags und /v1/tags/_default innerhalb des eigenen Modell-, Anbieter- und Shield-Rahmens des Schlüssels frei (403 insufficient_key_permissions). |
Ein Schlüssel je Anwendung: Lege für jede Anwendung und Umgebung einen eigenen
px--Schlüssel an (z. B.chatbot-produndchatbot-test), um Budgets, Modellauswahl und Widerruf sauber zu trennen.
Budgets je Schlüssel.
Ein Euro-Budget begrenzt die Ausgaben eines einzelnen API-Schlüssels, während andere Schlüssel deiner Organisation weiterarbeiten. Bei Status 402 unterscheidest du den Auslöser anhand von error.code:
import openai
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
try:
client.chat.completions.create(
model="qwen3.8-27b",
max_tokens=500,
messages=[{"role": "user", "content": "Zusammenfassung."}],
)
except openai.APIStatusError as err:
if err.status_code == 402:
code = err.response.json()["error"]["code"]
# "insufficient_credit" | "key_budget_exhausted"
# | "tag_budget_exhausted"import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
try {
await client.chat.completions.create({
model: "qwen3.8-27b",
max_tokens: 500,
messages: [{ role: "user", content: "Zusammenfassung." }],
});
} catch (err) {
if (err instanceof OpenAI.APIError && err.status === 402) {
// err.code: "insufficient_credit" | "key_budget_exhausted"
// | "tag_budget_exhausted"
}
}curl -s https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"max_tokens": 500,
"messages": [{"role": "user", "content": "Zusammenfassung."}]
}' | jq '.error.code'{
"error": {
"type": "insufficient_quota",
"code": "key_budget_exhausted",
"message": "This request could cost up to 0.42 EUR, more …",
"param": null
}
}Vor der Weiterleitung prüft das Gateway zuerst das Organisationsguthaben (insufficient_credit), danach das Schlüssel-Budget (key_budget_exhausted) und anschließend angehängte Tag-Budgets in Header-Reihenfolge (tag_budget_exhausted).
| Aspekt | Regel |
|---|---|
| Rücksetzintervalle | Täglich (00:00 UTC), Wöchentlich (montags 00:00 UTC), Monatlich (am 1. des Monats 00:00 UTC) oder Nie (gesamte Lebensdauer des Schlüssels; leer = kein Limit). |
| Angerechnete Kosten | Bepreiste verwaltete Modelle (status < 400) sowie die Prüfgebühr von Noirdoc Shield (+0,40 € / 1 Mio. geprüfter Eingabe-Tokens, auch auf BYOK-Routen mit aktivem Shield, bei 403 shield_violation und auf POST /v1/shield/inspect; BYOK ohne aktives Shield sowie klassische Maskierung bis 30.11.2026 zählen mit 0,00 €). |
| Kostenschätzung vorab | Chat/Embeddings: JSON-Zeichenlänge der Eingabe geteilt durch 4 (+ 0,40 € / 1 Mio. Tokens bei aktivem Shield) plus max_tokens / max_completion_tokens / max_output_tokens (ohne Angabe rechnet das Gateway bei Chat mit 4.096 Tokens – ein passendes max_tokens vermeidet verfrühte Ablehnungen kurz vor dem Limit). Bilder: Anzahl × Bild-/Megapixelpreis. Audio: prüft nur, ob das Limit noch nicht erreicht ist. |
Request-Tags (Preview).
Preview: Request-Tags sind als Preview für ausgewählte Organisationen verfügbar. Schreib an hello@noirdoc.de, um die Funktion freizuschalten. Ohne Freischaltung beantwortet das Gateway den Header
X-Noirdoc-Tagsund Aufrufe auf/v1/tagsmit403 request_tags_disabled.
Über X-Noirdoc-Tags übergibst du 1 bis 5 kommagetrennte Tag-Namen (Duplikate werden zusammengefasst, der Header wird vor der Weiterleitung entfernt und auch von GET /v1/models sowie POST /v1/shield/inspect ausgewertet), um Mandate, Kostenstellen oder Teams ohne eigene API-Schlüssel mit eigenen Budgets, Modell-/Anbieterregeln und shield_mode auszustatten. Tag-Namen folgen dem Muster ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$ (_default ist für /v1/tags/_default reserviert; Obergrenze 1.000 Tags je Organisation, darüber 403 tag_limit_exceeded). Unter Models → Tags legt das Gateway unbekannte Tags standardmäßig beim ersten weitergeleiteten Aufruf anhand der Vorlage _default automatisch an (tag_auto_create_enabled: true; wenn deaktiviert, antwortet das Gateway mit 403 tag_not_found):
import os
import httpx
from openai import OpenAI
key = os.environ["NOIRDOC_API_KEY"]
httpx.put(
"https://api.noirdoc.de/v1/tags/mandat-2026-042",
headers={"Authorization": f"Bearer {key}"},
json={
"description": "Akte 2026/042 – Arbeitsrecht",
"budget_limit_eur": 25.0,
"budget_reset": "monthly",
"shield_mode": "on",
"allowed_residencies": ["DE", "EU"],
"require_no_cloud_act": True,
"require_section203": True,
},
).raise_for_status()
client = OpenAI(base_url="https://api.noirdoc.de/v1", api_key=key)
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Fristen prüfen."}],
extra_headers={
"X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht"
},
)import OpenAI from "openai";
const key = process.env.NOIRDOC_API_KEY!;
await fetch("https://api.noirdoc.de/v1/tags/mandat-2026-042", {
method: "PUT",
headers: {
Authorization: `Bearer ${key}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
description: "Akte 2026/042 – Arbeitsrecht",
budget_limit_eur: 25.0,
budget_reset: "monthly",
shield_mode: "on",
allowed_residencies: ["DE", "EU"],
require_no_cloud_act: true,
require_section203: true,
}),
});
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: key,
});
await client.chat.completions.create(
{
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Fristen prüfen." }],
},
{ headers: { "X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht" } },
);curl -X PUT https://api.noirdoc.de/v1/tags/mandat-2026-042 \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Akte 2026/042 – Arbeitsrecht",
"budget_limit_eur": 25.0,
"budget_reset": "monthly",
"shield_mode": "on",
"allowed_residencies": ["DE", "EU"],
"require_no_cloud_act": true,
"require_section203": true
}'
curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "X-Noirdoc-Tags: mandat-2026-042,team-arbeitsrecht" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "Fristen prüfen."}]
}'{
"name": "mandat-2026-042",
"description": "Akte 2026/042 – Arbeitsrecht",
"is_active": true,
"budget_limit_eur": 25.0,
"budget_reset": "monthly",
"budget_spent_eur": 0.0,
"budget_spent_total_eur": 0.0,
"shield_mode": "on",
"allowed_residencies": ["DE", "EU"],
"require_no_cloud_act": true,
"require_section203": true,
"last_used_at": null
}Bei mehreren Tags in einer Anfrage bildet das Gateway für Modelle und Anbieter die Schnittmenge (403 model_not_allowed_for_tag / provider_not_allowed_for_tag), bei shield_mode gewinnt “on” vor “off”, und die vollen Anfragekosten werden auf den Schlüssel sowie auf jedes genannte Tag gebucht.
| Methode & Pfad | Verhalten (can_manage_tags erforderlich) |
|---|---|
GET /v1/tags | Listet die Tags deiner Organisation (optional mit limit, offset und Suchfilter q). |
POST /v1/tags | Legt ein neues Tag an (201 Created); existiert der Name bereits, antwortet das Gateway mit 409 tag_already_exists. |
GET | PUT /v1/tags/_default | Liest oder aktualisiert die Standard-Tag-Vorlage (tag_auto_create_enabled, shield_mode, Budget, Modell- und Anbieterregeln). |
GET | PUT | PATCH /v1/tags/{name} | Liest, erstellt/ersetzt oder aktualisiert ein einzelnes Tag; budget_spent_eur, budget_spent_total_eur und last_used_at bleiben bei PUT und PATCH erhalten. |
DELETE /v1/tags/{name} | Zweistufig (204 No Content): Auf einem aktiven Tag (is_active: true) setzt der erste Aufruf is_active: false (weitere Anfragen erhalten 403 tag_disabled; Reaktivierung per PATCH mit {"is_active": true}). Auf einem bereits inaktiven Tag löscht ein zweiter Aufruf es endgültig, sofern budget_spent_total_eur == 0 ist – sonst 409 tag_has_spend_history. |
Guthaben, Startguthaben und Aufladung.
Organisationen ohne Rechnungsabrechnung begleichen verwaltete Modellaufrufe (status < 400) und Noirdoc-Shield-Prüfungen aus einem im Voraus aufgeladenen Guthaben (Abrechnung → Aufladen über Mollie per Karte oder SEPA-Überweisung in ganzen Euro, Gutschrift bei Überweisung nach 1–2 Bankarbeitstagen, zuzüglich etwaiger Umsatzsteuer). Da das Gateway die tatsächlichen Kosten erst nach der Antwort abbucht, kann der Kontostand kurzzeitig unter null fallen und wird mit der nächsten Aufladung ausgeglichen:
| Bereich | Regeln |
|---|---|
| Abrechnungseinheiten | Chat, Responses, Messages: Eingabe-, Ausgabe- und Cache-Tokens (count_tokens / input_tokens kosten 0 €). Embeddings: Eingabe-Tokens. Rerank: Eingabe-Tokens oder je Anfrage. /v1/audio/speech: Eingabezeichen. /v1/audio/transcriptions: gemeldete Audiodauer anteilig je Minute. /v1/images/generations: je Bild oder Megapixel. Shield: +0,40 € / 1 Mio. geprüfter Eingabe-Tokens (BYOK ohne aktives Shield bleibt bei 0 €). |
| Startguthaben | Einmalig je Konto für die erste angelegte Organisation. Bis zur ersten bestätigten Aufladung sind auf verwalteten Routen nur freigegebene Modelle aufrufbar (403 starter_model_not_allowed, im Portal Ab Aufladung, kostenfrei und ohne Rate-Limit-Abzug), und verwaltete Anfragen sind organisationsweit auf 5 Anfragen/Minute sowie 25 Anfragen/Tag (UTC) begrenzt (429 starter_rate_limit_exceeded mit Retry-After; Minuten-Ablehnungen zählen nicht auf das Tageslimit). BYOK ist unbegrenzt; die erste bestätigte Aufladung schaltet sofort alle Modelle frei und hebt beide Limits auf. |
| Automatische Aufladung | Nur per Karte (Karte sofort → Automatisch aufladen, wenn das Guthaben knapp wird mit Einzugsermächtigung). Drei Pflichtwerte: Aufladen unter (Schwellenwert), Betrag je Aufladung (>= Schwellenwert) und Höchstens pro Monat (Kalendermonat in Europe/Berlin, >= Aufladebetrag; manuelle Aufladungen zählen nicht mit, für neue Organisationen gilt ein Karten-Tageslimit). Höchstens eine Abbuchung läuft gleichzeitig; Admins erhalten Pflicht-Belegmails. |
| Pause & Kartenwechsel | Nach einer Bankablehnung pausiert die Automatik und lässt sich unter Abrechnung mit Wieder aktivieren fortsetzen. Bei abgelaufener Karte (Mit anderer Karte aufladen), ungültigem Rechnungsprofil oder nach Ausschalten / Karte entfernen ist eine erneute Kartenzahlung nötig; bei Rückbuchungen oder gesperrten Aufladungen hilft hello@noirdoc.de. |
| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request_tags | Der Header X-Noirdoc-Tags oder der Tag-Name im Pfad unter /v1/tags ist leer, enthält mehr als 5 Tags oder entspricht nicht dem Format ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$. |
| 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. |
| 402 | tag_budget_exhausted | Das Budget eines in X-Noirdoc-Tags genannten Tags ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus; message nennt das Tag. |
| 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 | model_not_billable | Für das Modell ist kein vollständiger Preis hinterlegt, deshalb lässt es sich mit Guthaben nicht nutzen. |
| 403 | request_tags_disabled | Die Anfrage sendet X-Noirdoc-Tags oder ruft /v1/tags auf, aber Request-Tags (Preview) sind für diese Organisation nicht freigeschaltet. |
| 403 | tag_not_found | Das genannte Tag existiert nicht. Bei Anfragen mit X-Noirdoc-Tags ist die automatische Tag-Anlage ausgeschaltet (Statuscode 403); auf /v1/tags/{name} antwortet das Gateway mit Statuscode 404. |
| 403 | tag_disabled | Ein in X-Noirdoc-Tags genanntes Tag ist deaktiviert. |
| 403 | tag_limit_exceeded | Die Organisation hat die Obergrenze von 1.000 Request-Tags erreicht. |
| 403 | insufficient_key_permissions | Dem API-Schlüssel fehlt die Berechtigung für /v1/tags (can_manage_tags) oder /v1/shield/policy (can_manage_shield), ein Schlüssel mit fest aktiviertem Shield (shield_mode: on) versucht die Shield-Richtlinie oder shield_mode eines Tags abzuschwächen, oder das Tag soll weiter reichende Modelle, Anbieter oder Compliance-Regeln erhalten als der aufrufende Schlüssel selbst besitzt. |
| 403 | model_not_allowed_for_tag | Das Modell gehört nicht zu den erlaubten Modellen eines in X-Noirdoc-Tags genannten Tags. |
| 403 | provider_not_allowed_for_tag | Die Einschränkungen eines in X-Noirdoc-Tags genannten Tags (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. |
| 409 | tag_already_exists | Ein Tag mit diesem Namen existiert in der Organisation bereits. |
| 409 | tag_has_spend_history | Für das Tag wurden bereits Kosten verbucht; es lässt sich deshalb nicht endgültig löschen. |
| 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. |
Modelle und Preise per API.
GET https://api.noirdoc.de/v1/models
Liefert sortiert nach id jede Modell-ID genau einmal, die der aufrufende Schlüssel unter Berücksichtigung von § 203 StGB, Startguthaben, Schlüsselregeln und optionalem X-Noirdoc-Tags nutzen darf (eigene BYOK-Routen haben Vorrang vor verwalteten Routen; ein Aufruf über die falsche Endpunkt-Familie oder das falsche API-Format endet mit 400 wrong_endpoint_for_model):
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
for model in client.models.list():
print(model.id, model.owned_by)import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
for await (const model of client.models.list()) {
console.log(model.id, model.owned_by);
}curl https://api.noirdoc.de/v1/models \
-H "Authorization: Bearer $NOIRDOC_API_KEY"{
"object": "list",
"data": [
{
"id": "qwen3.8-27b",
"object": "model",
"owned_by": "platform",
"display_name": "Qwen 3.8 27B",
"endpoint_family": "chat",
"legacy_public_id": null
}
]
}owned_by unterscheidet eigene BYOK-Routen (“personal”) von verwalteten Routen (“platform”); endpoint_family ist “chat”, “embeddings”, “rerank”, “stt”, “tts” oder “image_gen” (modellfreie Endpunkte wie /v1/shield, /v1/files, /v1/skills und /v1/tags stehen nicht in der Liste).
GET https://api.noirdoc.de/v1/prices
Öffentlicher Endpunkt ohne Authentifizierung: listet alle aktiven verwalteten Routen mit vollständigem Preis (eine Zeile je Modell und Anbieter, nie BYOK) samt starter_allowed sowie auf oberster Ebene den Pauschalpreis von Noirdoc Shield:
import httpx
payload = httpx.get("https://api.noirdoc.de/v1/prices").json()
prices = payload["data"]
shield_price = payload["shield"]const res = await fetch("https://api.noirdoc.de/v1/prices");
const { data: prices, shield: shieldPrice } = await res.json();curl https://api.noirdoc.de/v1/prices{
"object": "list",
"data": [
{
"public_id": "qwen3.8-27b",
"legacy_public_id": null,
"provider_slug": "aki-io",
"provider_display_name": "AKI.IO",
"endpoint_family": "chat",
"price_input": 0.3,
"price_output": 2.2,
"price_cache_read": null,
"price_cache_write": null,
"price_cache_write_1h": null,
"long_context_threshold": null,
"price_input_long": null,
"price_output_long": null,
"price_cache_read_long": null,
"price_cache_write_long": null,
"price_unit": "per1MTokens",
"price_currency": "EUR",
"starter_allowed": true
}
],
"shield": {
"price_input": "0.40",
"price_unit": "per1MTokens",
"currency": "EUR",
"price_currency": "EUR"
}
}Die Zahlen im Beispiel zeigen nur das Schema; verbindliche aktuelle Euro-Preise (inklusive Prompt-Cache und Langkontext-Stufen ab long_context_threshold) liefert der Endpunkt selbst.
price_unit | Bedeutung | Endpunkt-Familie & gefüllte Preisfelder |
|---|---|---|
per1MTokens | pro 1 Mio. Tokens | Chat (price_input, price_output, optional Cache & *_long), Embeddings, Rerank und Noirdoc Shield (price_input) |
per1MChars | pro 1 Mio. Zeichen Eingabetext | Sprachausgabe tts (price_input) |
perRequest | pro erfolgreicher Anfrage (unabhängig von der Dokumentanzahl) | Rerank (price_input) |
perMinute | pro Minute Audio (anteilig berechnet) | Transkription stt (price_input oder price_output) |
perImage | pro erzeugtem Bild | Bilder image_gen (price_output) |
perMpx | pro angefangenem Megapixel (1024 × 1024 Pixel) je Bild | Bilder image_gen (price_output) |
perFirstMpx | erstes Megapixel in price_output; jedes weitere Megapixel optional in price_input | Bilder image_gen (price_output, optional price_input) |