Moderation API

Screen a Prompt

Invia testo, un’immagine o entrambi e ottieni un verdetto.

Get Moderation Usage

Visualizza le screen fatturabili e il tuo prossimo addebito.

Panoramica

La Moderation API analizza l’input dell’utente prima che il tuo prodotto AI lo utilizzi per generare contenuti. Invia il testo di un prompt, un’immagine o entrambi, e Dodo Payments restituisce un verdetto allow, flag o deny, insieme a un punteggio per ogni categoria di contenuto. Usala prima di qualsiasi modello di generazione di immagini, video o testo che riceva input dagli utenti. La Moderation API è attiva per impostazione predefinita per ogni attività e utilizza la tua chiave API Dodo Payments esistente, quindi non devi effettuare alcuna registrazione. Dodo Payments può disattivarla per una singola attività; in tal caso, le chiamate restituiscono 403 con MODERATION_DISABLED.

Perché abbiamo creato la Moderation API

Un prodotto di generazione AI crea nuovi contenuti a partire da qualunque testo inseriscano gli utenti. Non puoi esaminare manualmente ogni prompt e un singolo output dannoso può mettere a rischio la tua attività. In qualità di Merchant of Record, Dodo Payments è legalmente e a livello reputazionale responsabile di ciò che viene venduto attraverso la piattaforma. La Merchant Acceptance Policy esamina gli strumenti di generazione di contenuti AI e non consente impersonificazione, deepfake o contenuti espliciti, inclusi quelli generati dall’AI. Un account che genera contenuti dannosi, un numero eccessivo di chargeback o segnalazioni da parte dei partner di pagamento può essere sottoposto a revisione o sospeso. Abbiamo creato la Moderation API per consentirti di bloccare questi contenuti prima che il modello li crei:

Analizza prima di generare. Un prompt bloccato non raggiunge mai il modello, quindi non viene creato alcun output dannoso e non consumi risorse di calcolo.
Copri le categorie importanti per la generazione. La screen assegna un punteggio a 17 categorie, tra cui somiglianza con persone reali, immagini intime non consensuali, linguaggio che indica minori e la combinazione di una persona reale con contenuti sessuali che identifica un deepfake sessuale.
Integra senza un altro fornitore. L’API utilizza la tua chiave API Dodo Payments e il relativo costo viene addebitato sul tuo saldo. Non sono necessari contratti, fatture o account separati.
Mantieni privati i contenuti degli utenti. Dodo Payments non archivia né registra nei log il testo e le immagini che analizzi.

La Moderation API è uno strumento per le tue attività di enforcement. Non sostituisce la Merchant Acceptance Policy e resti responsabile di ciò che il tuo prodotto genera.

Come funziona

Chiama la Moderation API dal tuo backend dopo che l’utente ha inviato un prompt e prima che venga eseguito il modello: Ogni chiamata corrisponde a una screen. Il testo e un’immagine inviati nella stessa chiamata vengono conteggiati come una sola screen.

Verdict

Il campo decision contiene il verdetto:

Verdetto	Significato	Cosa fare
`allow`	Il contenuto è stato approvato.	Genera.
`flag`	Il contenuto ha superato una soglia di categoria che richiede una valutazione. Non si tratta di un soft deny.	Applica la tua policy. Puoi bloccare, inviare a revisione o generare.
`deny`	Il contenuto non deve essere generato.	Blocca la richiesta e mostra un errore all’utente.

Non generare quando non ricevi alcun verdetto. Un 503 significa che Dodo Payments non ha potuto produrre un verdetto; anche un timeout o un errore di rete ti lascia senza verdetto. Tratta tutti questi casi come un blocco e chiedi all’utente di riprovare.

Analisi di un prompt

Per analizzare un prompt, invia una richiesta POST a /moderation/screen con almeno uno tra text e image. La richiesta accetta tre campi:

Campo	Tipo	Descrizione
`text`	string	Il testo da analizzare, fino a 8.000 caratteri.
`image`	string	L’immagine da analizzare, in base64, con o senza il prefisso `data:image/...;base64,`.
`request_id`	string	Facoltativo. Il tuo identificatore per questa screen, ad esempio un ID di generazione, fino a 128 caratteri senza caratteri di controllo. La risposta lo restituisce invariato.

Gli SDK TypeScript e Python espongono l’endpoint come client.moderation.screen(). Questo esempio blocca la generazione con deny, con flag e in caso di errore:

