검열 — /v1/moderations
부적절한 입력 걸러내기. 무료이고 잔액 0에서도 됩니다.
학생이 쓰는 서비스라면 입력을 먼저 걸러야 할 때가 있어요. 이 문은 벤더가 무료로 제공해서 크레딧이 차감되지 않아요 — 잔액이 0이어도, 키의 하루 · 월 한도에 닿았어도 부르고, 다시 보내도 요금이 없어요(안전 기능을 돈으로 막지 않아요). 잔액이 0이면 검열은 되고 그다음 채팅 호출에서 402 가 와요. 이 문엔 Idempotency-Key 와 조회 주소가 없어요(실어도 읽지 않아요). 402 · 422 도 오지 않아서 맨 위 기본 규칙의 중복 방지 · 실행 불명 얘기는 이 문에 해당하지 않아요. 스페이스 키면 글 문과 같은 전송 정책을 OpenAI 로 보내기 전에 걸어서 space_content_policy(400 · 403 · 409 · 503 — 「에러」 장 표)가 올 수 있어요(2026-10-31 부터). 429 · 504 도 맨 아래 「오류」 문단대로 다시 보내도 돼요 — 맨 위 기본 규칙의 「504 · x-should-retry: false」는 다른 문 얘기예요.
curl https://oneport.kr/v1/moderations \
-H "Authorization: Bearer $ONEPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "input": "검사할 문장" }'openai SDK 로도 그대로 불러요 — Python 은 client.moderations.create(model="omni-moderation-latest", input=text), Node 는 await client.moderations.create({ model: "omni-moderation-latest", input: text }) 뒤 results[0].flagged 를 봐요. 채팅 때문에 재시도를 0 으로 둔 클라이언트라도 이 호출만 Python client.with_options(max_retries=2) · Node 둘째 인자 { maxRetries: 2 } 로 켜셔도 돼요(SDK 동작).
요청 파라미터#
요청 본문 (JSON)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| input필수 | 문자열 또는 배열 | 검사할 글이에요(문자열 또는 여러 개를 담은 배열). 빈 문자열 · 빈 배열이면 400 이에요 — 배열 안의 빈 글은 거르지 않고 그대로 넘기니 미리 빼고 보내세요. 한국어 글도 고치지 않고 그대로 OpenAI 에 넘겨서, 갈래 · 점수 칸은 영어와 같은 모양으로 와요. 한국어를 얼마나 잘 잡는지는 OpenAI 가 정해요(벤더 동작) — 학생 글 몇 개로 category_scores 를 먼저 보고 문턱을 정하세요. 그림도 같이 거를 수 있어요 — 배열에 OpenAI 형식 조각({"type": "text", "text": …} · {"type": "image_url", "image_url": {"url": …}})을 넣으면 저희는 안을 보지 않고 그대로 넘겨요. 어떤 조각을 몇 개까지 받는지는 OpenAI 가 정해요(벤더 동작) — 못 받으면 400 이고 message 의 「다시 보내도 같아요 — 」 뒤에 OpenAI 의 이유가 붙어요. data: 로 붙인 그림도 아래 4.5MB 본문 한도에 들어가요. 저희 쪽엔 배열 개수 상한이 없어요. 학생 키 · 스페이스 강좌 키로도 불러요 — 강좌 몫에 닿았어도 429 group_limit_exceeded 가 오지 않아요. 닫힌 강좌 · 기간이 끝난 반의 키로도 불러요(꺼진 키 · 기한이 지난 키 · 멈춘 지갑은 401). 학생 키라는 이유로 Claude · GPT 글 모델이 403 으로 막히지는 않아요 — 검열 다음 채팅 호출에서 학생 키가 막히는 경우는 「인증」 장이에요(https://oneport.kr/docs/authentication.md — 월 한도 429 도 거기 있어요). |
| model | 검열 모델 id (문자열) | 안 보내면 omni-moderation-latest 로 채워요. 판정 기준을 고정하려면 날짜 붙은 id(아래 표 · GET /v1/models 에서 kind 가 moderation 인 줄 — 10월 기준 omni-moderation-2024-09-26)를 적으세요. 목록에 없는 id 는 404 model_not_found, 검열이 아닌 모델은 400, 문자열이 아닌 값은 400 이에요. |
응답에서 볼 것#
응답은 OpenAI 가 보낸 몸통을 고치지 않고 그대로 돌려드려요 — id · model · results 와, 결과마다 category_applied_input_types(어느 입력 종류에서 본 점수인지) 같은 칸도 OpenAI 가 보내면 그대로 와요(omni-moderation 종류는 harassment · harassment/threatening · hate · hate/threatening · illicit · illicit/violent · self-harm · self-harm/intent · self-harm/instructions · sexual · sexual/minors · violence · violence/graphic 이에요 — 뜻은 OpenAI 검열 안내 · 늘 수 있으니 모르는 이름에도 문턱을 두세요 · 벤더 동작). 욕설 · 비속어만 잡는 종류는 없어요 — 혼잣말 욕까지 막으려면 서비스 쪽 낱말 목록을 같이 두세요. 모양은 {"id": "modr-…", "model": "omni-moderation-…", "results": [{"flagged": false, "categories": {"harassment": false, …}, "category_scores": {"harassment": 0.0001, …}, "category_applied_input_types": {"harassment": ["text"], …}}]} 예요(벤더 동작). results[0].flagged 가 true 면 걸린 글이고, categories 에 걸린 종류가, category_scores 에 종류마다 점수가 담겨요. flagged 가 true 면 막으세요. 더 엄격하게 거르려면 category_scores 에 서비스 기준 문턱을 더 두세요. 배열로 보내면 results 가 넣은 순서대로 하나씩 와요(벤더 동작). 실패는 요청 하나 단위예요 — 배열 중 하나를 OpenAI 가 거절하면 결과 일부가 아니라 요청 전체가 400 이에요. 저희는 OpenAI 의 이유 문장을 message 끝의 「다시 보내도 같아요 — 」 뒤에 붙여 드리고(최대 400자) 번호를 따로 달지 않아요 — 몇 번째 글인지는 그 문장에 있을 때만 알 수 있어요. 없으면 반으로 나눠 다시 보내세요. 보낸 글은 저희 사용 기록에 남기지 않아요 — 건수 · 성공 · 실패와, 실패 때 OpenAI 가 보낸 이유 문장 앞부분(키 같은 값은 가려서)만 남기고, 글은 검사하러 OpenAI 로만 가요. 이 문엔 x-gateway-fallback-depth 머리글이 없어요 — 한 경로로만 보내요.
오류 — 401 authentication_error(키) · 400 invalid_request_error(JSON 을 못 읽음 · 본문이 객체가 아님 · 빈 input · 문자열이 아닌 model · 검열이 아닌 모델 id — 어느 문으로 보낼지 알려 드려요 · OpenAI 가 입력을 거절 — message 의 「다시 보내도 같아요 — 」 뒤에 OpenAI 의 이유가 붙어요) · 404 model_not_found · 429 rate_limit_error(OpenAI 가 조였어요) · 502 upstream_error(OpenAI 쪽 실패) · 503 api_error · 504 upstream_error(OpenAI 가 20초 안에 답하지 않았어요 · 이 문의 504 엔 error.reason 이 없어요). 20초는 OpenAI 를 기다리는 시간이고, 요청 하나는 키 확인까지 늦어도 30초 안에 끝나요 — 클라이언트 시간 제한은 30초보다 길게 두세요. SDK 재시도를 켜 두면(위 maxRetries 2) 한 번에 30초씩 세 번이라 1분 30초 넘게 기다릴 수 있어요 — 학생이 답을 기다리는 화면이면 maxRetries 를 1 로 줄이세요(SDK 동작). 400 은 type 이 모두 invalid_request_error 라 저희 쪽 검사와 OpenAI 의 입력 거절은 문장으로만 갈려요 — 어느 쪽이든 다시 보내도 같으니 학생 입력이면 막고 다시 쓰게 하세요. 404 도 다시 보내도 같아요. 429 · 502 · 503 · 504 는 잠시 뒤 다시 보내세요 — 이 문은 x-should-retry 를 안 보내고, Retry-After 는 모델 목록을 잠깐 못 읽은 503 과 error.reason 이 "provider_unavailable" 인 503(저희 쪽 사정으로 OpenAI 가 받지 않음 · 2026-10-31 부터)에만 2초로 와요. 그 밖엔 간격을 직접 정하세요. 상태 코드 없는 연결 오류 · 시간 초과도 그대로 다시 보내도 돼요. 오류 몸통은 {"error": {"type": …, "message": …, "code": …, "request_id": …}} 이고 code 는 type 과 같아요. 401 엔 error.reason 도 와요(값은 「인증」 장 「키가 안 열릴 때」 표). 요청 ID 는 200 이든 오류든 머리글 request-id(같은 값이 x-request-id)로도 와요. 다만 이 문의 요청 ID 는 저희 사용 기록과 이어지지 않아서, 문의할 땐 요청 ID 와 함께 부른 시각을 꼭 알려 주세요. 본문이 4.5MB 를 넘으면 JSON 이 아닌 413 이 와요 — 긴 글은 여러 요청으로 나눠 보내세요. 검사가 끝내 실패하면 통과로 두지 말고 막으세요.
이 문이 받는 모델#
검열
| 모델 | 차감 단가 |
|---|---|
| omni-moderation-latestOmni Moderation | 무료 |
| omni-moderation-2024-09-26Omni Moderation (2024-09-26) | 무료 |