API — Referenz

Basis-URL: https://modwall.dev. Alle Antworten im JSON-Format. Maschinenlesbar: openapi.json.

Authentifizierung

Der Server-Schlüssel im Header jeder Anfrage:

Authorization: Bearer sk_live_...

Schlüssel legen Sie im Dashboard an und widerrufen sie dort. Er ist ein Geheimnis — bewahren Sie ihn serverseitig auf, nie im Frontend-Code (für den Browser gibt es das Widget).

Bild bewerten

POST /v1/moderate

Body: multipart/form-data.

Feld	Art	Beschreibung
`image`	Datei	Bild (erforderlich). Alias: `file`.
`reference`	Text	Optionale ID des Inhalts auf Ihrer Seite — sie geht in die HITL-Warteschlange.
`image_url`	Text	Optionale Vorschau-URL in Ihrer Infrastruktur — für die HITL-Warteschlange.

Query-Parameter:

Param	Beschreibung
`?threshold=0.8`	Überschreibt die Sperrschwelle für diese Anfrage. Die Entscheidung ist dann binär (`allow`/`block`), ohne `review`-Bereich.

Antwort 200:

{
  "scores": { "nsfw": 0.97, "safe": 0.03 },
  "categories": { "nsfw": 0.97, "weapon": 0.12 },   // weapon/violence: BETA, wg profilu
  "blocked_by": ["nsfw"],
  "decision": "block",
  "recommended_action": "block",
  "mode": "enforce",
  "threshold": 0.8,
  "profile": "Domyślny",
  "model_version": "falconsai-int8-1",
  "review_id": 42        // tylko gdy decision = "review"
}

Feld	Bedeutung
`decision`	Die Aktion für Sie, gemäß dem Modus des Profils: `allow` / `review` / `block`. Im Modus `monitor` immer `allow`.
`recommended_action`	Die rohe Empfehlung des Modells, unabhängig vom Modus. Im Modus `monitor` zeigt sie, was modwall tun würde.
`categories`	Score je Kategorie. `nsfw` immer; `weapon` / `violence` (beta) nur, wenn Sie sie im Profil des Schlüssels aktivieren. Es entscheidet die strengste aktivierte Kategorie (Schwellenwerte je Kategorie im Dashboard).
`blocked_by`	Kategorien, die ihre Sperrschwelle überschritten haben.
`profile`	Name des Moderationsprofils, das die Entscheidung getroffen hat (Sie heften ein Profil im Dashboard an einen Schlüssel — eine andere Richtlinie je Dienst).
`mode`	Aktiver Modus des Profils: `monitor` / `review` / `enforce`.
`model_version`	Die Modellversion, die das Ergebnis berechnet hat.

scores liefern wir immer roh; decision und Modus berechnen wir gemäß Ihrer Richtlinie. Die Bedeutung der Entscheidungen selbst (allow/review/block) und die Modus-Tabelle finden Sie unter Richtlinie.

Text bewerten

POST /v1/moderate-text

Body: JSON { "text": "…" } (optional reference, image_url für die Warteschlange). Erfordert im Tarif den Umfang Text oder beides. Mehrsprachiges Modell (versteht Deutsch); liefert rohe Scores und Kategorien.

curl -X POST https://modwall.dev/v1/moderate-text \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"treść do sprawdzenia"}'

{
  "scores": { "unsafe": 0.94, "safe": 0.06 },
  "categories": { "toxic": 0.94 },
  "decision": "block",
  "recommended_action": "block",
  "mode": "enforce",
  "threshold": 0.8,
  "model_version": "xlmr-tox-int8-1"
}

unsafe ist der Toxizitäts-Score (mehrsprachig, versteht Deutsch). categories liefert die rohen Labels des Modells (derzeit toxic; das Feld ist für weitere Modelle/Kategorien erweiterbar). decision und die Modi funktionieren genau wie bei Bildern (monitor/review/enforce).

Inhalt melden (reaktive Ebene)

POST /v1/report

Body: reference (erforderlich), optional image_url. Wird die in der Richtlinie festgelegte Meldeschwelle überschritten, geht der Inhalt in die HITL-Warteschlange. Ruft das Modell nicht auf und zählt nicht auf Ihr Limit.

{ "reference": "post-123", "reports": 2, "escalated": true }

Status eines Warteschlangeneintrags

GET /v1/review/{id}

Liefert die Entscheidung des Moderators zu einem Warteschlangeneintrag (etwa anhand der review_id aus /v1/moderate).

{ "id": 42, "status": "approved", "reason": "score", "reference": "post-123" }

status: pending / approved / rejected.

Fehler

Code	Bedeutung
`400`	`no_image` / `no_reference` — ein Pflichtfeld fehlt.
`401`	Schlüssel fehlt oder ist ungültig.
`402`	`quota_exceeded` — Tariflimit erschöpft (monatlicher Reset).
`403`	`capability_required` — der Tarif deckt diesen Inhaltstyp nicht ab (Bilder/Text).
`413`	`image_too_large` — Bild über dem Größenlimit.
`429`	`rate_limited` — zu viele Anfragen in kurzer Zeit.
`503`	`inference_unavailable` — die Engine ist vorübergehend nicht erreichbar.

Fail-open: Bei 503 entscheiden Sie über das Ausweichverhalten — empfohlen ist, den Inhalt zur manuellen Moderation zu leiten, statt ihn stillschweigend durchzulassen.