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:

EbeneEinstellungWirkung & Ort im Portal
OrganisationShield-Richtlinie & SchutzfilterStandardmodus (default_off, default_on, enforced), fünf Filter und custom_patterns unter Models → Shield (siehe Noirdoc Shield).
OrganisationErweiterte Einstellungenallow_stored_responses (Responses-API-Speicherung, neu: aus) und allow_file_content (Dateien/Bilder/Audio, Standard: an) unter Models → Shield.
OrganisationEigene Anbieter (BYOK), § 203 & GuthabenBYOK-Schlüssel mit Vorrang unter Models → Provider, §-203-Einstufung auf Erste Schritte (siehe Anbieter, Routing & § 203) sowie Kontostand unter Abrechnung.
API-SchlüsselModelle, Anbieter & shield_modeModellauswahl, Datenresidenz, CLOUD Act, § 203, Anbieterliste sowie Shield (inherit, on, off) unter Models → API-Schlüssel.
API-SchlüsselBudget (€)Optionales Ausgabenlimit je Schlüssel mit Rücksetzintervall (402 key_budget_exhausted).
API-Schlüsselcan_manage_shieldShield-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üsselcan_manage_tagsTag-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-prod und chatbot-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:

Python
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"
TypeScript
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
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'
JSON
{
  "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).

AspektRegel
RücksetzintervalleTä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 KostenBepreiste 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 vorabChat/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-Tags und Aufrufe auf /v1/tags mit 403 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):

Python
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"
    },
)
TypeScript
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
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."}]
  }'
JSON
{
  "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 & PfadVerhalten (can_manage_tags erforderlich)
GET /v1/tagsListet die Tags deiner Organisation (optional mit limit, offset und Suchfilter q).
POST /v1/tagsLegt ein neues Tag an (201 Created); existiert der Name bereits, antwortet das Gateway mit 409 tag_already_exists.
GET | PUT /v1/tags/_defaultLiest 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:

BereichRegeln
AbrechnungseinheitenChat, 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 €).
StartguthabenEinmalig 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 AufladungNur 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 & KartenwechselNach 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):

Python
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)
TypeScript
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
curl https://api.noirdoc.de/v1/models \
  -H "Authorization: Bearer $NOIRDOC_API_KEY"
JSON
{
  "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:

Python
import httpx

payload = httpx.get("https://api.noirdoc.de/v1/prices").json()
prices = payload["data"]
shield_price = payload["shield"]
TypeScript
const res = await fetch("https://api.noirdoc.de/v1/prices");
const { data: prices, shield: shieldPrice } = await res.json();
curl
curl https://api.noirdoc.de/v1/prices
JSON
{
  "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_unitBedeutungEndpunkt-Familie & gefüllte Preisfelder
per1MTokenspro 1 Mio. TokensChat (price_input, price_output, optional Cache & *_long), Embeddings, Rerank und Noirdoc Shield (price_input)
per1MCharspro 1 Mio. Zeichen EingabetextSprachausgabe tts (price_input)
perRequestpro erfolgreicher Anfrage (unabhängig von der Dokumentanzahl)Rerank (price_input)
perMinutepro Minute Audio (anteilig berechnet)Transkription stt (price_input oder price_output)
perImagepro erzeugtem BildBilder image_gen (price_output)
perMpxpro angefangenem Megapixel (1024 × 1024 Pixel) je BildBilder image_gen (price_output)
perFirstMpxerstes Megapixel in price_output; jedes weitere Megapixel optional in price_inputBilder image_gen (price_output, optional price_input)