Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Contentmoderatie met de API

Les 19 van 22 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Contentmoderatie met de API
  2. De Moderation API
  3. Moderatiecategorieën
  4. Volledige moderatiepijplijn
  5. Batchmoderatie
  6. Moderatielogboek
  7. Belangrijkste punten

Bijgewerkt op 3 november 2026 op basis van de Moderation-gids van OpenAI: de categorieën illicit en illicit/violent voor het model omni-moderation-latest ontbraken in de lijst en de code. Bron: Moderation.

Contentmoderatie met de API

De Moderation API van OpenAI detecteert automatisch ongepaste inhoud. Het is een gratis, essentieel hulpmiddel voor elke applicatie die door gebruikers gegenereerde inhoud accepteert. De vorige les liet u zien hoe u aangepaste filters schrijft; deze les biedt u een getrainde classifier die datgene opspoort wat reguliere expressies nooit zullen vinden: verhulde bedreigingen, indirecte beledigingen en impliciete formuleringen.

De Moderation API

De aanroep is bewust minimaal gehouden: één model, één tekst en een resultaat dat neerkomt op een boolean. Het veld flagged beantwoordt de binaire vraag: “Schendt deze inhoud het gebruiksbeleid?”, terwijl categories specifieert welke categorieën van toepassing zijn. Omdat dit eindpunt gratis is, is er geen economische reden om het over te slaan, zelfs niet bij grote volumes.

from openai import OpenAI
client = OpenAI()

# De Moderation API is GRATIS
moderation = client.moderations.create(
    model="omni-moderation-latest",
    input="Hello, how are you?"
)

result = moderation.results[0]
print(f"Content flagged: {result.flagged}")
print(f"Categories: {result.categories}")

# Resultaat:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)

Moderatiecategorieën

Achter de boolean gaat een fijnmazig raster schuil. Het model levert per categorie een beslissing terug: intimidatie, bedreigende intimidatie, haat, bedreigende haat, instructies voor illegale handelingen (met of zonder geweld), zelfbeschadiging met zijn varianten (instructies en intentie), seksuele inhoud, seksuele inhoud met minderjarigen, geweld en grafisch geweld. Daarnaast wordt voor elk een betrouwbaarheidsscore tussen 0,0 en 1,0 gegeven.

Deze scores zijn belangrijker dan de binaire beslissing wanneer u uw beleid wilt afstemmen. Een professioneel forumplatform wil misschien blokkeren bij 0,3 voor intimidatie, terwijl een fictiedienst 0,7 voor geweld accepteert. De onderstaande functie ontsluit beide niveaus van inzicht: de daadwerkelijk geactiveerde categorieën en de ruwe scores voor uw eigen drempelwaarden.

def analyze_moderation(text: str) -> dict:
    """Gedetailleerde moderatie-analyse."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Beschikbare categorieën
    categories = {
        "harassment": result.categories.harassment,
        "harassment_threatening": result.categories.harassment_threatening,
        "hate": result.categories.hate,
        "hate_threatening": result.categories.hate_threatening,
        "illicit": result.categories.illicit,
        "illicit_violent": result.categories.illicit_violent,
        "self_harm": result.categories.self_harm,
        "self_harm_instructions": result.categories.self_harm_instructions,
        "self_harm_intent": result.categories.self_harm_intent,
        "sexual": result.categories.sexual,
        "sexual_minors": result.categories.sexual_minors,
        "violence": result.categories.violence,
        "violence_graphic": result.categories.violence_graphic,
    }

    # Betrouwbaarheidsscores (0.0 tot 1.0)
    scores = {
        "harassment": result.category_scores.harassment,
        "hate": result.category_scores.hate,
        "self_harm": result.category_scores.self_harm,
        "sexual": result.category_scores.sexual,
        "violence": result.category_scores.violence,
    }

    return {
        "flagged": result.flagged,
        "detected_categories": [k for k, v in categories.items() if v],
        "main_scores": {k: round(v, 4) for k, v in scores.items()},
    }

# Test
result = analyze_moderation("Hello everyone!")
print(f"Flagged: {result['flagged']}")
print(f"Scores: {result['main_scores']}")

Volledige moderatiepijplijn

Moderatie van gebruikersinvoer

Laten we deze aanroep verpakken in een herbruikbare component. ContentModerator retourneert een expliciet paar—aanvaardbaar of niet, met de reden—in plaats van een ruw object dat elke aanroeper opnieuw zou moeten interpreteren. Het vertalen van categorieën naar duidelijke taal is belangrijk: dit is de vocabulaire die in uw interface en logs verschijnt, en het moet begrijpelijk zijn voor het menselijke moderatieteam dat het overneemt.

class ContentModerator:
    """Contentmoderator voor applicaties."""

    def __init__(self, custom_threshold: float = 0.5):
        self.client = OpenAI()
        self.threshold = custom_threshold

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Moderate tekst. Retourneert (is_acceptable, details)."""
        moderation = self.client.moderations.create(
            model="omni-moderation-latest",
            input=text
        )

        result = moderation.results[0]

        if result.flagged:
            categories = []
            if result.categories.harassment:
                categories.append("harassment")
            if result.categories.hate:
                categories.append("hate speech")
            if result.categories.sexual:
                categories.append("sexual content")
            if result.categories.violence:
                categories.append("violence")
            if result.categories.self_harm:
                categories.append("self-harm")

            return False, {
                "reason": "Inappropriate content detected",
                "categories": categories
            }

        return True, {"reason": "Content acceptable"}

    def moderate_conversation(self, messages: list[str]) -> list[dict]:
        """Moderate een lijst met berichten."""
        results = []
        for msg in messages:
            acceptable, details = self.moderate(msg)
            results.append({
                "message": msg[:50] + "..." if len(msg) > 50 else msg,
                "acceptable": acceptable,
                **details
            })
        return results

