2026/10/07

Bildmoderations-API Tutorial: Beispiel in Python und JavaScript

So funktioniert eine Bildmoderations-API: welche Schadenskategorien für Bilder gelten, Eingabe nur per URL, Abrechnung pro Bild, Score-Schwellenwerte sowie Code in Python und JavaScript.

Eine Bildmoderations-API nimmt ein Bild entgegen, bewertet es anhand einer Liste von Schadenskategorien und sagt Ihnen, ob Sie es veröffentlichen, zurückhalten oder blockieren sollten. Der Haken bei einem Allzweckmodell wie omni-moderation-latest: Nicht jede Kategorie, die es zurückgibt, betrachtet tatsächlich das Bild. OpenAIs Dokumentation kennzeichnet 6 der 13 Kategorien mit "Text and images" und die übrigen 7 mit "Text only"^[1]. Wenn Sie ein Foto ohne Bildunterschrift senden, liefern diese 7 reinen Textkategorien konstruktionsbedingt 0 zurück, und nicht etwa, weil das Foto unbedenklich ist^[1].

Dieser Leitfaden zeigt, was das in der Praxis bedeutet: auf welche Kategorien Sie sich bei Bildern verlassen können, wie Sie ein Bild senden (reAPI akzeptiert nur öffentliche URLs), wie ein Request abgerechnet wird, wie Sie aus Scores Entscheidungen ableiten, und ein lauffähiges Beispiel in Python und JavaScript, das ein Bild einreicht und das Ergebnis abfragt. Zum Schluss geht es darum, wie sich auf Bilder spezialisierte Dienste wie Sightengine, Hive, Azure AI Content Safety und Amazon Rekognition unterscheiden.

TL;DR

omni-moderation-latest bewertet Bilder in 6 Kategorien: sexual, self-harm, self-harm/intent, self-harm/instructions, violence und violence/graphic. Die anderen 7, darunter sexual/minors, gelten nur für Text^[1].
Auf reAPI wird ein Bild als image_url-Block mit einer öffentlichen http(s)-URL übergeben. Base64 und data:-URIs werden abgelehnt^[2].
Abgerechnet wird pro Moderationseinheit: eine Einheit pro Bild, eine pro 1.000 Wörter Text, mindestens eine Einheit pro Request^[2]. Die aktuellen Preise stehen auf der Modellseite.
Der Aufruf ist asynchron: POST /api/v1/moderations, danach GET /api/v1/tasks/{id} abfragen, bis status den Wert completed hat^[2].
flagged ist das Standardurteil des Modells. Für Ihre eigene Richtlinie setzen Sie pro Kategorie Schwellenwerte auf category_scores (0 bis 1) und kalibrieren neu, wenn das Modell aktualisiert wird^[1].
Ob OpenAIs eigener Endpunkt kostenlos ist, behandelt Ist die OpenAI Moderation API kostenlos?.

Welche Schadenskategorien eine Bildmoderations-API erkennen kann

OpenAI listet auf, welche Eingaben jede Kategorie von omni-moderation-latest unterstützt^[1]:

Kategorie	Eingaben
`sexual`	Text und Bilder
`self-harm`, `self-harm/intent`, `self-harm/instructions`	Text und Bilder
`violence`, `violence/graphic`	Text und Bilder
`sexual/minors`	Nur Text
`harassment`, `harassment/threatening`	Nur Text
`hate`, `hate/threatening`	Nur Text
`illicit`, `illicit/violent`	Nur Text

Für eine Bild-Pipeline ergeben sich daraus zwei Konsequenzen.

Erstens ist eine Null nicht immer ein Messwert. OpenAI schreibt, dass das Modell für die reinen Textkategorien einen Score von 0 zurückgibt, wenn Sie nur Bilder ohne begleitenden Text senden^[1]. Ein Hasssymbol in einem Meme oder eine schriftliche Drohung in einem Screenshot wird vom hate- oder harassment-Score eines reinen Bild-Requests nicht erfasst. Die Antwort gibt in category_applied_input_types an, gegen welche Eingabetypen jede Kategorie ausgewertet wurde; in OpenAIs Beispiel mit reiner Bildeingabe steht bei den sechs Bildkategorien ["image"] und bei den übrigen ein leeres Array^[1]. Prüfen Sie dieses Feld, bevor Sie einen niedrigen Score als unbedenklich werten.

Zweitens gilt sexual/minors nur für Text^[1]. OpenAIs Leitfaden sagt außerdem, dass bekanntes oder mutmaßliches Material über sexuellen Kindesmissbrauch nicht an die Moderation API gesendet werden soll, weil sie nicht für die Erkennung von CSAM ausgelegt ist und keinen Ersatz für dedizierte Kinderschutzmaßnahmen darstellt^[1]. Wenn Ihre Plattform Uploads von Nutzern annimmt, planen Sie eine separate Kinderschutzkontrolle ein.

