> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Moderation API > Analizza prompt e immagini prima che il tuo prodotto AI generi contenuti e ottieni un verdetto allow, flag o deny con un punteggio per 17 categorie di contenuti. Invia testo, un'immagine o entrambi e ottieni un verdetto. 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](/miscellaneous/merchant-acceptance) 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: ```mermaid theme={null} flowchart LR A[User submits a prompt] --> B[Your backend calls POST /moderation/screen] B -->|allow| C[Generate] B -->|flag| D[Apply your own policy] B -->|deny| E[Block the request] B -->|error, no verdict| E ``` 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](#testing-your-integration) e non analizza mai il contenuto. Le screen in live mode sono fatturate. ```typescript Node.js expandable theme={null} 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); } ``` ```python Python expandable theme={null} 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) ``` ```bash cURL theme={null} 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: ```typescript Node.js expandable theme={null} 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'; } ``` ```python Python expandable theme={null} 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" ``` ```bash cURL expandable theme={null} # 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: Invia `dodo_mock_deny` e verifica che il modello non venga chiamato. Invia `dodo_mock_flag` e verifica che il prodotto si comporti come previsto dalla tua policy. Invia `dodo_mock_overloaded` e verifica che il codice attenda `Retry-After` e non generi senza un verdetto. Invia `dodo_mock_not_ready` e verifica che il modello non venga chiamato. 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](/api-reference/balance-ledger/list-ledger-entries) 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. | ```bash cURL theme={null} curl https://live.dodopayments.com/moderation/usage \ -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" ``` ```typescript Node.js theme={null} const usage = await client.moderation.retrieveUsage(); console.log(usage.unbilled_screens, usage.screens_to_next_block); ``` ```python Python theme={null} 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](/api-reference/introduction#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. Addebita i tuoi clienti per ogni generazione. Vendi crediti di generazione e detr###ai il costo a ogni utilizzo.