# Gebruik
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")

Integratie in de API-pijplijn

Moderatie omlijst de aanroep aan beide zijden. Het filteren van invoer voorkomt dat u betaalt voor generatie van inhoud die u toch zou afwijzen; het filteren van uitvoer beschermt tegen gevallen waarin het model, slim uitgelokt, zelf iets onaanvaardbaars produceert. Let op het verschil in afhandeling: bij invoer kunt u de gebruiker vertellen wat er is gedetecteerd, aangezien hij de auteur is; bij uitvoer blijft het bericht vaag, omdat detaillering zou betekenen dat u beschrijft wat het model zojuist heeft geproduceerd.

def moderated_chatbot(user_input: str) -> str:
    """Chatbot met moderatie van zowel inputs ALS outputs."""
    moderator = ContentModerator()

    # 1. Input modereren
    input_ok, input_details = moderator.moderate(user_input)
    if not input_ok:
        return (f"Your message was blocked: "
                f"{', '.join(input_details['categories'])}")

    # 2. Respons genereren
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Respond in a professional and safe manner.",
        input=user_input
    )

    # 3. Output modereren
    output_ok, output_details = moderator.moderate(response.output_text)
    if not output_ok:
        return "I am unable to provide that response."

    return response.output_text

# Test
print(moderated_chatbot("What is the capital of France?"))

Batchmoderatie

Deze dubbele aanroep voegt latentie toe, wat acceptabel is in een gesprek maar prohibitief wordt wanneer u tienduizend klantrecensies uit een bestand moet verwerken. Om grote volumes efficiënt te modereren, geeft u direct een array door: de API verwerkt alle teksten in één verzoek en retourneert de resultaten in dezelfde volgorde, zodat u ze opnieuw kunt koppelen op basis van de index.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Moderate meerdere teksten in één verzoek."""
    results = []

    # De API accepteert een array van inputs
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=texts
    )

    for i, result in enumerate(moderation.results):
        results.append({
            "index": i,
            "text_preview": texts[i][:50],
            "flagged": result.flagged,
        })

    flagged_count = sum(1 for r in results if r["flagged"])
    print(f"Moderated {len(texts)} texts: {flagged_count} flagged")

    return results

# Gebruik
texts = [
    "Hello, how are you?",
    "Great product, I recommend it!",
    "Customer service is excellent.",
]
results = moderate_batch(texts)

Moderatielogboek

Een moderatiebeslissing heeft invloed op een gebruiker, en u zult vroeg of laat nodig hebben deze te rechtvaardigen—of het nu gaat om een klant die een blokkering betwist of om een toezichthouder. Log daarom systematisch het oordeel, de gebruikers-ID, de scores en een tekstfragment. Het logniveau maakt onderscheid tussen de twee gevallen: warning voor gemarkeerde inhoud, die menselijke review verdient, en info voor de rest, die uw statistieken voedt.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Moderate en logt het resultaat voor auditing."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "user_id": user_id,
        "flagged": result.flagged,
        "text_preview": text[:100],
        "scores": {
            "harassment": round(result.category_scores.harassment, 4),
            "hate": round(result.category_scores.hate, 4),
            "violence": round(result.category_scores.violence, 4),
        }
    }

    if result.flagged:
        logger.warning(json.dumps(log_entry))
    else:
        logger.info(json.dumps(log_entry))

    return not result.flagged

# Gebruik
is_ok = moderate_with_log("Test message", user_id="user-123")

Eén laatste waarschuwing voordat we verdergaan: moderatie classificeert inhoud; het begrijpt geen intentie. Een perfect beleefd bericht dat probeert uw assistent te ‘jailbreaken’, zal al deze filters passeren zonder ook maar één keer gemarkeerd te worden. Dat is het onderwerp van de volgende les.

Belangrijkste punten

  • De Moderation API is gratis—gebruik deze systematisch
  • Moderate zowel inputs (gebruikersinhoud) ALS outputs (modelresponsen)
  • Het model omni-moderation-latest dekt alle inhoudscategorieën
  • Log alle moderatiebeslissingen voor auditing
  • Gebruik batchverwerking om grote volumes efficiënt te modereren
  • Moderatie vult systeeminstructies aan; het vervangt ze niet