콘텐츠 검수 API

텍스트 하나와 이미지 최대 4장을 보내면 바로 활용할 수 있는 판정을 받습니다. 7개 카테고리마다 0~1 점수, 각 카테고리의 기준선 초과 여부, 그리고 allow, review, block 중 하나의 최종 판정이 반환됩니다. 사용자가 쓰거나 모델이 만든 콘텐츠를 검사하는 데 맞춰 설계되었습니다. 게시 전의 댓글, 모델에 전달되기 전의 프롬프트나 참조 이미지, 사용자에게 보이기 전의 답변이나 생성 이미지를 검사하세요.

POST https://api.beatapi.io/v1/moderations

요청과 응답이 OpenAI Moderation API를 따르므로, 공식 OpenAI SDK에서 기본 URL과 API 키만 바꾸면 됩니다. 2026-10-13에 공식 Python SDK(openai 3.29.0)로 텍스트와 이미지 모두 검증했습니다.

응답하는 모델. model은 선택 사항입니다. model이 없거나 OpenAI의 검수 모델 이름을 보낸 요청에는 beat-moderation-2.0이 응답합니다. beat-moderation-1.0과 beat-moderation-vision-1.0은 이름을 지정했을 때만 응답하며, 이전 제한(텍스트 하나, 이미지 하나 또는 각각 하나씩)과 자체 기준선을 유지합니다. 2026-10-13 이전에 쓰던 이름 beat-moderation-1과 beat-moderation-vision-1도 여전히 이전 모델로 연결됩니다. 어느 모델이 응답했는지는 응답의 model에 표시됩니다.

Beat Moderation 2.0

beat-moderation-2.0이 기본 모델입니다. 텍스트 하나와 이미지 최대 4장을 한 번의 호출로 함께 판정합니다. 어느 하나에라도 해당하면 그 카테고리가 적용되므로, 무해한 이미지가 유해한 캡션을 가리지 못하고 무해한 캡션도 유해한 이미지를 가리지 못합니다. 엔드포인트, 요청 형식, 응답 형식은 이전 모델과 같습니다. 텍스트만 보내거나 텍스트와 이미지를 함께 보내세요.

curl https://api.beatapi.io/v1/moderations \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "beat-moderation-2.0",
    "input": [
      {"type": "text", "text": "Product photos for my shop listing."},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo-1.jpg"}},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo-2.jpg"}}
    ]
  }'

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["BEATAPI_API_KEY"],
    base_url="https://api.beatapi.io/v1",
)
resp = client.moderations.create(
    model="beat-moderation-2.0",
    input=[
        {"type": "text", "text": "Product photos for my shop listing."},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo-1.jpg"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo-2.jpg"}},
    ],
)
print(resp.model)               # "beat-moderation-2.0"
print(resp.results[0].verdict)  # "allow", "review" or "block"

입력

• 텍스트 하나와 이미지 최대 4장. 텍스트 파트는 최대 하나(8,000자 이하), image_url 파트는 최대 4개입니다.
• 링크 또는 인라인. 이미지는 BeatAPI가 가져오는 공개 http(s) 링크(최대 2,048자) 또는 base64 데이터 URL입니다.
• PNG, JPEG, WebP 또는 GIF(첫 프레임), 각각 최대 16 MB, 픽셀 크기 제한 없음. BeatAPI가 모델에 맞게 각 이미지 크기를 조정하고 휴대폰 사진의 방향을 바로잡습니다.
• 2.0의 응답에는 "model": "beat-moderation-2.0"과 "policy_version": "2026-10-15"가 있으며, 이미지를 보냈다면 category_applied_input_types는 ["text", "image"]입니다. 나머지는 아래에 설명한 응답과 같습니다.

400으로 거부되는 경우

일부만 판정하는 경우는 없으며, 400으로 거부된 요청은 과금되지 않습니다.

기준선과 판정

카테고리는 0.6에서 플래그되며(판정은 block), 예외는 다음과 같습니다. verdict는 카테고리 기준선보다 0.25 낮은 점수부터 review이며, 0.15보다 낮아지지 않습니다.

더 엄격하거나 느슨한 기준이 필요하면 category_scores에 자체 기준선을 적용하세요.

가격과 토큰 규모

입력 1M 토큰당 $0.08, 출력은 무료입니다. 측정된 규모:

모든 응답의 usage.input_tokens에 호출에서 센 토큰 수가 정확히 표시됩니다. 텍스트와 이미지는 로그에 남지 않습니다.

빠른 시작

curl https://api.beatapi.io/v1/moderations \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Forged ID cards and bank cards for sale, shipped within 24 hours. Message me for the price list."}'

