Moderation API

Screen a Prompt

Send text, an image, or both, and get a verdict.

Get Moderation Usage

See your billable screens and your next charge.

Overview

The Moderation API screens user input before your AI product generates from it. You send the text of a prompt, an image, or both, and Dodo Payments returns a verdict of allow, flag, or deny, together with a score for each content category. Use it in front of any image, video, or text generation model that takes input from your users. The Moderation API is on for every business by default and runs with your existing Dodo Payments API key, so there is nothing to sign up for. Dodo Payments can turn it off for an individual business, and calls then return 403 with MODERATION_DISABLED.

Why We Built the Moderation API

An AI generation product creates new content from whatever its users type. You cannot review each prompt by hand, and one harmful output can put your business at risk. As your Merchant of Record, Dodo Payments is legally and reputationally responsible for what is sold through the platform. The Merchant Acceptance Policy reviews AI content generation tools and does not allow impersonation, deepfakes, or explicit content, including AI-generated content. An account that generates harmful content, excessive chargebacks, or flags from payment partners can be placed under review or suspended. We built the Moderation API so that you can stop this content before your model creates it:

Screen before you generate. A blocked prompt never reaches your model, so no harmful output exists and you spend no compute on it.
Cover the categories that matter for generation. The screen scores 17 categories, including real-person likeness, non-consensual intimate imagery, minor-coded language, and the combination of a real person with sexual content that marks a sexual deepfake.
Integrate without another vendor. The API runs with your Dodo Payments API key, and its fee is debited from your balance. There is no separate contract, invoice, or account.
Keep user content private. Dodo Payments does not store or log the text and images you screen.

The Moderation API is a tool for your own enforcement. It does not replace the Merchant Acceptance Policy, and you remain responsible for what your product generates.

How It Works

Call the Moderation API from your backend after the user submits a prompt and before your model runs: Each call is one screen. Text and an image sent in the same call count as one screen.

Verdicts

The decision field carries the verdict:

Verdict	Meaning	What to do
`allow`	The content passed.	Generate.
`flag`	The content crossed a category threshold that calls for judgement. It is not a soft deny.	Apply your own policy. You can block, send to review, or generate.
`deny`	The content must not be generated.	Block the request and show the user an error.

Do not generate when you receive no verdict. A 503 means Dodo Payments could not produce a verdict, and a timeout or network error leaves you without one. Treat all of these as a block and ask the user to try again.

Screening a Prompt

To screen a prompt, send a POST request to /moderation/screen with at least one of text and image. The request accepts three fields:

Field	Type	Description
`text`	string	The text to screen, up to 8,000 characters.
`image`	string	The image to screen, as base64, with or without a `data:image/...;base64,` prefix.
`request_id`	string	Optional. Your identifier for this screen, such as a generation ID, up to 128 characters with no control characters. The response returns it unchanged.

The TypeScript and Python SDKs expose the endpoint as client.moderation.screen(). This example blocks generation on deny, on flag, and on any error:

The examples call live mode, because only live mode runs the moderation model. Test mode returns mock verdicts and never screens the content. Live mode screens are billed.

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"
  }'

The example treats flag like deny. If your product allows some flagged content, check triggered to decide by category instead.

Screen the text your user wrote, not the prompt template you wrap around it. Your own template is the same on every call and adds nothing to the screen.

Screening Images

Send an image to screen an uploaded reference image, or a generated image before you show it. The image must meet these requirements:

The format is JPEG, PNG, WebP, GIF, or BMP.
The base64 string is at most 6,991,530 characters, and the decoded image is at most 5 MiB.
The image is a single still frame. Animated GIF and WebP images are rejected.
The longest edge is at least 32 pixels.

An image that fails one of these checks returns 400 with MODERATION_INVALID_IMAGE, or 413 with MODERATION_INPUT_TOO_LARGE when it is too large. To screen an image, read the file, encode it as base64, and send it in image. To screen an image and its prompt together, send both text and image in the same call. It counts as one screen. This example uses the client from the previous example:

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 @-

Handle errors from an image screen the same way as a text screen: if the call throws, do not generate.

Reading the Response

The response returns the verdict and the evidence behind it:

Field	Description
`decision`	The verdict: `allow`, `flag`, or `deny`.
`triggered`	The categories whose score crossed the threshold of the category. It can be empty on a `flag` from the general check.
`compound_triggered`	`true` when real-person likeness and sexual content together crossed their combined threshold, the pattern of a sexual deepfake.
`categories`	The probability, from 0 to 1, that the content falls in each category.
`provenance`	How each score was measured: `targeted` by a check for that one category, or `broad` by the general check that covers all categories.
`notes`	Human-readable reasons for the decision. The wording can change, so do not parse it.
`normalized_applied`	`true` when the text was also screened with obfuscation removed, such as invisible or look-alike characters.
`passes`	The number of yes/no questions the model answered for this screen.
`latency_ms`	The time the screen took, in milliseconds.
`request_id`	The `request_id` you sent, or `null`.

Base your logic on decision and triggered. Each category has its own threshold, so a single score cut-off in your code does not match the verdict.

