> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Omni Moderation

> 使用 OpenAI 异步审核文本和 HTTPS 图像。

Omni Moderation 使用 OpenAI `omni-moderation-latest` 审核文本、最多一张 HTTPS 图像，或两者同时审核。通过统一的生成接口提交审核，然后用返回的 `task_id` 轮询[查询任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)，或接收可选的回调。

提交后会立即返回 `status: "not_started"`。审核异步执行，状态经过 `running` 后变为 `finished` 或 `failed`。

> [!NOTE]
>
> 通过可选的外层 `callback_url` 字段支持回调。不支持流式输出；请勿传入 `stream`。

## 输入

| 字段 | 类型 | 说明 |
| - | - | - |
| `model` | string | 必须为 `omni-moderation-latest` |
| `callback_url` | string (URI) | 可选，任务完成或失败时通知的 Webhook URL |
| `input.prompt` | string | 可选，待审核的文本；可与一张图像同时提供 |
| `input.image_urls` | string\[] | 可选，最多包含一个 HTTPS 图像 URL 的数组 |

**`prompt` 和 `image_urls` 至少提供一个，也可以同时提供。** 使用非空白文本、一个 HTTPS 图像 URL，或两者都用。`image_urls` 仍为数组，最多接受一张图像。多张图像请分别提交为独立任务。空输入会被拒绝。

## 提交审核

```bash theme={"dark"}
curl -X POST https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-moderation-latest",
    "input": {
      "prompt": "A peaceful mountain landscape."
    }
  }'
```

同时审核图像和文本：

```json theme={"dark"}
{
  "model": "omni-moderation-latest",
  "input": {
    "prompt": "A mountain view at sunset.",
    "image_urls": [
      "https://example.com/image.jpg"
    ]
  }
}
```

只审核图像时，省略 `prompt`。如需通过 Webhook 接收已完成的任务，请在 `input` 之外提供 `callback_url`：

```json theme={"dark"}
{
  "model": "omni-moderation-latest",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A peaceful mountain landscape."
  }
}
```

### 提交响应

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "MODERATION_TASK_ID",
    "status": "not_started",
    "created_time": "2026-10-14T10:00:00"
  }
}
```

## 获取结果

```bash theme={"dark"}
curl https://api.poyo.ai/api/generate/status/MODERATION_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

持续轮询，直到 `data.status` 变为 `finished` 或 `failed`。审核完成后，`data.output` 中返回完整的 OpenAI 响应；`data.files` 为空，`data.credits_amount` 为 `0`。

| 字段 | 类型 | 说明 |
| - | - | - |
| `data.output.id` | string | OpenAI 审核响应的标识符 |
| `data.output.model` | string | OpenAI 返回的模型标识符，可能是带日期的模型版本 |
| `data.output.results` | array | OpenAI 审核结果 |
| `data.output.results[].flagged` | boolean | OpenAI 是否标记了被审核内容 |
| `data.output.results[].categories` | object | 按类别给出的分类布尔值 |
| `data.output.results[].category_scores` | object | 按类别给出的置信度分数 |
| `data.output.results[].category_applied_input_types` | object | 每个类别所使用的输入模态 |

`status: "finished"` 表示审核已完成。`flagged: true` 的结果是一次检测到相关内容的成功审核，不会使任务变为 `failed`。只有任务本身失败时才需要查看 `data.error_message`。

## 回调请求体

提供 `callback_url` 时，任务变为 `finished` 或 `failed` 后，PoYo 会发送 POST 请求。请求体是状态响应中的 `data` 对象，不含外层的 `code` 和 `data` 包装。其中包括 `task_id`、`status`、`credits_amount: 0`、`files: []`，以及可用时位于 `output` 中的完整 OpenAI 响应。失败的任务会提供 `error_message`。

