2026/10/07

이미지 모더레이션 API 튜토리얼: Python·JavaScript 예제

이미지 모더레이션 API의 작동 방식: 이미지에 적용되는 유해 카테고리, URL 전용 입력, 이미지당 과금, 점수 임계값, 그리고 Python·JavaScript 코드까지 정리합니다.

이미지 모더레이션 API는 이미지를 받아 여러 유해 카테고리별로 점수를 매기고, 게시할지, 보류할지, 차단할지 판단할 근거를 돌려줍니다. 다만 omni-moderation-latest 같은 범용 모델에는 함정이 있습니다. 모델이 보고하는 모든 카테고리가 실제로 이미지를 보는 것은 아닙니다. OpenAI 문서는 13개 카테고리 중 6개를 "Text and images", 나머지 7개를 "Text only"로 표시합니다^[1]. 캡션 없이 사진만 보내면 텍스트 전용 카테고리 7개는 사진이 깨끗해서가 아니라 설계상 0으로 반환됩니다^[1].

이 가이드에서는 이것이 실무에서 무엇을 의미하는지 다룹니다. 이미지에 대해 믿을 수 있는 카테고리는 무엇인지, 이미지를 어떻게 보내는지(reAPI는 공개 URL만 받습니다), 요청이 어떻게 과금되는지, 점수를 어떻게 판정으로 바꾸는지, 그리고 이미지를 제출하고 판정 결과를 폴링하는 실행 가능한 Python·JavaScript 예제를 소개합니다. 마지막으로 Sightengine, Hive, Azure AI Content Safety, Amazon Rekognition 같은 이미지 전문 서비스와 어떻게 다른지 정리합니다.

TL;DR

omni-moderation-latest는 이미지에 대해 6개 카테고리를 채점합니다: sexual, self-harm, self-harm/intent, self-harm/instructions, violence, violence/graphic. sexual/minors를 포함한 나머지 7개는 텍스트 전용입니다^[1].
reAPI에서 이미지는 공개 http(s) URL을 담은 image_url 블록으로 보냅니다. Base64와 data: URI는 거부됩니다^[2].
과금은 모더레이션 단위(unit) 기준입니다. 이미지 1장당 1 unit, 텍스트 1,000단어당 1 unit이며, 요청 하나당 최소 1 unit입니다^[2]. 현재 요금은 모델 페이지에서 확인할 수 있습니다.
호출은 비동기입니다. POST /api/v1/moderations를 보낸 뒤 status가 completed가 될 때까지 GET /api/v1/tasks/{id}를 폴링합니다^[2].
flagged는 모델의 기본 판정입니다. 자체 정책에 맞추려면 카테고리별로 category_scores(0~1)에 임계값을 두고, 모델이 업데이트되면 다시 보정하세요^[1].
OpenAI 자체 엔드포인트가 무료인지는 OpenAI 모더레이션 API는 무료인가요?에서 다룹니다.

이미지 모더레이션 API가 볼 수 있는 유해 카테고리

OpenAI는 omni-moderation-latest의 각 카테고리가 지원하는 입력을 다음과 같이 명시합니다^[1].

카테고리	입력
`sexual`	텍스트 및 이미지
`self-harm`, `self-harm/intent`, `self-harm/instructions`	텍스트 및 이미지
`violence`, `violence/graphic`	텍스트 및 이미지
`sexual/minors`	텍스트 전용
`harassment`, `harassment/threatening`	텍스트 전용
`hate`, `hate/threatening`	텍스트 전용
`illicit`, `illicit/violent`	텍스트 전용

이미지 파이프라인에서는 두 가지 결과가 중요합니다.

첫째, 0이 언제나 측정값은 아닙니다. OpenAI는 텍스트 없이 이미지만 보내면 텍스트 전용 카테고리에 대해 모델이 점수 0을 반환한다고 밝히고 있습니다^[1]. 밈 속의 혐오 상징이나 스크린샷 안에 적힌 협박 문구는 이미지만 보낸 요청의 hate나 harassment 점수로는 잡히지 않습니다. 응답의 category_applied_input_types는 각 카테고리가 어떤 입력 유형을 기준으로 평가되었는지 알려줍니다. OpenAI의 이미지 전용 예시에서 이미지 카테고리 6개는 ["image"], 나머지는 빈 배열로 표시됩니다^[1]. 낮은 점수를 통과로 처리하기 전에 이 필드를 확인하세요.

