バッチ エンドポイント は、最大 20 件のテキストを 1 回の POST で Telm アンチスパム エンジンに通し、それぞれの評決を返します。ルールのみ(AI レベルなし)で、Pro プラン以上で利用できます。枠は項目ごとに課金されるので、10 件のテキストのバッチは 10 呼び出し使います。任意の AI チェック付きの単一テキストには、通常のスパム判定エンドポイントを使ってください。
1バッチ スパム判定がすること
バッチ スパム判定を使うと、メッセージごとに 1 リクエストを作る代わりに、多くのテキストを一度に採点できます。項目の配列とともに /spam/check-batch へ POST を送ると、同じ順序で評決の配列が返ります。メッセージのバックログの分類、コメント フィードのモデレーション、サンプルでの検出品質の評価に最適です。
バッチは、稼働中のグループを守るのと同じルール エンジンを走らせますが、AI レベルは走らせないため、各リクエストが速く予測可能に保たれます。AI チェックが必要なら、AI オプションを有効にした単一の スパム判定エンドポイント を、1 件ずつ使ってください。
- エンドポイント:POST /api/public/v1/spam/check-batch。
- 1 リクエストで最大 20 件のテキストを採点し、評決は入力順で返ります。
- ルールのみ:バッチ モードでは AI レベルは走りません。
2リクエスト形式
リクエスト本文は、items 配列を持つ JSON オブジェクトです。各項目は必須の text フィールドと、稼働中のエンジンが見るものを反映する任意の context オブジェクト、つまり group_id、送信者の user_telegram_id、送信者が新規ユーザーか、username、そして allow_sales や crypto_community といったフラグを持ちます。
項目が context に group_id を含むと、チェックはそのグループのカスタム ルールと設定を適用するので、あなたのアカウントはそのグループの管理者でなければならず、そうでなければリクエスト全体が拒否されます。代わりにグローバルなルールセットに照らして採点するには、グループの context を省いてください。
- トップレベルのフィールド:items — 1 から 20 のエントリの配列。
- 各項目:text(必須)と任意の context オブジェクト。
- context は group_id、user_telegram_id、is_new_user、username、allow_sales、crypto_community を持てます。
- グループの context には、あなたがそのグループを管理していることが必要です。
3レスポンス形式
レスポンスは、results 配列(入力項目ごとに 1 つの評決、同じ順序)と、使用数・日次上限・リセット時刻を示す quota オブジェクトを持つ JSON オブジェクトです。
各評決は、分類と理由を伝えます。verdict フィールドは spam、suspicious、clean のいずれかです。それに加えて、数値の score と confidence、recommended_action(none、review、warn、mute、kick、ban、delete のいずれか)、categories のリスト、人間可読な reasons、一致した matched_rules の名前、そして個々の採点の寄与を持つ signals マップを得ます。
- results — 項目ごとに 1 つの評決、入力順。
- verdict — spam、suspicious、clean。
- 各評決は score、confidence、recommended_action、categories、reasons、matched_rules、signals も持ちます。
- quota — used、limit、reset_at。本文に反映されます。
4制限と枠のコスト
バッチはリクエストごとに 20 項目に上限が設けられ、各テキストは 10,000 文字に制限されます。リクエスト本文全体にもサイズ上限があるので、非常に大きなペイロードは処理前に拒否されます。20 を超えるテキストがある場合は、複数のリクエストに分けてください。
枠はリクエストごとではなく項目ごとに課金されます。10 件のテキストのバッチは、日次枠から 10 呼び出し使います。これは API のレート制限と枠 で説明したのと同じ予算で、レスポンスは通常の X-Quota-Limit、X-Quota-Used、X-Quota-Reset ヘッダーを持ちます。
- リクエストごとに最大 20 項目。テキストごとに最大 10,000 文字。
- 枠のコストはバッチ内の項目数に等しくなります。
- 標準の X-Quota-* ヘッダーが適用され、本文に quota オブジェクトも付きます。
5エラーとタイムアウト
不正なリクエストは、具体的なコードとともに 400 を返します。空の items 配列、項目上限を超えるバッチ、欠けた text、長さ上限を超える text です。あなたが管理しないグループの context は、その項目に 404 を返します。Pro 未満のプランは plan_required コードとともに 403 を返します。
バッチの処理が時間予算を超えると、API は 504 を返し、終わらなかった項目の枠を払い戻すので、完了した作業の分だけ課金されます。タイムアウトが見えたら、より小さなバッチを送ってください。
- 400 — empty_batch、batch_too_large、missing_text、text_too_long。
- 404 — 項目の context のグループが、あなたが管理するものではない。
- 403 plan_required — バッチ エンドポイントには Pro 以上が必要。
- 504 timeout — バッチが長く走りすぎました。未完了の項目は払い戻されます。より少ないテキストを送ってください。