Gli esempi utilizzano la live mode, perché solo la live mode esegue il modello di moderazione. La test mode restituisce verdetti simulati e non analizza mai il contenuto. Le screen in live mode sono fatturate.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
});

async function generateImage(prompt: string, generationId: string) {
  let verdict;
  try {
    verdict = await client.moderation.screen({
      text: prompt,
      request_id: generationId,
    });
  } catch (err) {
    // No verdict: do not generate.
    throw new Error('Moderation is unavailable. Try again in a moment.');
  }

  if (verdict.decision !== 'allow') {
    throw new Error('This prompt cannot be generated. Revise it and try again.');
  }

  return myModel.generate(prompt);
}

import os
from dodopayments import DodoPayments, APIError

client = DodoPayments(
    bearer_token=os.environ["DODO_PAYMENTS_API_KEY"],
    environment="live_mode",
)

def generate_image(prompt: str, generation_id: str):
    try:
        verdict = client.moderation.screen(text=prompt, request_id=generation_id)
    except APIError:
        # No verdict: do not generate.
        raise RuntimeError("Moderation is unavailable. Try again in a moment.")

    if verdict.decision != "allow":
        raise ValueError("This prompt cannot be generated. Revise it and try again.")

    return my_model.generate(prompt)

curl -X POST https://live.dodopayments.com/moderation/screen \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "a watercolor painting of a lighthouse at sunset",
    "request_id": "gen_7Hc2k9"
  }'

L’esempio tratta flag come deny. Se il tuo prodotto consente alcuni contenuti segnalati, controlla triggered per decidere in base alla categoria.

Analizza il testo scritto dall’utente, non il prompt template che lo avvolge. Il tuo template è uguale in ogni chiamata e non aggiunge nulla alla screen.

Analisi delle immagini

Invia un’immagine per analizzare un’immagine di riferimento caricata o un’immagine generata prima di mostrarla. L’immagine deve soddisfare questi requisiti:

Il formato è JPEG, PNG, WebP, GIF o BMP.
La stringa base64 contiene al massimo 6.991.530 caratteri e l’immagine decodificata ha dimensioni massime di 5 MiB.
L’immagine è un singolo fotogramma statico. Le immagini GIF e WebP animate vengono rifiutate.
Il lato più lungo misura almeno 32 pixel.

Un’immagine che non supera uno di questi controlli restituisce 400 con MODERATION_INVALID_IMAGE oppure 413 con MODERATION_INPUT_TOO_LARGE quando è troppo grande. Per analizzare un’immagine, leggi il file, codificalo in base64 e invialo in image. Per analizzare insieme un’immagine e il relativo prompt, invia entrambi text e image nella stessa chiamata. Viene conteggiata come una sola screen. Questo esempio utilizza client dell’esempio precedente:

import { readFile } from 'node:fs/promises';

async function screenImage(path: string, prompt: string, generationId: string) {
  const image = (await readFile(path)).toString('base64');

  const verdict = await client.moderation.screen({
    image, // or `data:image/png;base64,${image}`
    text: prompt, // optional: screen the prompt with the image
    request_id: generationId,
  });

  return verdict.decision === 'allow';
}

import base64

def screen_image(path: str, prompt: str, generation_id: str) -> bool:
    with open(path, "rb") as f:
        image = base64.b64encode(f.read()).decode("ascii")

    verdict = client.moderation.screen(
        image=image,  # or f"data:image/png;base64,{image}"
        text=prompt,  # optional: screen the prompt with the image
        request_id=generation_id,
    )
    return verdict.decision == "allow"

# Builds the JSON body with jq, so a large image does not hit the shell argument limit.
base64 < reference.png | tr -d '\n' \
  | jq -Rs '{image: ., text: "turn this photo into a watercolor painting", request_id: "gen_7Hc2k9"}' \
  | curl -X POST https://live.dodopayments.com/moderation/screen \
      -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
      -H "Content-Type: application/json" \
      --data @-

Gestisci gli errori di una screen di immagini nello stesso modo di una screen di testo: se la chiamata genera un’eccezione, non generare.

Lettura della risposta

La risposta restituisce il verdetto e le informazioni che lo motivano:

