Moderation API

Screen a Prompt

发送文本、图像或两者，并获取判定结果。

Get Moderation Usage

查看您的计费筛查次数和下一笔费用。

概览

Moderation API 会在您的 AI 产品根据用户输入生成内容之前，对用户输入进行筛查。您可以发送提示词文本、图像或两者，Dodo Payments 会返回 allow、flag 或 deny 判定，以及每个内容类别的分数。您可以将其用于任何接受用户输入的图像、视频或文本生成模型之前。默认情况下，Moderation API 对每个商户启用，并使用您现有的 Dodo Payments API 密钥，因此无需注册。Dodo Payments 可以针对单个商户将其关闭，此时调用会返回 403 和 MODERATION_DISABLED。

我们构建 Moderation API 的原因

AI 生成产品会根据用户输入的任何内容创建新内容。您不可能手动审核每条提示词，而一次有害的输出就可能让您的业务面临风险。作为您的 Merchant of Record，Dodo Payments 对通过平台销售的内容承担法律和声誉责任。Merchant Acceptance Policy 会审核 AI 内容生成工具，不允许冒充、深度伪造或露骨内容，包括 AI 生成的内容。生成有害内容、导致大量拒付或被支付合作伙伴标记的账户，可能会被置于审核状态或暂停。我们构建 Moderation API，帮助您在模型创建此类内容之前将其拦截：

在生成之前进行筛查。 被拦截的提示词永远不会到达您的模型，因此不会产生有害输出，也不会为其消耗计算资源。
覆盖生成场景中重要的类别。 筛查会对 17 个类别评分，包括真人相似度、未经同意的私密图像、暗示未成年人的语言，以及真人与色情内容的组合（这会构成色情深度伪造）。
无需接入其他供应商。 API 使用您的 Dodo Payments API 密钥运行，费用从您的余额中扣除。无需单独签订合同、开具发票或创建账户。
保护用户内容隐私。 Dodo Payments 不会存储或记录您筛查的文本和图像。

Moderation API 是供您自行执行政策的工具。它不能替代 Merchant Acceptance Policy，您仍需对产品生成的内容负责。

工作原理

用户提交提示词后、模型运行前，从您的后端调用 Moderation API：每次调用算作一次筛查。在同一次调用中发送的文本和图像算作一次筛查。

判定结果

decision 字段包含判定结果：

判定	含义	操作
`allow`	内容通过筛查。	生成内容。
`flag`	内容超过了需要人工判断的类别阈值。这不是软拒绝。	应用您自己的政策。您可以拦截、发送审核或生成内容。
`deny`	不得生成该内容。	拦截请求并向用户显示错误。

未收到判定结果时不要生成内容。503 表示 Dodo Payments 无法生成判定结果，超时或网络错误也会导致您没有判定结果。将所有这些情况视为拦截，并要求用户重试。

筛查提示词

要筛查提示词，请向 /moderation/screen 发送 POST 请求，并至少提供 text 或 image 之一。请求接受三个字段：

字段	类型	描述
`text`	string	要筛查的文本，最多 8,000 个字符。
`image`	string	要筛查的图像，以 base64 编码，可带或不带 `data:image/...;base64,` 前缀。
`request_id`	string	可选。您为此次筛查指定的标识符，例如生成 ID，最多 128 个字符，且不得包含控制字符。响应会原样返回该标识符。

TypeScript 和 Python SDK 将该端点公开为 client.moderation.screen()。此示例会在 deny、flag 以及任何错误情况下拦截生成：

示例调用实时模式，因为只有实时模式会运行审核模型。测试模式返回模拟判定结果，不会筛查内容。实时模式的筛查会计费。

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

示例将 flag 与 deny 同样处理。如果您的产品允许某些被标记的内容，请检查 triggered，按类别作出决定。

筛查用户编写的文本，而不是您在其外层包装的提示词模板。您自己的模板在每次调用中都相同，不会为筛查增加任何信息。

筛查图像

发送图像以筛查用户上传的参考图像，或在展示生成的图像之前进行筛查。图像必须满足以下要求：