아래 응답은 이 요청에 실제로 반환된 응답입니다.

{
  "id": "modr-task_untsppzSTLTDbt7Kw360kbf4ydPBYOAS",
  "model": "beat-moderation-2.0",
  "results": [
    {
      "flagged": true,
      "categories": {
        "sexual": false,
        "sexual/minors": false,
        "violence": false,
        "hate": false,
        "harassment": false,
        "self-harm": false,
        "illicit": true,
        "harassment/threatening": false,
        "hate/threatening": false,
        "illicit/violent": false,
        "self-harm/intent": false,
        "self-harm/instructions": false,
        "violence/graphic": false
      },
      "category_scores": {
        "sexual": 0,
        "sexual/minors": 0.01,
        "violence": 0.02,
        "hate": 0.01,
        "harassment": 0.02,
        "self-harm": 0.01,
        "illicit": 0.99,
        "harassment/threatening": 0,
        "hate/threatening": 0,
        "illicit/violent": 0,
        "self-harm/intent": 0,
        "self-harm/instructions": 0,
        "violence/graphic": 0
      },
      "category_applied_input_types": {
        "sexual": ["text"],
        "sexual/minors": ["text"],
        "violence": ["text"],
        "hate": ["text"],
        "harassment": ["text"],
        "self-harm": ["text"],
        "illicit": ["text"],
        "harassment/threatening": [],
        "hate/threatening": [],
        "illicit/violent": [],
        "self-harm/intent": [],
        "self-harm/instructions": [],
        "violence/graphic": []
      },
      "verdict": "block",
      "sexual_level": "none"
    }
  ],
  "policy_version": "2026-10-15",
  "usage": { "input_tokens": 1210 }
}

illicit이 0.99점으로 기준선 0.6을 넘었으므로 categories.illicit은 true, flagged는 true, verdict는 block입니다.

OpenAI SDK(Python)

클라이언트를 BeatAPI로 지정하고 평소처럼 moderations.create를 호출하세요. BeatAPI가 추가한 필드도 타입이 지정된 결과에서 읽을 수 있습니다.

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["BEATAPI_API_KEY"],
    base_url="https://api.beatapi.io/v1",
)
resp = client.moderations.create(
    input="Forged ID cards and bank cards for sale, shipped within 24 hours. Message me for the price list.",
)
result = resp.results[0]
# The values in the comments are the ones from the response above.
print(result.flagged)                  # True
print(result.verdict)                  # "block" (added by BeatAPI)
print(result.categories.illicit)       # True
print(result.category_scores.illicit)  # 0.99
print(result.sexual_level)             # "none" (added by BeatAPI)
print(resp.policy_version)             # "2026-10-12" (added by BeatAPI)

JavaScript

