OpenAI's Moderation API
Op deze pagina
Bijgewerkt op 3 november 2026 op basis van de Moderation-gids van OpenAI: de categorie
illicit(enillicit/violent) is toegevoegd aan de tabel, evenals categorieën die van toepassing zijn op afbeeldingen. Bron: Moderation.
Een ingebouwde moderatietool
OpenAI biedt een gratis Moderation API aan die tekst analyseert om potentieel schadelijke inhoud op te sporen. Dit is de eerste verdedigingslinie die u moet integreren in elke applicatie die gebruikmaakt van OpenAI-modellen. U bent echter niet beperkt tot dit gebruiksscenario: omdat de API ruwe tekst als invoer accepteert, kunt u deze ook gebruiken om invoer te filteren die bestemd is voor andere modellen. Het feit dat de service gratis is, verandert uw benadering van het probleem. De gebruikelijke afwegingen—moeten we elk verzoek modereren of alleen verdachte?—verliezen hun gewicht, aangezien de enige resterende kosten de latentie betreffen.
Wat de API retourneert
De basisaanroep past op één regel; het is de respons die uw aandacht vereist. De API retourneert drie distincte elementen: een boolean flagged die het oordeel van OpenAI weergeeft, de lijst met daadwerkelijk geactiveerde categorieën, en, nog belangrijker, continue scores per categorie. Deze scores maken het verschil in productieomgevingen, omdat ze u in staat stellen zelf te bepalen waar u de grens trekt, in plaats van een drempelwaarde over te nemen die is ontworpen voor algemeen gebruik.
from openai import OpenAI
client = OpenAI()
def moderate_content(text: str) -> dict:
"""Analyseert tekst via de Moderation API van OpenAI."""
response = client.moderations.create(input=text)
result = response.results[0]
return {
"blocked": result.flagged,
"categories": {
cat: flagged
for cat, flagged in result.categories.__dict__.items()
if flagged
},
"scores": {
cat: round(score, 4)
for cat, score in result.category_scores.__dict__.items()
if score > 0.01
},
}
# Test met verschillende inhoudstypes
examples = [
"How do I bake a chocolate cake?",
"I will kill you if you don't answer me",
"Explain how AES encryption works",
]
for text in examples:
result = moderate_content(text)
status = "BLOCKED" if result["blocked"] else "OK"
print(f"{status} : {text[:50]}...")
if result["categories"]:
print(f" Categories : {list(result['categories'].keys())}")
De drie testvoorbeelden zijn niet willekeurig: het eerste zou moeten passeren, het tweede geblokkeerd moeten worden, en het derde—een volkomen legitieme technische vraag—laat zien hoe uw pipeline zich gedraagt wanneer deze wordt geconfronteerd met beveiligingsgerelateerde terminologie. Dit is precies het soort verzoek dat een cybersecurityteam dagelijks afhandelt.
Gedetecteerde categorieën
De API classificeert problematische inhoud langs verschillende assen, die elk overeenkomen met een distinct type schade.
| Category | Description |
|---|---|
| harassment | Harassment, threats, intimidation |
| hate | Hate speech based on identity |
| illicit | Advice or instructions for committing illicit acts |
| self-harm | Self-harm, suicide |
| sexual | Explicit sexual content |
| violence | Graphic violence, threats |
Elke categorie kent ook subcategorieën (bijv. harassment/threatening, illicit/violent, violence/graphic) voor fijnmaziger filtering. Met omni-moderation-latest zijn alleen self-harm en de varianten daarvan, sexual, en violence (met violence/graphic) ook van toepassing op afbeeldingen; de andere categorieën gelden uitsluitend voor tekst. Deze granulariteit bespaart u het maken van grove afwegingen: een forummoderatieplatform zou bijvoorbeeld harassment/threatening willen blokkeren terwijl eenvoudig harassment wordt getolereerd, wat veel gewone geschillen dekt.
Wanneer u grote volumes moet verwerken—bijvoorbeeld retrospectieve analyse van een conversatiegeschiedenis—accepteert de API een lijst en retourneert ze een resultaat voor elk element, waardoor meerdere netwerkrondes worden vermeden.
def moderate_batch(messages: list[str]) -> list[dict]:
"""Moderateert meerdere berichten in één enkele aanroep."""
response = client.moderations.create(input=messages)
results = []
for i, result in enumerate(response.results):
results.append({
"index": i,
"text": messages[i][:50],
"blocked": result.flagged,
"max_score": max(
score
for score in result.category_scores.__dict__.values()
),
})
return results
Moderatie aan beide uiteinden van de pipeline
Een veelgemaakte fout is het modereren van alleen de invoer. Dit berust op een verkeerde intuïtie: als het binnenkomende bericht acceptabel is, zal de respons dat ook zijn. Een model kan echter problematische inhoud produceren op basis van een neutraal verzoek, vooral wanneer het vertrouwt op opgehaalde documenten waarvan de inhoud door niemand is geverifieerd. De onderstaande klasse past daarom dezelfde behandeling in beide richtingen toe, met toevoeging van een aangepaste drempelwaarde die het standaardbesluit van de API aanscherpt.
class ModerationPipeline:
"""Invoer- + uitvoer-moderatiepipeline voor een LLM-applicatie."""
def __init__(self, custom_threshold: float = 0.7):
self.client = OpenAI()
self.threshold = custom_threshold
def moderate_input(self, message: str) -> tuple[bool, dict]:
"""Moderateert het bericht VOOR verzending naar het model."""
result = self.client.moderations.create(input=message).results[0]
scores = result.category_scores.__dict__
high_categories = {
cat: score for cat, score in scores.items() if score > self.threshold
}
blocked = result.flagged or bool(high_categories)
return blocked, {"flagged_api": result.flagged, "custom_categories": high_categories}
def moderate_output(self, response: str) -> tuple[bool, dict]:
"""Moderateert de respons van het model VOOR verzending naar de gebruiker."""
return self.moderate_input(response)
def process_message(self, user_message: str, system_prompt: str) -> str:
"""Volledige pipeline: invoermoderatie, LLM, uitvoermoderatie."""
# Stap 1: invoer modereren
input_blocked, details = self.moderate_input(user_message)
if input_blocked:
return "Your message cannot be processed. Please rephrase it."
# Stap 2: het model aanroepen
response = self.client.chat.completions.create(
model="gpt-5.6-sol",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message},
],
)
model_response = response.choices[0].message.content
# Stap 3: uitvoer modereren
output_blocked, _ = self.moderate_output(model_response)
if output_blocked:
return "The response was filtered for non-compliance."
return model_response
# Gebruik
pipeline = ModerationPipeline(custom_threshold=0.5)
response = pipeline.process_message(
"How do I protect my application against SQL injections?",
"You are an expert in defensive cybersecurity."
)
print(response)
Wat deze API niet doet
De belangrijkste beperking is ook de meest misbegrepene: de API detecteert geen prompt injection. Een beleefd bericht dat vanuit inhoudelijk oogpunt volkomen onschuldig is, maar het model vraagt zijn instructies te negeren, passeert zonder enige categorie te activeren. Verwachten dat deze tool beschermt tegen manipulatie, is vergelijkbaar met het installeren van een rookmelder in de hoop dat deze inbraken voorkomt.
False positives vormen de tweede beperking, wat vooral gevoelig ligt in beveiligings- of medische contexten, waar het beschrijven van een dreiging deel uitmaakt van het werk. Er wordt een extra netwerkaanroep aan elk verzoek toegevoegd, wat van belang is wanneer u streeft naar real-time responsen. Detectie blijft betrouwbaarder in het Engels dan in andere talen, een blind vlek die aanvallers perfect kennen. Tot slot evolueren categorieën en drempelwaarden met updates: een kalibratieset van zes maanden geleden verdient herverificatie.
Deze beperkingen dicteren hoe u de tool gebruikt. Moderatie in beide richtingen, pas drempelwaarden per categorie aan in plaats van globaal, en combineer de tool systematisch met andere lagen—detectie van injecties, filtering op basis van bedrijfslogica—zoals de volgende lessen in detail beschrijven. Log de resultaten, want het observeren van uw eigen false positives leert u waar u de schuifregelaars moet verplaatsen. En bereid u voor op het scenario waarin de API niet beschikbaar is: beslis nu, terwijl de rust nog heerst, of uw applicatie standaard moet blokkeren of verkeer moet doorlaten, in plaats van dit gedrag pas tijdens een incident te ontdekken.
Belangrijkste punten
- De Moderation API is gratis, snel en eenvoudig te integreren
- Deze detecteert aanstootgevende inhoud, maar geen injections of jailbreaks
- De pipeline van invoer naar model naar uitvoer moet aan beide uiteinden worden gemodereerd
- Standaarddrempelwaarden passen zelden; pas ze aan uw context aan
- Het is één laag among others, nooit de enige verdedigingslinie