格式为 JPEG、PNG、WebP、GIF 或 BMP。
base64 字符串最多 6,991,530 个字符，解码后的图像最多 5 MiB。
图像必须是单个静态帧。动画 GIF 和 WebP 图像会被拒绝。
最长边至少为 32 像素。

不符合上述任一检查的图像会返回 400 和 MODERATION_INVALID_IMAGE；图像过大时会返回 413 和 MODERATION_INPUT_TOO_LARGE。要筛查图像，请读取文件，将其编码为 base64，然后在 image 中发送。要同时筛查图像及其提示词，请在同一次调用中发送 text 和 image。这算作一次筛查。此示例使用上一个示例中的 client：

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

以处理文本筛查的方式处理图像筛查错误：如果调用抛出错误，请不要生成内容。

读取响应

响应会返回判定结果及其依据：

字段	描述
`decision`	判定结果：`allow`、`flag` 或 `deny`。
`triggered`	分数超过相应类别阈值的类别。对于一般检查返回的 `flag`，可能为空。
`compound_triggered`	当真人相似度和色情内容共同超过组合阈值（即色情深度伪造模式）时为 `true`。
`categories`	内容属于每个类别的概率，范围为 0 到 1。
`provenance`	每个分数的测量方式：`targeted` 表示通过针对该单一类别的检查，`broad` 表示通过覆盖所有类别的一般检查。
`notes`	对判定结果的可读原因。措辞可能发生变化，因此不要解析它。
`normalized_applied`	当文本也经过移除混淆处理的筛查时为 `true`，例如移除不可见字符或形似字符。
`passes`	模型针对此次筛查回答的是非题的数量。
`latency_ms`	筛查耗时，单位为毫秒。
`request_id`	您发送的 `request_id`，或 `null`。

请基于 decision 和 triggered 编写逻辑。每个类别都有自己的阈值，因此在代码中使用单一分数阈值不会与判定结果匹配。

类别

每个响应都会根据 17 个类别对内容评分：

类别	涵盖内容
`violent_crimes`	暴力犯罪。
`sex_related_crimes`	性相关犯罪。
`child_sexual_exploitation`	儿童性剥削。
`suicide_and_self_harm`	自杀和自残。
`indiscriminate_weapons`	化学、生物、放射性、核武器或爆炸性武器。
`intellectual_property`	侵犯版权或商标权。
`defamation`	可能损害真人声誉的虚假描绘。
`non_violent_crimes`	非暴力犯罪。
`hate`	因受保护特征而贬低他人。
`privacy`	关于某人的敏感私密信息。
`specialized_advice`	未经资质说明的金融、医疗、法律或选举建议。
`sexual_content`	色情或露骨性内容。
`non_consensual_intimate_imagery`	脱衣、裸化或性化真人。
`minor_coded_language`	暗示主体为未成年人的年龄相关语言。
`real_person_likeness`	真实、可识别且有姓名的人的相似形象。
`living_artist_style`	模仿特定在世艺术家的标志性风格。
`prompt_injection`	试图覆盖或操纵系统指令。

处理错误

错误会返回标准的 Dodo Payments 错误正文，其中包含 code 和 message。任何错误都不是判定结果，因此都不允许生成内容：

状态	`code`	原因	操作
`400`	`INVALID_REQUEST_PARAMETERS`	请求格式错误，或既没有 `text` 也没有 `image`。	修正请求。
`400`	`MODERATION_INVALID_IMAGE`	无法解码图像、图像为动画或尺寸过小。	发送受支持的静态图像。
`403`	`MODERATION_DISABLED`	Dodo Payments 已为您的业务关闭 Moderation API。	联系支持团队了解原因。
`413`	`MODERATION_INPUT_TOO_LARGE`	`text` 超过 8,000 个字符，或 `image` 超出大小限制。	缩短文本或压缩图像。
`429`	`MODERATION_OVERLOADED`	Moderation 已达到容量上限。这是吞吐量限制，不是判定结果。	等待 `Retry-After` 标头中的秒数，然后重试。
`503`	`MODERATION_UNAVAILABLE`	没有可用的判定结果。	不要生成内容。稍后重试。

SDK 默认会对 429 或 503 重试两次，并在尝试之间等待 Retry-After。重试次数耗尽后，SDK 会抛出错误，您的代码必须拦截请求。