const text = "Forged ID cards and bank cards for sale, shipped within 24 hours. Message me for the price list.";
const response = await fetch("https://api.beatapi.io/v1/moderations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEATAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: text }),
});
if (!response.ok) {
  // A failed call judged nothing: do not let the content through.
  // On HTTP 429, wait the Retry-After seconds before retrying.
  throw new Error(`Moderation HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);
}
const moderation = await response.json();
const result = moderation.results?.[0];
if (!result || !["allow", "review", "block"].includes(result.verdict)) {
  throw new Error("Invalid moderation response; hold the content for review");
}
if (result.verdict === "block") {
  console.log("rejected", result.category_scores);
} else if (result.verdict === "review") {
  console.log("queued for a person", result.sexual_level, result.category_scores);
} else {
  console.log("allowed under policy", moderation.policy_version);
}

이미지

이미지는 OpenAI API와 같은 방식으로 input 배열에 image_url 파트로 넣습니다. 이미지만 보내거나, 관련 텍스트(프롬프트, 캡션)를 같은 배열에 text 파트로 함께 보내세요.

curl https://api.beatapi.io/v1/moderations \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"type": "text", "text": "Remove her clothes and make it a nude photo."},
      {"type": "image_url", "image_url": {"url": "https://beatapi.io/samples/ai-ecommerce-video-demo-poster.jpg"}}
    ]
  }'

이 요청의 이미지는 평범한 제품 포스터입니다. 이미지만 보내면 허용되지만, 이 프롬프트와 함께 보냈을 때 실제 응답은 verdict: "block"였고 sexual은 1, sexual_level: "explicit"였습니다. 이미지와 텍스트를 함께 판정하고 텍스트도 따로 채점하므로, 무해한 이미지가 그 이미지에 대한 유해한 요청을 가리지 못합니다.

resp = client.moderations.create(
    input=[
        {"type": "text", "text": "Change the background to a beach."},
        {"type": "image_url", "image_url": {"url": "https://example.com/upload.jpg"}},
    ],
)
print(resp.model)                # "beat-moderation-vision-1.0"
print(resp.results[0].verdict)   # "allow", "review" or "block"

• 링크 또는 인라인. image_url.url은 http(s) 링크 또는 data:image/jpeg;base64,... 같은 base64 데이터 URL입니다. 링크는 BeatAPI가 가져오므로 공개적으로 접근할 수 있어야 하며, 사설 주소로 연결되는 링크는 거부됩니다.
• PNG, JPEG 또는 WebP, 최대 4 MB, 16메가픽셀 이하. 형식은 데이터 URL의 표기가 아니라 파일 자체로 판별하며, 줄바꿈이 있거나 URL 안전 문자 집합을 쓰거나 패딩이 없는 base64도 받습니다.
• 호출당 이미지 한 장, 텍스트는 최대 하나(8,000자 이하).
• 이미지에 대한 응답에는 "model": "beat-moderation-vision-1.0", "policy_version": "2026-10-13", 그리고 ["image"](텍스트를 함께 보냈다면 ["text", "image"])인 category_applied_input_types가 있습니다. 나머지는 아래에 설명한 응답과 같습니다.
• 호출 한 번에 약 0.5초가 걸리며, 링크를 가져오는 시간이 더해집니다.

요청

응답

응답은 동기식입니다. HTTP 응답이 성공하면 판정이 담겨 있으며, 폴링할 필요가 없습니다.

카테고리

7개 카테고리를 OpenAI와 같은 이름으로 판정하며, 각각 0~1 점수를 매깁니다. 텍스트와 이미지에 같은 7개 카테고리가 적용됩니다.

OpenAI의 6개 하위 카테고리 키(harassment/threatening, hate/threatening, illicit/violent, self-harm/intent, self-harm/instructions, violence/graphic)는 타입이 지정된 SDK가 계속 동작하도록 포함되지만 따로 판정하지 않습니다. 항상 false이며 점수는 0, category_applied_input_types 목록은 비어 있습니다. 이 키로 규칙을 만들지 마세요.

기준선과 판정

판정하는 모든 카테고리에는 기준선이 있습니다. categories[k]는 해당 카테고리 점수를 기준선과 비교한 결과이며, 어느 카테고리든 점수가 기준선에 도달하면 flagged는 true입니다.

Beat Moderation 2.0은 자체 기준선이 있으며, 이 페이지 위쪽의 해당 섹션에 나와 있습니다. 위 표는 이름을 지정해 이전 모델을 쓸 때의 기준입니다.

sexual_level은 점수와 별개로 콘텐츠가 얼마나 성적인지 나타냅니다.

category_scores.sexual은 explicit 수준일 확률입니다. 암시적인 콘텐츠는 이 값이 낮게 나오고 대신 sexual_level: "suggestive"와 verdict: "review"로 나타나므로, 암시적인 콘텐츠가 중요하다면 이 두 필드를 확인하세요. 이미지와 텍스트를 함께 보내면 둘 중 높은 값이 표시됩니다.

이보다 엄격하거나 느슨한 기준이 필요하면 category_scores에 자체 기준선을 적용하세요.

policy_version은 점수를 산출한 정책을 나타냅니다. 정책 버전이 다른 점수끼리, 그리고 텍스트 모델과 이미지 모델의 점수끼리는 비교할 수 없으므로 점수를 저장할 때는 버전도 함께 저장하세요.

한도

이 제한은 이름을 지정해 이전 모델을 쓸 때 적용됩니다. Beat Moderation 2.0은 텍스트 하나와 이미지 최대 4장을 받으며, 제한은 이 페이지 위쪽의 해당 섹션에 있습니다.

• 호출당 텍스트 하나, 이미지 하나 또는 각각 하나씩. 텍스트나 이미지가 둘 이상이면 400으로 거부되며, 일부만 판정하지 않습니다. 항목마다 요청을 하나씩 보내세요.
• 텍스트는 최대 8,000자입니다. 더 긴 텍스트는 잘리지 않고 400으로 거부되므로 나눠서 보내세요. 길이는 UTF-16 코드 단위로 세므로 대부분의 이모지는 2자로 계산됩니다.
• 이미지는 PNG, JPEG 또는 WebP이며 최대 4 MB, 16메가픽셀입니다. 그 밖의 경우는 무엇이 잘못되었는지 알려 주는 400으로 거부됩니다.
• 오디오와 영상은 지원하지 않습니다.
• 동기식입니다. 스트리밍도 폴링할 작업도 없습니다. 서버 측 처리 시간은 텍스트가 약 0.2초, 이미지가 약 0.5초입니다.

오류

오류는 표준 BeatAPI 오류 형식(code, message, retryable, request_id, 그리고 429일 때 retry_after_seconds)을 사용합니다. 전체 표와 재시도 정책은 오류를 참고하세요. 이 엔드포인트의 오류 객체에는 OpenAI의 type과 param도 포함되므로(param은 항상 null) OpenAI SDK가 평소와 같은 예외를 발생시킵니다.

{
  "error": {
    "code": "bad_request",
    "message": "input is required: the text to moderate, an image, or one of each",
    "retryable": false,
    "request_id": "…",
    "type": "invalid_request_error",
    "param": null
  }
}

이미지에 대한 400 메시지:

손상되었거나 잘린 이미지는 이 검사를 통과한 뒤 모델에서 실패할 수 있습니다. 이 경우 파일이 손상되었을 수 있다는 메시지와 함께 503이 반환되며, 같은 파일로 재시도해도 다시 실패합니다.

첫 번째 표의 예외는 공식 Python SDK가 실제로 발생시킨 것입니다. 2026-10-12에 401, 402, 403, 429를(openai 2.48.0), 2026-10-13에 400과 503을 다시 확인했으며(openai 3.29.0), 503은 잘린 JPEG에 대한 것입니다.

실패한 호출은 아무것도 판정하지 않은 것이므로 오류를 “허용”으로 처리하지 마세요. 400으로 거부된 요청은 과금되지 않습니다.

과금

콘텐츠 검수는 입력 토큰에만 과금됩니다. 기본 모델 beat-moderation-2.0은 입력 1M 토큰당 $0.08**입니다. 이름을 지정해 이전 모델을 쓰면 텍스트는 **입력 1M 토큰당$0.065, 이미지가 포함된 요청은 입력 1M 토큰당 $0.23입니다. 세 모델 모두 가격 페이지에 있습니다.

이전 모델에서는 검수 정책이 호출마다 함께 전달되어 약 1,150토큰의 입력으로 계산되므로, 짧은 텍스트에도 최소 비용이 있습니다. 이미지는 크기와 관계없이 최대 약 1,000토큰이 추가됩니다.

이전 모델의 토큰 규모(2.0의 값은 이 페이지 위쪽의 해당 섹션 참고):

모든 응답의 usage.input_tokens에 호출에서 센 토큰 수가 정확히 표시되므로 호출별로 지출을 대조할 수 있습니다.

개인정보 보호

제출한 텍스트와 이미지는 요청 로그에 기록되지 않습니다. 텍스트 길이, 이미지 수, 점수, 정책 버전만 보관합니다. 링크로 보낸 이미지는 해당 요청을 위해 한 번만 가져옵니다.

하지 않는 것

• 분류기일 뿐 보증이 아닙니다. 명백한 위반은 안정적으로 잡아냅니다. 은어, 동음이의어, 위장한 스팸(특히 중국어)은 덜 안정적으로 잡습니다. 사용하기 전에 실제 콘텐츠로 테스트하세요.
• 경계선에 있는 이미지는 텍스트보다 판정이 덜 일관됩니다. 예술적 누드, 격투 스포츠, 역사 사진은 기준선 근처 점수를 받으며, 비슷한 이미지라도 allow, review 또는 block으로 나올 수 있습니다. 이미지 안에 그려진 텍스트(밈, QR 코드 광고)는 테스트에 포함하지 않았습니다.
• sexual/minors는 알려진 학대물에 대한 해시 매칭이나 법적 신고 의무를 대신하지 않습니다.
• 오디오와 영상은 검사하지 않습니다.
• 점수가 정확히 재현되지는 않습니다. 테스트에서 같은 호출끼리 최대 0.04까지 차이가 났으므로, 기준선 근처 점수를 받은 콘텐츠는 어느 쪽으로든 판정될 수 있습니다. 기준선 근처 점수는 경계 사례로 다루세요.

에이전트

에이전트는 Capabilities API를 통해 같은 검사를 사용할 수 있으며, 카탈로그에 model:beat-moderation-1.0과 model:beat-moderation-vision-1.0으로 등록되어 있습니다. Run 입력은 텍스트는 {"input": "…"}, 이미지는 {"image_url": "…", "input": "optional text"}이며, 결과 본문은 위와 같습니다. 이 경로의 오류는 type과 param이 없는 표준 오류 형식을 사용합니다.

Beat Moderation 2.0은 model:beat-moderation-2.0입니다. Run 입력은 {"input": "text", "image_urls": ["https://..."]}이며, 이미지 한 장은 image_url로도 보낼 수 있습니다.