둘째, sexual/minors는 텍스트 전용입니다^[1]. OpenAI 가이드는 또한 알려졌거나 의심되는 아동 성착취물(CSAM)을 Moderation API에 보내지 말라고 안내합니다. 이 API는 CSAM 탐지용으로 설계되지 않았고, 전용 아동 보호 장치를 대체하지 않기 때문입니다^[1]. 플랫폼에서 사용자 업로드를 받는다면 아동 보호를 위한 별도의 통제 수단을 마련하세요.

OpenAI는 이 모델의 이미지 파일 크기 제한을 20 MB로 문서화하고 있습니다^[1].

이미지 보내기: 공개 URL만 가능

요청 본문의 콘텐츠 필드는 input 하나입니다. 이미지는 콘텐츠 블록 배열로 보냅니다^[2].

{
  "model": "omni-moderation-latest",
  "input": [
    { "type": "image_url", "image_url": { "url": "https://example.com/upload.jpg" } }
  ]
}

OpenAI 자체 API 레퍼런스에는 image_url.url에 이미지 URL이나 base64로 인코딩된 이미지 데이터를 넣을 수 있다고 되어 있습니다^[3]. reAPI는 첫 번째 형식만 받습니다. image_url.url은 공개 http(s) URL이어야 하며, base64나 data: URI는 오류 20003으로 검증에 실패합니다^[2]. 이 규칙은 reAPI의 모든 모델에서 미디어 입력에 동일하게 적용됩니다.

사용자 업로드라면 처리 순서는 이렇습니다. 파일을 저장하고, 인터넷에서 가져올 수 있는 URL을 만든 다음, 모더레이션을 실행합니다. 서명된 URL(signed URL)도 태스크가 실행되는 시점에 유효하기만 하면 사용할 수 있습니다^[2]. URL을 가져올 수 없으면 태스크는 80007로 실패하고 요금은 환불됩니다^[2]. 판정이 나올 때까지 객체는 비공개 상태로, 게시하지 않은 채 두세요.

캡션과 사진을 같은 배열에 함께 넣을 수도 있습니다. reAPI 문서에 따르면 콘텐츠 블록 배열은 전체 묶음에 대해 하나의 결과를 반환하므로, 모델이 텍스트와 이미지를 함께 판단합니다^[2]. 캡션이 달린 게시물이라면 바로 원하는 동작입니다. 하지만 서로 관계없는 업로드 10장이라면 맞지 않습니다. 합쳐진 판정 하나로는 어떤 이미지가 걸렸는지 알 수 없으니, 이런 경우에는 요청을 따로 보내세요.

이미지 모더레이션 과금 방식

reAPI는 omni-moderation-latest를 모더레이션 단위로 과금합니다^[2].

입력	단위
`image_url` 블록 1개마다	1 unit
텍스트	요청 전체를 합산해 1,000단어당 1 unit. 텍스트 항목 하나는 최소 50단어로 계산
모든 요청	최소 1 unit

단위는 요청마다 한 번 크레딧으로 환산되며 올림 처리됩니다. 폴링은 무료이고, 실패한 요청은 자동으로 환불됩니다^[2]. 요청 하나에 최대 500개 항목을 넣을 수 있습니다^[2]. 단위당 요금은 모델 페이지에 있습니다. 서비스별 가격과 무료 티어 비교는 OpenAI 모더레이션 API는 무료인가요?를 참고하세요.

Python·JavaScript 이미지 모더레이션 API 예제

두 예제는 같은 일을 합니다. 이미지 1장을 제출하고, 3초마다 태스크를 폴링한 뒤, 첫 번째 결과를 반환합니다. reAPI 태스크 문서는 태스크가 진행 중인 동안 폴링 엔드포인트가 5초간 캐시되므로 2~3초보다 짧은 간격으로 폴링하지 말 것을 권장합니다^[4]. 모더레이션 검사는 보통 몇 초 안에 끝납니다^[2].

Python

import time
import requests

API = "https://reapi.ai/api/v1"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

