Der Batch-Endpunkt lässt bis zu 20 Texte in einem einzigen POST durch die Telm-Anti-Spam-Engine laufen und liefert für jeden ein Urteil zurück. Er ist nur regelbasiert (keine KI-Ebene) und ab dem Pro-Plan verfügbar. Das Kontingent wird pro Element berechnet, sodass ein Batch von zehn Texten zehn Aufrufe verbraucht. Für einen einzelnen Text mit optionaler KI-Prüfung verwenden Sie den regulären Spam-Check-Endpunkt.
1Was die Stapel-Spam-Prüfung macht
Mit der Batch-Spam-Prüfung bewerten Sie viele Texte auf einmal, statt eine Anfrage pro Nachricht zu stellen. Sie senden einen POST an /spam/check-batch mit einem Array von Elementen und erhalten ein Array von Urteilen in derselben Reihenfolge zurück — ideal, um einen Rückstau von Nachrichten zu klassifizieren, einen Kommentar-Feed zu moderieren oder die Erkennungsqualität über eine Stichprobe zu bewerten.
Der Stapel nutzt dieselbe Regel-Engine, die Live-Gruppen schützt, führt aber die KI-Stufe nicht aus, was jede Anfrage schnell und vorhersehbar hält. Wenn Sie die KI-Prüfung benötigen, nutzen Sie den einzelnen Spam-Prüf-Endpunkt mit aktivierter KI-Option, jeweils einen Text.
- Endpunkt: POST /api/public/v1/spam/check-batch.
- Bewertet bis zu 20 Texte pro Anfrage, Urteile werden in Eingabereihenfolge zurückgegeben.
- Nur regelbasiert: Die KI-Stufe wird im Stapelmodus nicht ausgeführt.
2Anfrageformat
Der Anfrage-Body ist ein JSON-Objekt mit einem items-Array. Jedes Element hat ein erforderliches text-Feld und ein optionales context-Objekt, das widerspiegelt, was die Live-Engine sieht — die group_id, die user_telegram_id des Absenders, ob der Absender ein neuer Benutzer ist, den username und Flags wie allow_sales und crypto_community.
Wenn ein Element eine group_id in seinem Kontext enthält, wendet die Prüfung die benutzerdefinierten Regeln und Einstellungen dieser Gruppe an, sodass Ihr Konto Administrator dieser Gruppe sein muss, sonst wird die gesamte Anfrage abgelehnt. Lassen Sie den Gruppenkontext weg, um stattdessen gegen das globale Regelwerk zu bewerten.
- Feld auf oberster Ebene: items — ein Array von einem bis zwanzig Einträgen.
- Jedes Element: text (erforderlich) und ein optionales context-Objekt.
- Der context kann group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community tragen.
- Ein Gruppen-context erfordert, dass Sie diese Gruppe verwalten.
3Antwortformat
Die Antwort ist ein JSON-Objekt mit einem results-Array — ein Urteil pro Eingabeelement, in derselben Reihenfolge — und einem quota-Objekt, das Ihre Verbrauchszahl, das Tageslimit und den Rücksetzzeitpunkt zeigt.
Jedes Urteil nennt Ihnen die Klassifizierung und den Grund. Das verdict-Feld ist eines von spam, suspicious oder clean. Daneben erhalten Sie einen numerischen score und confidence, eine recommended_action (eines von none, review, warn, mute, kick, ban oder delete), eine Liste von categories, menschenlesbare reasons, die Namen der matched_rules und eine signals-Map mit den einzelnen Bewertungsbeiträgen.
- results — ein Urteil pro Element, in Eingabereihenfolge.
- verdict — spam, suspicious oder clean.
- Jedes Urteil hat außerdem score, confidence, recommended_action, categories, reasons, matched_rules und signals.
- quota — used, limit und reset_at, im Body zurückgegeben.
4Limits und Kontingentkosten
Ein Stapel ist auf 20 Elemente pro Anfrage begrenzt, und jeder Text ist auf 10.000 Zeichen beschränkt. Auch der gesamte Anfrage-Body hat eine Größenobergrenze, sodass sehr große Payloads vor der Verarbeitung abgelehnt werden. Wenn Sie mehr als 20 Texte haben, verteilen Sie sie auf mehrere Anfragen.
Das Kontingent wird pro Element berechnet, nicht pro Anfrage: Ein Stapel von zehn Texten verbraucht zehn Aufrufe aus Ihrem Tageskontingent. Dies ist dasselbe Budget, das in API-Ratenlimits und Kontingente beschrieben wird, und die Antwort trägt die üblichen X-Quota-Limit-, X-Quota-Used- und X-Quota-Reset-Header.
- Bis zu 20 Elemente pro Anfrage; bis zu 10.000 Zeichen pro Text.
- Die Kontingentkosten entsprechen der Anzahl der Elemente im Stapel.
- Es gelten die Standard-X-Quota-*-Header, plus ein quota-Objekt im Body.
5Fehler und Timeouts
Fehlerhafte Anfragen geben 400 mit einem bestimmten Code zurück: ein leeres items-Array, ein Stapel über dem Elementlimit, ein fehlender text oder ein text über dem Längenlimit. Ein Gruppen-context, den Sie nicht verwalten, gibt für dieses Element 404 zurück. Ein Plan unterhalb von Pro gibt 403 mit einem plan_required-Code zurück.
Wenn die Verarbeitung eines Stapels sein Zeitbudget überschreitet, gibt die API 504 zurück und erstattet das Kontingent für die Elemente, die sie nicht abgeschlossen hat, sodass Ihnen nur abgeschlossene Arbeit berechnet wird. Wenn Sie Timeouts sehen, senden Sie kleinere Stapel.
- 400 — empty_batch, batch_too_large, missing_text oder text_too_long.
- 404 — eine Gruppe in einem Element-context wird nicht von Ihnen verwaltet.
- 403 plan_required — der Stapel-Endpunkt erfordert Pro oder höher.
- 504 timeout — der Stapel lief zu lange; nicht abgeschlossene Elemente werden erstattet. Senden Sie weniger Texte.