测试集成

测试模式会返回模拟判定结果，且不会调用审核模型，因此您可以免费测试路由逻辑。使用测试模式 API 密钥向 https://test.dodopayments.com 发送请求。默认模拟判定结果为 allow。要获取其他结果，请将以下字符串之一放在 text 的任意位置：

`text` 中的字符串	响应
`dodo_mock_flag`	`200`，且 `decision` 设置为 `flag`
`dodo_mock_deny`	`200`，且 `decision` 设置为 `deny`
`dodo_mock_overloaded`	`429` `MODERATION_OVERLOADED`，包含 `Retry-After: 1`
`dodo_mock_not_ready`	`503` `MODERATION_UNAVAILABLE`

模拟判定结果会附带说明，表明该结果为模拟结果，且其所有类别分数均为 0。测试模式执行与实时模式相同的请求验证。对于图像，它会检查 base64 编码和格式，但不会检查帧数或尺寸。上线前，请确认您的集成能够处理每种情况：

Deny Blocks Generation

发送 dodo_mock_deny，并确认不会调用您的模型。

Flag Follows Your Policy

发送 dodo_mock_flag，并确认您的产品执行方式符合您的政策。

Overload Retries

发送 dodo_mock_overloaded，并确认您的代码会等待 Retry-After，且在没有判定结果时不会生成内容。

An Outage Blocks Generation

发送 dodo_mock_not_ready，并确认不会调用您的模型。

Every Generation Path Screens

检查所有到达您模型的代码路径是否都会先调用 Moderation API。

定价和计费

Moderation API 的费用为每 1,000 次可计费筛查 0.30 美元。没有免费层级，也没有最低消费。可计费筛查是返回判定结果的实时模式筛查。以下筛查免费且不计入费用：

测试模式中的筛查。
返回错误的筛查，包括 429 和 503。

Dodo Payments 按每 1,000 次筛查的完整区块计费。每个完整区块会在一小时内计费，未填满区块的筛查会一直保持未计费状态，直到区块填满。费用从您的 USD 余额中扣除，并以事件类型 moderation_fees 显示在您的余额账本中。Payouts 会将其显示在 Moderation Fees 下。

跟踪用量

要查看用量，请调用 GET /moderation/usage。响应会返回：

字段	描述
`unbilled_screens`	Dodo Payments 尚未向您收取费用的可计费筛查次数。
`screens_to_next_block`	填满下一个 1,000 次区块所需的剩余可计费筛查次数。
`daily`	最近 30 天内您按 UTC 日期统计的可计费筛查次数。没有筛查的日期会被省略。

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)

测试模式不会记录筛查次数，因此用量端点不会返回测试模式活动。

访问权限和隐私

筛查需要具有写入权限的 API 密钥。任何 API 密钥（包括只读密钥）都可以读取用量。请参阅身份验证，了解如何创建密钥并设置其访问级别。 Dodo Payments 不会存储您筛查的文本或图像，也不会将其写入日志。对于每次实时模式筛查，Dodo Payments 会保留时间、判定结果以及您提供的 request_id，用于计费和用量报告。

Usage-Based Billing

向您自己的客户收取每次生成的费用。

Credit-Based Billing

销售生成额度，并按使用次数扣除。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Screen a Prompt

Get Moderation Usage

概览

我们构建 Moderation API 的原因

工作原理

判定结果

筛查提示词

筛查图像

读取响应

类别

处理错误

测试集成

定价和计费

跟踪用量

访问权限和隐私

Usage-Based Billing

Credit-Based Billing

Screen a Prompt

Get Moderation Usage

​概览

​我们构建 Moderation API 的原因

​工作原理

​判定结果

​筛查提示词

​筛查图像

​读取响应

​类别

​处理错误

​测试集成

​定价和计费

​跟踪用量

​访问权限和隐私

Usage-Based Billing

Credit-Based Billing

概览

我们构建 Moderation API 的原因

工作原理

判定结果

筛查提示词

筛查图像

读取响应

类别

处理错误

测试集成

定价和计费

跟踪用量

访问权限和隐私