OpenAI dokumentiert für das Modell eine Größenbegrenzung von 20 MB pro Bilddatei^[1].

Bilder senden: nur öffentliche URLs

Der Request-Body hat ein einziges Inhaltsfeld, input. Für Bilder senden Sie ein Array von Content-Blöcken^[2]:

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

OpenAIs eigene API-Referenz besagt, dass image_url.url entweder eine Bild-URL oder base64-kodierte Bilddaten sein kann^[3]. reAPI akzeptiert nur die erste Form: image_url.url muss eine öffentliche http(s)-URL sein, und base64 oder data:-URIs scheitern an der Validierung mit dem Fehler 20003^[2]. Diese Regel gilt für Medieneingaben bei jedem reAPI-Modell.

Für Nutzer-Uploads ergibt sich daraus diese Reihenfolge: Datei speichern, eine URL erzeugen, die aus dem Internet abrufbar ist, dann moderieren. Signierte URLs funktionieren, solange sie bei der Ausführung des Tasks noch gültig sind^[2]. Kann die URL nicht abgerufen werden, schlägt der Task mit 80007 fehl und die Kosten werden erstattet^[2]. Halten Sie das Objekt privat und unveröffentlicht, bis das Ergebnis vorliegt.

Sie können auch eine Bildunterschrift und das zugehörige Foto in dasselbe Array packen. Laut reAPI-Dokumentation liefert ein Array von Content-Blöcken ein Ergebnis für die gesamte Menge, das Modell beurteilt Text und Bild also gemeinsam^[2]. Für einen Post mit Bildunterschrift ist das genau richtig. Für zehn voneinander unabhängige Uploads nicht: Ein gemeinsames Urteil verrät Ihnen nicht, welches Bild es ausgelöst hat, also senden Sie diese als separate Requests.

Wie Bildmoderation abgerechnet wird

reAPI rechnet omni-moderation-latest pro Moderationseinheit ab^[2]:

Eingabe	Einheiten
Jeder `image_url`-Block	1 Einheit
Text	1 Einheit pro 1.000 Wörter, summiert über den Request; jedes Text-Item zählt als mindestens 50 Wörter
Jeder Request	Mindestens 1 Einheit

Einheiten werden einmal pro Request in Credits umgerechnet und aufgerundet, das Abfragen ist kostenlos, und fehlgeschlagene Requests werden automatisch erstattet^[2]. Ein Request nimmt bis zu 500 Items auf^[2]. Der Preis pro Einheit steht auf der Modellseite. Einen anbieterübergreifenden Vergleich von Preisen und Free Tiers finden Sie unter Ist die OpenAI Moderation API kostenlos?.

Bildmoderations-API Beispiel in Python und JavaScript

Beide Beispiele machen dasselbe: ein Bild einreichen, den Task alle 3 Sekunden abfragen und das erste Ergebnis zurückgeben. Die reAPI-Dokumentation zu Tasks empfiehlt, nicht häufiger als alle 2 bis 3 Sekunden abzufragen, weil der Polling-Endpunkt während der Verarbeitung eines Tasks 5 Sekunden lang gecacht wird^[4]. Eine Moderationsprüfung ist in der Regel innerhalb weniger Sekunden abgeschlossen^[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+, gespeichert als `.mjs`-Modul)

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);

Führen Sie die JavaScript-Version auf Ihrem Server aus, nicht im Browser. Der API-Key ist ein Bearer-Token, und wer ihn im Frontend-Code ausliefert, macht ihn für jeden sichtbar, der die Entwicklertools öffnet. Dasselbe gilt für die React-Frage in den FAQ unten. Das vollständige Request-Schema, einschließlich Text- und gemischter Eingaben, steht in der API-Dokumentation.

Das Ergebnis lesen und Schwellenwerte festlegen

Jedes Ergebnis enthält vier Felder^[1]^[2]:

Feld	Was es Ihnen sagt
`flagged`	`true`, wenn das Modell die Eingabe in mindestens einer Kategorie als schädlich einstuft
`categories`	Das true/false-Urteil des Modells pro Kategorie
`category_scores`	Die Konfidenz des Modells pro Kategorie, von 0 bis 1
`category_applied_input_types`	Gegen welche Eingabetypen (`text`, `image`) jede Kategorie ausgewertet wurde

flagged ist ein brauchbarer erster Filter, bildet aber die Standardeinstellungen des Modells ab, die strenger oder lockerer als Ihre Richtlinie sein können^[2]. OpenAI empfiehlt, die Scores als Signale für die Richtlinie Ihrer Anwendung zu behandeln statt als automatische Blockierentscheidung, und markierte Inhalte bei Bedarf in eine Prüfung zu leiten^[1].

