배치 엔드포인트는 하나의 POST로 최대 20개의 텍스트를 Telm 안티스팸 엔진에 통과시켜 각각에 대한 판정을 반환합니다. 규칙 전용(AI 레벨 없음)이며 Pro 요금제 이상에서 사용할 수 있습니다. 할당량은 항목당 부과되므로 텍스트 열 개짜리 배치는 열 호출을 씁니다. 선택적 AI 검사가 필요한 단일 텍스트에는 일반 스팸 검사 엔드포인트를 사용하세요.
1배치 스팸 검사가 하는 일
배치 스팸 검사를 사용하면 메시지마다 한 요청씩 보내는 대신 많은 텍스트를 한 번에 채점할 수 있습니다. 항목 배열을 담아 /spam/check-batch 로 POST를 보내면 같은 순서로 판정 배열을 돌려받습니다. 밀린 메시지 분류, 댓글 피드 모더레이션, 표본에 대한 감지 품질 평가에 이상적입니다.
배치는 실시간 그룹을 보호하는 것과 같은 규칙 엔진을 실행하지만 AI 레벨은 실행하지 않아, 각 요청을 빠르고 예측 가능하게 유지합니다. AI 검사가 필요하면 AI 옵션을 켠 단일 스팸 검사 엔드포인트를 한 번에 텍스트 하나씩 사용하세요.
- 엔드포인트: POST /api/public/v1/spam/check-batch.
- 요청당 최대 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 배열 — 입력 항목당 하나의 판정, 같은 순서 — 과, 사용 수·일일 한도·초기화 시각을 보여주는 quota 객체를 가진 JSON 객체입니다.
각 판정은 분류와 그 이유를 알려줍니다. verdict 필드는 spam, suspicious, clean 중 하나입니다. 그와 함께 숫자 score와 confidence, recommended_action(none, review, warn, mute, kick, ban, delete 중 하나), categories 목록, 사람이 읽을 수 있는 reasons, 매칭된 matched_rules 이름, 그리고 개별 채점 기여를 담은 signals 맵을 받습니다.
- results — 항목당 하나의 판정, 입력 순서.
- verdict — spam, suspicious 또는 clean.
- 각 판정에는 score, confidence, recommended_action, categories, reasons, matched_rules, signals도 있습니다.
- quota — used, limit, reset_at, 본문에 그대로 반영.
4제한과 할당량 비용
배치는 요청당 20개 항목으로 제한되며, 각 텍스트는 10,000자로 제한됩니다. 전체 요청 본문에도 크기 상한이 있어, 매우 큰 페이로드는 처리 전에 거부됩니다. 텍스트가 20개보다 많으면 여러 요청으로 나누세요.
할당량은 요청당이 아니라 항목당 부과됩니다. 텍스트 열 개짜리 배치는 일일 할당량에서 열 호출을 씁니다. 이는 API 속도 제한 및 할당량에서 설명한 것과 같은 예산이며, 응답에는 통상적인 X-Quota-Limit, X-Quota-Used, X-Quota-Reset 헤더가 담깁니다.
- 요청당 최대 20개 항목, 텍스트당 최대 10,000자.
- 할당량 비용은 배치의 항목 수와 같습니다.
- 표준 X-Quota-* 헤더가 적용되며, 본문에 quota 객체가 추가됩니다.
5오류와 타임아웃
잘못된 요청은 구체적인 코드와 함께 400을 반환합니다. 빈 items 배열, 항목 한도를 넘은 배치, 누락된 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 — 배치가 너무 오래 걸렸습니다. 끝내지 못한 항목은 환불됩니다. 더 적은 텍스트를 보내세요.