签名验证见 [Webhook 回调](https://docs.poyo.ai/zh/api-manual/task-management/webhooks.md)。

## 已完成状态响应示例

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "MODERATION_TASK_ID",
    "status": "finished",
    "credits_amount": 0,
    "files": [],
    "output": {
      "id": "modr_example",
      "model": "omni-moderation-latest",
      "results": [
        {
          "flagged": false,
          "categories": {
            "harassment": false,
            "harassment/threatening": false,
            "hate": false,
            "hate/threatening": false,
            "illicit": false,
            "illicit/violent": false,
            "self-harm": false,
            "self-harm/intent": false,
            "self-harm/instructions": false,
            "sexual": false,
            "sexual/minors": false,
            "violence": false,
            "violence/graphic": false
          },
          "category_scores": {
            "harassment": 0.00001,
            "harassment/threatening": 0.00001,
            "hate": 0.00001,
            "hate/threatening": 0.00001,
            "illicit": 0.00001,
            "illicit/violent": 0.00001,
            "self-harm": 0.00001,
            "self-harm/intent": 0.00001,
            "self-harm/instructions": 0.00001,
            "sexual": 0.00001,
            "sexual/minors": 0.00001,
            "violence": 0.00001,
            "violence/graphic": 0.00001
          },
          "category_applied_input_types": {
            "harassment": [
              "text"
            ],
            "harassment/threatening": [
              "text"
            ],
            "hate": [
              "text"
            ],
            "hate/threatening": [
              "text"
            ],
            "illicit": [
              "text"
            ],
            "illicit/violent": [
              "text"
            ],
            "self-harm": [
              "text"
            ],
            "self-harm/intent": [
              "text"
            ],
            "self-harm/instructions": [
              "text"
            ],
            "sexual": [
              "text"
            ],
            "sexual/minors": [
              "text"
            ],
            "violence": [
              "text"
            ],
            "violence/graphic": [
              "text"
            ]
          }
        }
      ]
    },
    "created_time": "2026-10-14T10:00:00",
    "progress": 100,
    "error_message": null
  }
}
```


## OpenAPI

````yaml zh/api-manual/moderation-series/omni-moderation.json POST /api/generate/submit
openapi: 3.1.0
info:
  title: PoYo AI - Omni Moderation API
  description: >-
    Omni Moderation 通过 OpenAI 异步审核文本和 HTTPS 图片。通过统一生成 API 提交，然后轮询任务状态，或通过回调接收
    output 中的完整 OpenAI 响应。不支持流式输出。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Moderation
      summary: 提交 Omni Moderation 审核
      description: >-
        将文本、最多一个 HTTPS 图片 URL 或两者一起加入审核队列。立即返回 not_started 状态的任务；可轮询任务状态或提供
        callback_url 获取完成通知。被标记（flagged）的审核同样以 finished 状态完成。不支持流式输出。
      operationId: submitOmniModerationTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-only:
                summary: 审核文本
                value:
                  model: omni-moderation-latest
                  input:
                    prompt: A peaceful mountain landscape.
              image-only:
                summary: 审核 HTTPS 图片
                value:
                  model: omni-moderation-latest
                  input:
                    image_urls:
                      - https://example.com/image.jpg
              text-and-image:
                summary: 审核文本和图片
                value:
                  model: omni-moderation-latest
                  input:
                    prompt: A mountain view at sunset.
                    image_urls:
                      - https://example.com/image.jpg
              with-callback:
                summary: 带完成回调的审核
                value:
                  model: omni-moderation-latest
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: A peaceful mountain landscape.
      responses:
        '200':
          description: >-
            任务已入队，状态为 not_started。可轮询 GET
            /api/generate/status/{task_id}，或在完成后接收可选的回调。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              example:
                code: 200
                data:
                  task_id: MODERATION_TASK_ID
                  status: not_started
                  created_time: '2026-10-14T10:00:00'
        '400':
          description: 模型输入无效或使用了不支持的 stream 参数。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API Key 无效。
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      description: 将 Omni Moderation 审核加入异步队列。可提供可选的 callback_url 接收完成通知。不支持流式输出。
      properties:
        model:
          type: string
          enum:
            - omni-moderation-latest
          description: 公开的模型标识。
          example: omni-moderation-latest
        callback_url:
          type: string
          format: uri
          description: >-
            可选的 Webhook 回调 URL。任务完成或失败时，POST 请求体为状态响应中的 data 对象，不含外层 code/data
            包装。
          example: https://your-domain.com/callback
        input:
          type: object
          additionalProperties: false
          description: >-
            prompt 和 image_urls 至少提供一个，也可同时提供。请提供非空白文本或一个 HTTPS 图片
            URL。image_urls 最多接受一个 HTTPS 图片 URL，prompt 可与图片一起提供。
          properties:
            prompt:
              type: string
              description: 要审核的文本。image_urls 包含一张图片时可省略；也可与图片一起提供。
              example: A peaceful mountain landscape.
            image_urls:
              type: array
              maxItems: 1
              description: 最多一个要审核的 HTTPS 图片 URL。prompt 包含非空白文本时可省略；prompt 可与图片一起提供。
              items:
                type: string
                format: uri
                pattern: ^https://
                description: 要审核图片的 HTTPS URL。
              example:
                - https://example.com/image.jpg
          not:
            properties:
              prompt:
                not:
                  pattern: \S
              image_urls:
                maxItems: 0
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              description: 将此任务标识用于 GET /api/generate/status/{task_id}。
              example: MODERATION_TASK_ID
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              description: 初始的排队状态。提交后审核异步执行。
            created_time:
              type: string
              format: date-time
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.