Ein verbreitetes Muster sind drei Bereiche pro Bildkategorie: unterhalb eines niedrigen Scores zulassen, im mittleren Bereich an eine manuelle Prüfung geben, oberhalb eines hohen Scores blockieren. Eine minimale Version:

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"

Die Zahlen oben dienen nur zur Veranschaulichung und sind keine Empfehlungen. Ermitteln Sie Ihre eigenen, indem Sie einige hundert bereits gelabelte Bilder durchlaufen lassen und schauen, wo die Scores liegen. Wiederholen Sie diese Prüfung regelmäßig: OpenAI kündigt an, das zugrunde liegende Modell weiter zu verbessern, und eigene Richtlinien auf Basis von category_scores müssen mit der Zeit möglicherweise neu kalibriert werden^[1]. Scores werden auf dem Weg durch reAPI weder gerundet noch umgerechnet^[2], eine einmal vorgenommene Kalibrierung gilt also direkt für die Werte, die Ihr Code liest.

Wie sich auf Bilder spezialisierte Moderations-APIs unterscheiden

Ein Allzweckmodell und ein auf Bilder spezialisierter Dienst beantworten unterschiedliche Fragen. omni-moderation-latest bewertet sechs visuelle Kategorien und kann eine Bildunterschrift zusammen mit ihrem Bild beurteilen^[1]. Spezialisierte Bild-APIs erkennen deutlich mehr visuelle Klassen, etwa Waffen, Drogen, Hasssymbole oder Text im Bild, und unterscheiden sich darin, wie sie die Datei entgegennehmen und wie sie Konfidenz ausweisen. Laut der Dokumentation des jeweiligen Anbieters:

Dienst	Was er in Bildern erkennt	Wie das Bild gesendet wird	Ausgabe	Abrechnungseinheit
`omni-moderation-latest` auf reAPI	sexual, self-harm (3), violence (2)^[1]	Öffentliche http(s)-URL^[2]	Boolean + 0–1-Score pro Kategorie^[1]	Pro Bild (Moderationseinheit)^[2]
Sightengine	Nacktheit in 29 Klassen, Gewalt, Waffen, Hass- und beleidigende Zeichen, Gore, Selbstverletzung, Drogen, Alkohol, Tabak, Glücksspiel, Text in Bildern, QR-Codes^[5]	Direkter Upload oder öffentlich zugängliche URL^[6]	Ergebnisse pro ausgewähltem Modell	Operations; Modelle derselben Gruppe zählen einmal pro Request^[7]
Hive Visual Moderation	Sexuelle Inhalte, gewalttätige Bilder, Drogen, Hassbilder und Bildattribute, aufgeteilt in benannte Klassen^[8]	Öffentliche oder signierte URL oder lokaler Datei-Upload^[9]	0–1-Konfidenz pro Klasse^[9]	Jahresvertrag; kleinere Kunden verweist Hive auf sein Self-Service-VLM^[8]
Azure AI Content Safety (Analyze Image)	Hate, SelfHarm, Sexual, Violence^[10]	Base64-Bytes oder eine Blob-URL, entweder oder^[10]	Schweregrad 0, 2, 4 oder 6 pro Kategorie^[11]	Pro eingereichtem Bild^[12]
Amazon Rekognition (DetectModerationLabels)	Dreistufige Label-Taxonomie; die oberste Ebene umfasst Explicit, Violence, Visually Disturbing, Drugs & Tobacco, Alcohol, Rude Gestures, Gambling und Hate Symbols^[13]	Base64-Bildbytes oder ein Amazon-S3-Objekt; JPEG oder PNG^[14]	Labels mit Konfidenz; `MinConfidence` ist standardmäßig 50^[14]	Pro Bild und API-Aufruf^[15]

Drei Unterschiede geben meist den Ausschlag.

Visuelle Abdeckung. Wenn Sie Waffen, Drogen, Hasssymbole oder in ein Bild eingebrannten Text erkennen müssen, führen die spezialisierten Dienste diese Klassen ausdrücklich auf^[5]^[8]^[13]. omni-moderation-latest hat dafür keine Bildkategorien^[1].

Form der Scores. Hive liefert eine 0–1-Konfidenz pro Klasse und schlägt vor, mit etwa 0,90 als Schwelle zum Markieren einer Klasse zu beginnen^[8]. Rekognition verwirft Labels unterhalb von MinConfidence, standardmäßig 50 auf einer Skala von 0 bis 100^[14]. Azure liefert für Bilder grobe Schweregrade: 0, 2, 4 oder 6^[11]. Ein auf einem Dienst abgestimmter Schwellenwert lässt sich nicht auf einen anderen übertragen.

Umgang mit Eingaben. Azure und Rekognition akzeptieren Base64-Bytes^[10]^[14], Sightengine und Hive einen direkten Datei-Upload^[6]^[9]. reAPI nimmt nur URLs an^[2], was zu Pipelines passt, in denen der Upload ohnehin im Object Storage landet.