Campo	Descrizione
`decision`	Il verdetto: `allow`, `flag` o `deny`.
`triggered`	Le categorie il cui punteggio ha superato la soglia della categoria. Può essere vuoto per un `flag` derivante dal controllo generale.
`compound_triggered`	`true` quando la somiglianza con una persona reale e i contenuti sessuali hanno insieme superato la soglia combinata, il modello tipico di un deepfake sessuale.
`categories`	La probabilità, da 0 a 1, che il contenuto rientri in ciascuna categoria.
`provenance`	Come è stato misurato ogni punteggio: `targeted` tramite un controllo per quella singola categoria oppure `broad` tramite il controllo generale che copre tutte le categorie.
`notes`	Motivi leggibili dall’utente per la decisione. La formulazione può cambiare, quindi non analizzarla programmaticamente.
`normalized_applied`	`true` quando il testo è stato analizzato anche dopo aver rimosso l’offuscamento, ad esempio caratteri invisibili o simili.
`passes`	Il numero di domande sì/no a cui il modello ha risposto per questa screen.
`latency_ms`	Il tempo impiegato dalla screen, in millisecondi.
`request_id`	L’`request_id` che hai inviato oppure `null`.

Basa la logica su decision e triggered. Ogni categoria ha una propria soglia, quindi un’unica soglia di punteggio nel codice non corrisponde al verdetto.

Categorie

Ogni risposta assegna un punteggio al contenuto rispetto a 17 categorie:

Categoria	Include
`violent_crimes`	Crimini violenti.
`sex_related_crimes`	Crimini a sfondo sessuale.
`child_sexual_exploitation`	Sfruttamento sessuale di minori.
`suicide_and_self_harm`	Suicidio e autolesionismo.
`indiscriminate_weapons`	Armi chimiche, biologiche, radiologiche, nucleari o esplosive.
`intellectual_property`	Violazione del copyright o del marchio.
`defamation`	Rappresentazione falsa che potrebbe danneggiare la reputazione di una persona reale.
`non_violent_crimes`	Crimini non violenti.
`hate`	Denigrazione di persone a causa di una caratteristica protetta.
`privacy`	Informazioni private sensibili su una persona.
`specialized_advice`	Consulenza finanziaria, medica, legale o elettorale non qualificata.
`sexual_content`	Contenuti sessualmente espliciti o pornografici.
`non_consensual_intimate_imagery`	Spogliare, denudare o sessualizzare una persona reale.
`minor_coded_language`	Linguaggio che indica un’età e suggerisce che il soggetto sia minorenne.
`real_person_likeness`	La somiglianza di una persona reale, identificabile e nominata.
`living_artist_style`	Imitazione dello stile caratteristico di uno specifico artista vivente.
`prompt_injection`	Un tentativo di sovrascrivere o manipolare le istruzioni del sistema.

Gestione degli errori

Gli errori restituiscono il corpo di errore standard di Dodo Payments con un code e un message. Nessun errore costituisce un verdetto, quindi nessuno consente la generazione:

Status	`code`	Causa	Cosa fare
`400`	`INVALID_REQUEST_PARAMETERS`	La richiesta non è valida oppure non contiene né `text` né `image`.	Correggi la richiesta.
`400`	`MODERATION_INVALID_IMAGE`	L’immagine non può essere decodificata, è animata o è troppo piccola.	Invia un’immagine statica supportata.
`403`	`MODERATION_DISABLED`	Dodo Payments ha disattivato la Moderation API per la tua attività.	Contatta l’assistenza per sapere perché.
`413`	`MODERATION_INPUT_TOO_LARGE`	`text` supera gli 8.000 caratteri oppure `image` supera il limite di dimensione.	Riduci il testo o le dimensioni dell’immagine.
`429`	`MODERATION_OVERLOADED`	La moderazione ha raggiunto la capacità massima. Si tratta di un limite di throughput, non di un verdetto.	Attendi i secondi indicati nell’header `Retry-After`, quindi riprova.
`503`	`MODERATION_UNAVAILABLE`	Non è disponibile alcun verdetto.	Non generare. Riprova più tardi.

Per impostazione predefinita, gli SDK ritentano due volte un 429 o un 503 e attendono Retry-After tra un tentativo e l’altro. Quando i tentativi terminano, lo SDK genera un errore e il codice deve bloccare la richiesta.

Test dell’integrazione

La test mode restituisce verdetti simulati e non chiama mai il modello di moderazione, consentendoti di testare il routing senza costi. Invia le richieste a https://test.dodopayments.com con una chiave API in test mode. Il verdetto simulato predefinito è allow. Per ottenere un risultato diverso, inserisci una di queste stringhe in qualsiasi punto di text:

Stringa in `text`	Risposta
`dodo_mock_flag`	`200` con `decision` impostato su `flag`
`dodo_mock_deny`	`200` con `decision` impostato su `deny`
`dodo_mock_overloaded`	`429` `MODERATION_OVERLOADED` con `Retry-After: 1`
`dodo_mock_not_ready`	`503` `MODERATION_UNAVAILABLE`

