> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/chinese-simplified/api-wen-dang-tu-pian/biao-zhun-tao-can/tu-pian-shen-he-api.md).

# 图片审核 API

\[ 基础 URL: `api.ggwp.com`]

`POST` /image/v1/moderate

## **说明**

Image Moderation 端点接收一张输入图像，以及一组可配置选项，并返回受支持的类别列表及其对应标记和总体严重程度。 

### **处理模式**

为了满足不同的质量和性能需求，Image API 提供以下两种处理模式。两种模式使用相同的类别，但类别严重程度的可配置设置不同，并且在延迟和分析深度上有所差异。

你可以通过 `x-api-processing-mode` 请求头使用 

 `x-api-processing-mode:quality/performance`

**质量模式（默认）**

运行 GGWP 的完整模型，以实现最高检测准确率，并在各类别中提供更细致的严重程度覆盖。支持以下文件格式：JPG、JPEG、PNG、GIF、WEBP

* **延迟：** 约 1000–1200 毫秒，中位数。
* **类别覆盖：** 使用不同的严重程度配置设置，支持标题部分中提到的每个类别更细致的严重程度级别。
* **适用场景：** 安全政策更严格或面向更年轻受众的社区，在这些场景中，尽量减少有害图像漏过审核的风险非常重要。也适用于对延迟不那么敏感的离线检查。

**性能模式**

使用经过简化的模型，针对低延迟进行了优化，同时仍覆盖 Image API 支持的核心类别。支持以下文件格式：JPG、JPEG、PNG。

* **延迟：** 约 150–200 毫秒，中位数。
* **类别覆盖：** 支持请求头部分中提到的类别标准覆盖集。
* **适用场景：** 适用于需要快速响应的实时图像审核和高吞吐工作流。

## **请求头**

***注意：** 如果你的配置设置在入驻期间已单独与 GGWP 共享，则本节不需要。*

***质量模式：***

以下请求头选项允许你按请求自定义审核类别。默认情况下，所有类别都设置为 **high**:

* `explicit_nudity`: off/low/medium/high
* `non_explicit_nudity`: off/low/medium/high
* `hate_imagery`: off/low/medium/high
* `violence`: off/low/medium/high
* `gore`: off/low/medium/high
* `weapons`: off/low/medium/high
* `alcohol_drugs`: off/low/medium/high
* `gambling`: off/low/medium/high
* `profanity`: off/low/medium/high

你可以通过 `x-api-config` 请求头以 **经过 base64 编码的 JSON 对象**.

#### 示例

`config.json`

```json
{
  "non_explicit_nudity": "high",
  "gambling": "off",
  "violence": "low"
}
```

转换为 base64：

{% code overflow="wrap" %}

```bash
$ base64 config.json
ewogICJub25fZXhwbGljaXRfbnVkaXR5IjogImhpZ2giLAogICJnYW1ibGluZyI6ICJvZmYiLAogICJ2aW9sZW5jZSI6ICJsb3ciCn0=
```

{% endcode %}

***性能模式：*** 

以下请求头选项允许你按请求自定义审核类别。默认情况下，所有类别都设为 **on**:

* `explicit_nudity`: on/off
* `non_explicit_nudity`: on/off
* `hate_imagery`: on/off
* `violence`: on/off
* `gore`: on/off
* `weapons`: on/off
* `alcohol_drugs`: on/off
* `gambling`: on/off
* `profanity`: on/off

你可以通过 `x-api-config` 请求头以 **经过 base64 编码的 JSON 对象**.

#### 示例

`config.json`

```json
{
  "non_explicit_nudity": "off",
  "gambling": "off",
  "violence": "on"
}
```

转换为 base64：

{% code overflow="wrap" %}

```bash
$ base64 config.json
ewogICJub25fZXhwbGljaXRfbnVkaXR5IjogIm9mZiIsCiAgImdhbWJsaW5nIjogIm9mZiIsCiAgInZpb2xlbmNlIjogIm9uIgp9
```

{% endcode %}

发起请求：

{% code overflow="wrap" %}

```bash
curl --request POST 'https://api.ggwp.com/image/v1/moderate' \\
  --header 'x-api-key: <API_KEY>' \\
  --header 'x-api-config: <BASE64_CONFIG>' \\
  -F "file=@/path/to/example.jpeg" \\
  -F "file_name=avatar123.jpeg" \\
  -F "user_id=user989"
```