omni-moderation-latest passt, wenn Ihre Inhalte überwiegend Text mit angehängten Bildern sind, wenn die sechs visuellen Kategorien zu Ihrer Richtlinie passen oder wenn Sie bereits andere Modelle über reAPI mit demselben Key aufrufen. Einen breiteren Vergleich nach Modalität und Anwendungsfall finden Sie unter Die beste Content Moderation API.

Häufige Fragen

Bildmoderation API kostenlos

OpenAI gibt an, dass sein eigener Moderations-Endpunkt kostenlos nutzbar ist^[1]. Auf reAPI wird omni-moderation-latest nutzungsbasiert mit einer Einheit pro Bild abgerechnet, und fehlgeschlagene Requests werden erstattet^[2]. Free Tiers und Rate Limits der verschiedenen Anbieter werden in Ist die OpenAI Moderation API kostenlos? verglichen.

Hochgeladene Bilder moderieren kostenlose API

Einen Upload zu moderieren läuft in drei Schritten ab: die Datei privat speichern, eine URL erzeugen, die die API abrufen kann (eine signierte URL funktioniert, solange sie gültig ist), dann diese URL einreichen und erst nach dem Ergebnis veröffentlichen^[2]. reAPI akzeptiert weder die Dateibytes noch einen Base64-String direkt^[2]. Welche Dienste ein kostenloses Kontingent haben, steht in Ist die OpenAI Moderation API kostenlos?.

OpenAI Bildmoderation API

Ja, OpenAIs Moderationsmodell verarbeitet Bilder. omni-moderation-latest akzeptiert Text- und Bildeingaben, klassifiziert kein Audio und bewertet Bilder nur in den Kategorien sexual, self-harm und violence^[1]. Die Modell-ID auf reAPI ist dieselbe, omni-moderation-latest, hinter einem asynchronen Task-Endpunkt^[2].

Bildmoderation API Python

Das Python-Beispiel oben ist vollständig: Es sendet einen image_url-Block an /api/v1/moderations, fragt /api/v1/tasks/{id} ab und gibt output.moderation.results[0] zurück. Es braucht nur das Paket requests. Die API-Dokumentation zeigt denselben Aufruf in cURL, Node.js und Go.

Bildmoderation API React

Rufen Sie die Moderations-API aus Ihrem Backend auf, nicht aus einer React-Komponente. Ihre React-App lädt die Datei auf Ihren Server oder in Ihren Storage hoch, Ihr Server ruft die API mit dem Key auf, und der Client erhält nur die Entscheidung. Steht der Bearer-Key im Browser-Code, ist er für jeden Besucher sichtbar.

Kann die ChatGPT API Bilder analysieren?

Ja. OpenAIs Modelle mit Vision-Fähigkeit analysieren Bilder über die Responses API und die Chat Completions API, und zwar aus einer URL, einer Base64-Data-URL oder einer File-ID^[16]. Das ist offenes Bildverständnis. Für einen festen Satz von Schadenskategorien mit Scores von 0 bis 1 ist der Moderations-Endpunkt die dafür gebaute Option^[1].

Beste Bildmoderation API

Das hängt davon ab, was Sie erkennen müssen. Ein Allzweckmodell wie omni-moderation-latest deckt sexuelle Inhalte, Selbstverletzung und Gewalt in Bildern ab und ergänzt Textkategorien für Bildunterschriften^[1]; auf Bilder spezialisierte Dienste decken mehr visuelle Klassen ab (siehe Tabelle oben). Den vollständigen Auswahlleitfaden finden Sie unter Die beste Content Moderation API.

Bildmoderation in einen Upload-Flow einbauen

Ein funktionierendes Setup mit einer Bildmoderations-API ist kurz: in privaten Storage hochladen, die URL moderieren, auf die Scores reagieren, dann veröffentlichen. Denken Sie bei omni-moderation-latest daran, dass nur sechs Kategorien die Pixel betrachten. Fügen Sie dem Request also eine Bildunterschrift oder OCR-Text hinzu, wenn Text in Bildern für Sie relevant ist, und behalten Sie eine separate Kontrolle für den Kinderschutz bei. Starten Sie mit flagged, wechseln Sie zu Schwellenwerten pro Kategorie, sobald Sie gelabelte Daten haben, und prüfen Sie diese Schwellenwerte erneut, wenn sich das Modell ändert.

Zum Ausprobieren fügen Sie eine Bild-URL in den Playground auf der Content-Moderation-Modellseite ein und übernehmen dann das Python- oder JavaScript-Beispiel von oben in Ihr Backend. Die API-Dokumentation listet jedes Feld auf, das diese Bildmoderations-API akzeptiert.