def moderate_image(image_url, timeout_s=60):
    submit = requests.post(
        f"{API}/moderations",
        headers=HEADERS,
        json={
            "model": "omni-moderation-latest",
            "input": [{"type": "image_url", "image_url": {"url": image_url}}],
        },
        timeout=30,
    )
    submit.raise_for_status()
    task_id = submit.json()["id"]

    deadline = time.time() + timeout_s
    while time.time() < deadline:
        time.sleep(3)
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return task["output"]["moderation"]["results"][0]
        if task["status"] == "failed":
            raise RuntimeError(f'{task["error"]["code"]}: {task["error"]["message"]}')
    raise TimeoutError(f"task {task_id} still processing")

result = moderate_image("https://example.com/upload.jpg")
print(result["flagged"], result["category_scores"]["violence"])

JavaScript (Node.js 18+, `.mjs` 모듈로 저장)

const API = "https://reapi.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.REAPI_API_KEY}`,
  "Content-Type": "application/json",
};

async function moderateImage(imageUrl, timeoutMs = 60_000) {
  const submit = await fetch(`${API}/moderations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "omni-moderation-latest",
      input: [{ type: "image_url", image_url: { url: imageUrl } }],
    }),
  });
  if (!submit.ok) throw new Error(`submit failed: ${submit.status} ${await submit.text()}`);
  const { id } = await submit.json();

  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 3000));
    const task = await (await fetch(`${API}/tasks/${id}`, { headers })).json();
    if (task.status === "completed") return task.output.moderation.results[0];
    if (task.status === "failed") throw new Error(`${task.error.code}: ${task.error.message}`);
  }
  throw new Error(`task ${id} still processing`);
}

const result = await moderateImage("https://example.com/upload.jpg");
console.log(result.flagged, result.category_scores.violence);

JavaScript 버전은 브라우저가 아니라 서버에서 실행하세요. API 키는 Bearer 토큰이므로 프런트엔드 코드에 넣으면 개발자 도구를 여는 누구에게나 노출됩니다. 아래 FAQ의 React 질문에도 똑같이 해당됩니다. 텍스트 입력과 혼합 입력을 포함한 전체 요청 스키마는 API 문서에 있습니다.

결과 읽기와 임계값 설정

각 결과에는 네 개의 필드가 있습니다^[1]^[2].

필드	알려주는 내용
`flagged`	모델이 입력을 하나 이상의 카테고리에서 유해하다고 판단하면 `true`
`categories`	카테고리별 모델의 true/false 판정
`category_scores`	카테고리별 모델의 신뢰도, 0~1
`category_applied_input_types`	각 카테고리가 어떤 입력 유형(`text`, `image`)을 기준으로 평가되었는지

flagged는 1차 필터로는 쓸 만하지만, 모델의 기본값을 반영하므로 여러분의 정책보다 엄격하거나 느슨할 수 있습니다^[2]. OpenAI는 점수를 자동 차단 결정으로 쓰기보다 애플리케이션 정책을 위한 신호로 다루고, 필요하면 플래그된 콘텐츠를 검토로 넘기라고 안내합니다^[1].

흔히 쓰는 방식은 이미지 카테고리마다 구간을 셋으로 나누는 것입니다. 낮은 점수 미만은 허용, 중간은 사람 검토, 높은 점수 이상은 차단입니다. 최소 구현은 다음과 같습니다.

IMAGE_CATEGORIES = [
    "sexual", "self-harm", "self-harm/intent", "self-harm/instructions",
    "violence", "violence/graphic",
]
REVIEW_AT = 0.3   # example values only; calibrate on your own labeled images
BLOCK_AT = 0.8

def decide(result):
    applied = result["category_applied_input_types"]
    scores = result["category_scores"]
    checked = [c for c in IMAGE_CATEGORIES if "image" in applied.get(c, [])]
    top = max((scores[c] for c in checked), default=0.0)
    if top >= BLOCK_AT:
        return "block"
    if top >= REVIEW_AT or result["flagged"]:
        return "review"
    return "allow"

위 숫자는 예시일 뿐 권장값이 아닙니다. 이미 라벨링해 둔 이미지 수백 장을 돌려 보고 점수가 어디에 분포하는지 확인한 뒤 직접 정하세요. 이 점검은 주기적으로 다시 하세요. OpenAI는 기반 모델을 계속 업그레이드할 계획이며, category_scores를 기반으로 만든 커스텀 정책은 시간이 지나면서 재보정이 필요할 수 있다고 밝히고 있습니다^[1]. 점수는 reAPI를 거치면서 반올림되거나 재매핑되지 않으므로^[2], 한 번 해 둔 보정은 코드가 읽는 값에 그대로 적용됩니다.

이미지 전문 모더레이션 API와의 차이

범용 모델과 이미지 전문 서비스는 서로 다른 질문에 답합니다. omni-moderation-latest는 시각 카테고리 6개를 채점하고, 캡션과 이미지를 함께 판단할 수 있습니다^[1]. 이미지 전문 API는 무기, 약물, 혐오 상징, 이미지 속 텍스트 등 훨씬 많은 시각 클래스를 탐지하며, 파일을 받는 방식과 신뢰도를 보고하는 방식도 서로 다릅니다. 각 업체 문서를 기준으로 정리하면 다음과 같습니다.

서비스	이미지에서 탐지하는 항목	이미지 전송 방식	출력	과금 단위
reAPI의 `omni-moderation-latest`	성적 콘텐츠, 자해(3), 폭력(2)^[1]	공개 http(s) URL^[2]	카테고리별 Boolean + 0–1 점수^[1]	이미지당(모더레이션 단위)^[2]
Sightengine	29개 클래스에 걸친 노출, 폭력, 무기, 혐오·모욕 표식, 고어, 자해, 약물, 주류, 담배, 도박, 이미지 속 텍스트, QR 코드^[5]	직접 업로드 또는 공개 접근 가능한 URL^[6]	선택한 모델별 결과	Operation 단위. 같은 그룹의 모델은 요청당 한 번만 계산^[7]
Hive Visual Moderation	성적 콘텐츠, 폭력적 이미지, 약물, 혐오 이미지, 이미지 속성을 이름 붙은 클래스로 세분화^[8]	공개 또는 서명된 URL, 혹은 로컬 파일 업로드^[9]	클래스별 0–1 신뢰도^[9]	연간 계약. 소규모 고객에게는 셀프서브 VLM을 안내^[8]
Azure AI Content Safety (Analyze Image)	Hate, SelfHarm, Sexual, Violence^[10]	Base64 바이트 또는 blob URL 중 하나^[10]	카테고리별 심각도 0, 2, 4, 6^[11]	제출한 이미지당^[12]
Amazon Rekognition (DetectModerationLabels)	3단계 라벨 분류 체계. 최상위에는 Explicit, Violence, Visually Disturbing, Drugs & Tobacco, Alcohol, Rude Gestures, Gambling, Hate Symbols 포함^[13]	Base64 이미지 바이트 또는 Amazon S3 객체. JPEG 또는 PNG^[14]	신뢰도가 붙은 라벨. `MinConfidence` 기본값 50^[14]	API 호출당 이미지당^[15]

선택을 가르는 차이는 대개 세 가지입니다.

시각 커버리지. 무기, 약물, 혐오 상징, 이미지에 박힌 텍스트를 잡아야 한다면 전문 서비스들이 해당 클래스를 명시적으로 제공합니다^[5]^[8]^[13]. omni-moderation-latest에는 이에 해당하는 이미지 카테고리가 없습니다^[1].

점수 형태. Hive는 클래스별 0–1 신뢰도를 반환하며, 클래스를 플래그할 기준으로 0.90 전후에서 시작할 것을 제안합니다^[8]. Rekognition은 MinConfidence 미만의 라벨을 버리며, 기본값은 0–100 척도에서 50입니다^[14]. Azure는 이미지에 대해 0, 2, 4, 6의 거친 심각도 단계를 반환합니다^[11]. 한 서비스에서 맞춘 임계값은 다른 서비스로 옮겨 쓸 수 없습니다.

입력 처리. Azure와 Rekognition은 base64 바이트를 받고^[10]^[14], Sightengine과 Hive는 파일 직접 업로드를 받습니다^[6]^[9]. reAPI는 URL만 받으므로^[2], 업로드가 이미 객체 스토리지에 저장되는 파이프라인에 잘 맞습니다.

omni-moderation-latest는 콘텐츠가 주로 텍스트이고 이미지가 첨부되는 경우, 시각 카테고리 6개가 정책과 맞는 경우, 또는 이미 같은 키로 reAPI의 다른 모델을 호출하고 있는 경우에 적합합니다. 모달리티와 사용 사례별로 더 넓게 비교하려면 최고의 콘텐츠 모더레이션 API를 참고하세요.

자주 묻는 질문

이미지 모더레이션 api 무료

OpenAI는 자체 모더레이션 엔드포인트를 무료로 사용할 수 있다고 밝히고 있습니다^[1]. reAPI에서 omni-moderation-latest는 이미지 1장당 1 unit의 종량제이며, 실패한 요청은 환불됩니다^[2]. 업체별 무료 티어와 rate limit 비교는 OpenAI 모더레이션 API는 무료인가요?에 있습니다.

업로드 이미지 모더레이션 무료 api

업로드된 이미지의 모더레이션은 세 단계입니다. 파일을 비공개로 저장하고, API가 가져올 수 있는 URL을 만든 다음(서명된 URL은 유효한 동안 사용 가능), 그 URL을 제출하고 판정이 나온 뒤에만 게시합니다^[2]. reAPI는 파일 바이트나 base64 문자열을 직접 받지 않습니다^[2]. 어떤 서비스에 무료 한도가 있는지는 OpenAI 모더레이션 API는 무료인가요?를 참고하세요.

OpenAI 이미지 모더레이션 api

네, OpenAI의 모더레이션 모델은 이미지를 처리합니다. omni-moderation-latest는 텍스트와 이미지 입력을 받고, 오디오는 분류하지 않으며, 이미지에 대해서는 성적 콘텐츠, 자해, 폭력 카테고리만 채점합니다^[1]. reAPI에서도 모델 ID는 동일한 omni-moderation-latest이며, 비동기 태스크 엔드포인트로 제공됩니다^[2].

이미지 모더레이션 api Python

위의 Python 예제는 그대로 완성된 코드입니다. image_url 블록을 /api/v1/moderations에 POST하고, /api/v1/tasks/{id}를 폴링해 output.moderation.results[0]을 반환합니다. 필요한 패키지는 requests 하나뿐입니다. API 문서에는 같은 호출이 cURL, Node.js, Go로도 나와 있습니다.

이미지 모더레이션 api React

모더레이션 API는 React 컴포넌트가 아니라 백엔드에서 호출하세요. React 앱은 파일을 서버나 스토리지에 업로드하고, 서버가 키로 API를 호출하며, 클라이언트는 판정 결과만 받습니다. Bearer 키를 브라우저 코드에 넣으면 모든 방문자에게 노출됩니다.

ChatGPT API로 이미지 분석이 가능한가요?

네. OpenAI의 비전 지원 모델은 Responses API와 Chat Completions API를 통해 URL, base64 data URL, 파일 ID로 이미지를 분석합니다^[16]. 이는 자유 형식의 이미지 이해입니다. 고정된 유해 카테고리에 대해 0–1 점수를 받으려면 모더레이션 엔드포인트가 그 목적에 맞게 만들어진 선택지입니다^[1].

최고의 이미지 모더레이션 api

무엇을 탐지해야 하는지에 따라 다릅니다. omni-moderation-latest 같은 범용 모델은 이미지의 성적 콘텐츠, 자해, 폭력을 다루고 캡션용 텍스트 카테고리를 더해 줍니다^[1]. 이미지 전문 서비스는 더 많은 시각 클래스를 다룹니다(위 표 참고). 전체 선택 가이드는 최고의 콘텐츠 모더레이션 API에 있습니다.

업로드 흐름에 이미지 모더레이션 연결하기

실제로 동작하는 이미지 모더레이션 API 구성은 간단합니다. 비공개 스토리지에 업로드하고, URL을 모더레이션하고, 점수에 따라 처리한 다음, 게시합니다. omni-moderation-latest에서는 픽셀을 보는 카테고리가 6개뿐이라는 점을 기억하세요. 이미지 속 텍스트가 중요하다면 요청에 캡션이나 OCR 텍스트를 함께 넣고, 아동 보호용 통제는 별도로 두세요. 처음에는 flagged로 시작하고, 라벨링된 데이터가 생기면 카테고리별 임계값으로 옮기며, 모델이 바뀌면 그 임계값을 다시 점검하세요.

직접 써 보려면 Content Moderation 모델 페이지의 playground에 이미지 URL을 붙여 넣은 뒤, 위의 Python 또는 JavaScript 예제를 백엔드로 옮기세요. 이 이미지 모더레이션 API가 받는 모든 필드는 API 문서에 정리되어 있습니다.