API — Referenz

Bazowy URL: https://modwall.dev. Wszystkie odpowiedzi w formacie JSON. Maszynowo: openapi.json.

Uwierzytelnianie

Klucz serwerowy w nagłówku każdego żądania:

Authorization: Bearer sk_live_...

Klucze tworzysz i odwołujesz w panelu. To sekret — trzymaj go po stronie serwera, nigdy w kodzie frontendu (do przeglądarki służy widget).

Oceń obraz

POST /v1/moderate

Body: multipart/form-data.

Pole	Art	Opis
`image`	plik	Obraz (wymagany). Alias: `file`.
`reference`	tekst	Opcjonalne ID treści u Ciebie — trafia do kolejki HITL.
`image_url`	tekst	Opcjonalny URL podglądu na Twojej infrze — do kolejki HITL.

Parametr zapytania:

Param	Opis
`?threshold=0.8`	Nadpisuje próg blokady na to żądanie. Decyzja jest wtedy binarna (`allow`/`block`), bez pasma `review`.

Odpowiedź 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"
}

Pole	Znaczenie
`decision`	Akcja dla Ciebie, wg trybu profilu: `allow` / `review` / `block`. W trybie `monitor` zawsze `allow`.
`recommended_action`	Surowa rekomendacja modelu, niezależna od trybu. W `monitor` pokazuje, co modwall by zrobił.
`categories`	Score per kategoria. `nsfw` zawsze; `weapon` / `violence` (beta) tylko, gdy włączysz je w profilu klucza. Decyduje najostrzejsza włączona kategoria (progi per kategoria w panelu).
`blocked_by`	Kategorie, które przekroczyły swój próg blokady.
`profile`	Nazwa profilu moderacji, który podjął decyzję (przypinasz profil do klucza w panelu — inna polityka per serwis).
`mode`	Aktywny tryb profilu: `monitor` / `review` / `enforce`.
`model_version`	Wersja modelu, która policzyła wynik.

scores zwracamy zawsze surowe; decision i tryb liczymy wg Twojej polityki. Znaczenie samych decyzji (allow/review/block) i tabela trybów — w Polityce.

Oceń tekst

POST /v1/moderate-text

Body: JSON { "text": "…" } (opcjonalnie reference, image_url do kolejki). Wymaga zakresu treść lub obie w planie. Model multilingual (rozumie polski); zwraca surowe score i kategorie.

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 to score toksyczności (multilingual, rozumie polski). categories zwraca surowe etykiety modelu (obecnie toxic; pole jest rozszerzalne pod kolejne modele/kategorie). decision i tryby działają identycznie jak dla obrazów (monitor/review/enforce).

Zgłoś treść (warstwa reaktywna)

POST /v1/report

Body: reference (wymagane), opcjonalnie image_url. Po przekroczeniu progu zgłoszeń z polityki treść trafia do kolejki HITL. Nie wywołuje modelu i nie liczy się do limitu.

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

Status pozycji kolejki

GET /v1/review/{id}

Zwraca decyzję moderatora dla pozycji kolejki (np. po review_id z /v1/moderate).

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

status: pending / approved / rejected.

Błędy

Kod	Znaczenie
`400`	`no_image` / `no_reference` — brak wymaganego pola.
`401`	Brak lub nieprawidłowy klucz.
`402`	`quota_exceeded` — wyczerpany limit planu (reset miesięczny).
`403`	`capability_required` — plan nie obejmuje tego typu treści (obrazy/tekst).
`413`	`image_too_large` — obraz powyżej limitu.
`429`	`rate_limited` — zbyt wiele żądań w krótkim czasie.
`503`	`inference_unavailable` — silnik chwilowo niedostępny.

Fail-open: przy 503 Ty decydujesz o zachowaniu zapasowym — zalecane skierowanie treści do ręcznej moderacji zamiast cichego przepuszczenia.