{% endcode %}

## **参数**

`主体`：以 `multipart/form-data` （UTF-8 编码）。

* **file**：二进制图像文件。图像必须符合以下要求：
  * **文件格式**：JPG、JPEG、PNG、（仅质量模式支持 GIF/WEBP）。
  * **大小限制：** 最高 5MB。
* **file\_name**：图像文件的描述符。&#x20;
  * 示例： `avatar123.jpeg`
* **user\_id：** 图像应归属到的用户的唯一标识。检测到的事件将影响用户的信誉分数和个人资料。
* （可选） **username**：用户选择的友好显示名称。会在 GGWP 仪表板中与 `user_id`一起显示。默认值为 `user_id` 如果未提供。
* （可选） **session\_id**：图像被分享时对应对话、比赛或频道的唯一会话标识符。
* （可选） **timestamp**：图像被分享时的 UTC 时间，格式为 `YYYY-MM-DD HH:MM:SS.SSS` 或 `YYYY-MM-DD HH:MM:SS` 。如果省略，服务器将分配当前 UTC 时间戳。
* （可选） **image\_url**：与图像关联的 URL（必须是 `http` 或 `https`）。如果有效，它将显示在仪表板中。
* （可选） **metadata**：自定义键/值对的 JSON 字符串。必须小于 5KB。只有允许的键和值类型才有效。请与你的 GGWP 代表合作，确定哪些键适用于你的平台。

## 示例调用

**Bash**

```bash
curl --request POST 'https://api.ggwp.com/image/v1/moderate' \\
  --header 'x-api-key: <API_KEY>' \\
  --header 'x-api-config: <BASE64_CONFIG>' \\
  --header 'x-api-processing-mode: quality' \\
  -F "file=@/path/to/example.jpeg" \\
  -F "file_name=avatar123.jpeg" \\
  -F "user_id=user989" \\
  -F "username=nlxdz" \\
  -F "session_id=match_7765" \\
  -F "timestamp=2025-10-10 16:49:02" \\
  -F "image_url=https://cdn.example.com/uploads/avatar123.jpeg"
```

**Python**

```python
import requests

# API 端点
url = "https://api.ggwp.com/image/v1/moderate"

# 身份验证和配置（用于类别的 base64 编码 JSON 字符串）
headers = {
    "x-api-key": "GGWP_API_KEY",
    "x-api-config": "<BASE64_CONFIG>",
    "x-api-processing-mode": "quality"
}

# 元数据和其他参数
data = {
    "file_name": "avatar123.jpeg",
    "user_id": "player10",
    "username": "purpleCarrot",
    "session_id": "match_unranked_20230620_12345",
    "timestamp": "2025-10-10 16:49:02",
    "image_url": "https://cdn.example.com/uploads/avatar123.jpeg"
}

# 图像文件
files = {
    "file": open("/location/to/avatar123.jpeg", "rb")
}

# 发送 POST 请求
response = requests.post(url, headers=headers, data=data, files=files)

# 检查响应
print(response.status_code)
print(response.json())
```

## **输出**

* 200 响应 - 操作成功

```json
{
  "image_id": "20251010164902.482311-946bb8a9-0766-4c31-995a-d910da8531e5",
  "file_name": "avatar123.jpeg",
  "flag": true,
  "severity": "medium",
  "categories": {
    "explicit_nudity": true,
    "non_explicit_nudity": false,
    "hate_imagery": false,
    "violence": false,
    "gore": false,
    "weapons": false,
    "alcohol_drugs": false,
    "gambling": false,
    "profanity": true
  },
  "timestamp": "2025-10-10 16:49:02"
}


```

* 400
  * 无效或格式错误的请求。可能原因：
    * 缺少必需字段（例如， `file`, `file_name`, `user_id`)
    * 文件格式不受支持（仅允许 JPEG/JPG/PNG）
    * 文件大小超过 5MB 限制
    * 时间戳格式无效
    * 元数据超过 5KB 或包含不允许的键
* 403
  * API 密钥无效或缺失
* 500
  * 服务器端错误响应