Un verdetto simulato contiene una nota che indica che è simulato e tutti i punteggi delle categorie sono 0. La test mode applica la stessa validazione delle richieste della live mode. Per le immagini controlla la codifica base64 e il formato, ma non il numero di fotogrammi o le dimensioni. Prima di passare alla live mode, verifica che l’integrazione gestisca ogni caso:

Deny Blocks Generation

Invia dodo_mock_deny e verifica che il modello non venga chiamato.

Flag Follows Your Policy

Invia dodo_mock_flag e verifica che il prodotto si comporti come previsto dalla tua policy.

Overload Retries

Invia dodo_mock_overloaded e verifica che il codice attenda Retry-After e non generi senza un verdetto.

An Outage Blocks Generation

Invia dodo_mock_not_ready e verifica che il modello non venga chiamato.

Every Generation Path Screens

Verifica che ogni percorso del codice che raggiunge il modello chiami prima la Moderation API.

Prezzi e fatturazione

La Moderation API costa 0,30 USD per 1.000 screen fatturabili. Non sono previsti un piano gratuito né un minimo. Una screen fatturabile è una screen in live mode che restituisce un verdetto. Queste screen sono gratuite e non vengono conteggiate:

Le screen in test mode.
Le screen che restituiscono un errore, inclusi 429 e 503.

Dodo Payments fattura blocchi completi di 1.000 screen. Ogni blocco completo viene addebitato entro un’ora; le screen che non completano un blocco restano non fatturate fino al raggiungimento del blocco. Il costo viene addebitato sul tuo saldo in USD e compare nel tuo balance ledger con il tipo di evento moderation_fees. Nei payout compare nella sezione Moderation Fees.

Monitoraggio dell’utilizzo

Per visualizzare il tuo utilizzo, chiama GET /moderation/usage. La risposta restituisce:

Campo	Descrizione
`unbilled_screens`	Screen fatturabili che Dodo Payments non ha ancora addebitato.
`screens_to_next_block`	Screen fatturabili ancora necessarie per completare il prossimo blocco di 1.000.
`daily`	Le tue screen fatturabili per giorno UTC negli ultimi 30 giorni. I giorni senza screen vengono omessi.

curl https://live.dodopayments.com/moderation/usage \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

const usage = await client.moderation.retrieveUsage();
console.log(usage.unbilled_screens, usage.screens_to_next_block);

usage = client.moderation.retrieve_usage()
print(usage.unbilled_screens, usage.screens_to_next_block)

La test mode non registra alcuna screen, quindi l’endpoint di utilizzo non restituisce attività in test mode.

Accesso e privacy

L’analisi richiede una chiave API con accesso in scrittura. Qualsiasi chiave API, inclusa una chiave di sola lettura, può leggere i dati di utilizzo. Consulta Authentication per sapere come creare una chiave e impostarne il livello di accesso. Dodo Payments non archivia il testo o le immagini che analizzi e non li scrive nei log. Per ogni screen in live mode, conserva l’orario, il verdetto e il tuo request_id per la fatturazione e i report sull’utilizzo.

Usage-Based Billing

Addebita i tuoi clienti per ogni generazione.

Credit-Based Billing

Vendi crediti di generazione e detr###ai il costo a ogni utilizzo.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Screen a Prompt

Get Moderation Usage

Panoramica

Perché abbiamo creato la Moderation API

Come funziona

Verdict

Analisi di un prompt

Analisi delle immagini

Lettura della risposta

Categorie

Gestione degli errori

Test dell’integrazione

Prezzi e fatturazione

Monitoraggio dell’utilizzo

Accesso e privacy

Usage-Based Billing

Credit-Based Billing

Screen a Prompt

Get Moderation Usage

​Panoramica

​Perché abbiamo creato la Moderation API

​Come funziona

​Verdict

​Analisi di un prompt

​Analisi delle immagini

​Lettura della risposta

​Categorie

​Gestione degli errori

​Test dell’integrazione

​Prezzi e fatturazione

​Monitoraggio dell’utilizzo

​Accesso e privacy

Usage-Based Billing

Credit-Based Billing

Panoramica

Perché abbiamo creato la Moderation API

Come funziona

Verdict

Analisi di un prompt

Analisi delle immagini

Lettura della risposta

Categorie

Gestione degli errori

Test dell’integrazione

Prezzi e fatturazione

Monitoraggio dell’utilizzo

Accesso e privacy