Category	Covers
`violent_crimes`	Violent crimes.
`sex_related_crimes`	Sex-related crimes.
`child_sexual_exploitation`	Child sexual exploitation.
`suicide_and_self_harm`	Suicide and self-harm.
`indiscriminate_weapons`	Chemical, biological, radiological, nuclear, or explosive weapons.
`intellectual_property`	Copyright or trademark infringement.
`defamation`	False depiction that is likely to injure the reputation of a real person.
`non_violent_crimes`	Non-violent crimes.
`hate`	Demeaning people because of a protected characteristic.
`privacy`	Sensitive private information about a person.
`specialized_advice`	Unqualified financial, medical, legal, or electoral advice.
`sexual_content`	Sexually explicit or pornographic content.
`non_consensual_intimate_imagery`	Undressing, nudifying, or sexualizing a real person.
`minor_coded_language`	Age-coded language that suggests the subject is a minor.
`real_person_likeness`	The likeness of a real, identifiable, named person.
`living_artist_style`	Imitation of the signature style of a specific living artist.
`prompt_injection`	An attempt to override or manipulate the instructions of the system.

Handling Errors

Errors return the standard Dodo Payments error body with a code and a message. No error is a verdict, so none of them allow generation:

Status	`code`	Cause	What to do
`400`	`INVALID_REQUEST_PARAMETERS`	The request is malformed, or it has neither `text` nor `image`.	Fix the request.
`400`	`MODERATION_INVALID_IMAGE`	The image cannot be decoded, is animated, or is too small.	Send a supported still image.
`403`	`MODERATION_DISABLED`	Dodo Payments has turned off the Moderation API for your business.	Contact support to find out why.
`413`	`MODERATION_INPUT_TOO_LARGE`	`text` is over 8,000 characters, or `image` is over the size limit.	Shorten the text or shrink the image.
`429`	`MODERATION_OVERLOADED`	Moderation is at capacity. This is a throughput limit, not a verdict.	Wait for the seconds in the `Retry-After` header, then retry.
`503`	`MODERATION_UNAVAILABLE`	No verdict is available.	Do not generate. Retry later.

The SDKs retry a 429 or a 503 twice by default and wait for Retry-After between attempts. When the retries run out, the SDK raises an error, and your code must block the request.

Testing Your Integration

Test mode returns mock verdicts and never calls the moderation model, so you can test your routing without cost. Send requests to https://test.dodopayments.com with a test mode API key. The default mock verdict is allow. To get another outcome, put one of these strings anywhere in text:

String in `text`	Response
`dodo_mock_flag`	`200` with `decision` set to `flag`
`dodo_mock_deny`	`200` with `decision` set to `deny`
`dodo_mock_overloaded`	`429` `MODERATION_OVERLOADED` with `Retry-After: 1`
`dodo_mock_not_ready`	`503` `MODERATION_UNAVAILABLE`

A mock verdict carries a note that says it is a mock, and all its category scores are 0. Test mode applies the same request validation as live mode. For images, it checks the base64 encoding and the format, but not the frame count or the dimensions. Before you go live, confirm that your integration handles each case:

Deny Blocks Generation

Send dodo_mock_deny and confirm your model is not called.

Flag Follows Your Policy

Send dodo_mock_flag and confirm your product does what your policy says.

Overload Retries

Send dodo_mock_overloaded and confirm your code waits for Retry-After and does not generate without a verdict.

An Outage Blocks Generation

Send dodo_mock_not_ready and confirm your model is not called.

Every Generation Path Screens

Check that every code path that reaches your model calls the Moderation API first.

Pricing and Billing

The Moderation API costs $0.30 USD per 1,000 billable screens. There is no free tier and no minimum. A billable screen is a live mode screen that returns a verdict. These screens are free and not counted:

Screens in test mode.
Screens that return an error, including 429 and 503.

Dodo Payments bills in full blocks of 1,000 screens. Each full block is charged within one hour, and screens that do not fill a block stay unbilled until they do. The fee is debited from your USD balance and appears in your balance ledger with the event type moderation_fees. Payouts show it under Moderation Fees.

Tracking Usage

To see your usage, call GET /moderation/usage. The response returns:

Field	Description
`unbilled_screens`	Billable screens that Dodo Payments has not charged for yet.
`screens_to_next_block`	Billable screens still needed to fill the next block of 1,000.
`daily`	Your billable screens per UTC day for the last 30 days. Days with no screens are omitted.

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)

Test mode records no screens, so the usage endpoint returns no test mode activity.

Access and Privacy

Screening requires an API key with write access. Any API key, including a read-only key, can read usage. See Authentication for how to create a key and set its access level. Dodo Payments does not store the text or images you screen, and does not write them to logs. For each live mode screen, it keeps the time, the verdict, and your request_id for billing and usage reporting.

Usage-Based Billing

Charge your own customers for each generation.

Credit-Based Billing

Sell generation credits and deduct them per use.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Screen a Prompt

Get Moderation Usage

Overview

Why We Built the Moderation API

How It Works

Verdicts

Screening a Prompt

Screening Images

Reading the Response

Categories

Handling Errors

Testing Your Integration

Pricing and Billing

Tracking Usage

Access and Privacy

Usage-Based Billing

Credit-Based Billing

Screen a Prompt

Get Moderation Usage

​Overview

​Why We Built the Moderation API

​How It Works

​Verdicts

​Screening a Prompt

​Screening Images

​Reading the Response

​Categories

​Handling Errors

​Testing Your Integration

​Pricing and Billing

​Tracking Usage

​Access and Privacy

Usage-Based Billing

Credit-Based Billing

Overview

Why We Built the Moderation API

How It Works

Verdicts

Screening a Prompt

Screening Images

Reading the Response

Categories

Handling Errors

Testing Your Integration

Pricing and Billing

Tracking Usage

Access and Privacy