# 易盾内容安全 API 调用文档

## 📋 目录

- [概述](#概述)
- [配置说明](#配置说明)
- [API接口列表](#api接口列表)
- [文本检测](#1-文本检测)
- [图片检测](#2-图片检测)
- [视频检测](#3-视频检测)
- [错误码说明](#错误码说明)

---

## 概述

本项目集成了网易易盾内容安全SDK，提供文本、图片、视频的内容安全检测服务。

### 产品凭证

| 检测类型 | SecretID | SecretKey | BusinessID |
|---------|----------|-----------|------------|
| **音视频检测** | f58a38341ca6227014df7c3bf0e6f16f | 526aa631ba5d518aedeb70b5a3b67371 | 需从易盾控制台获取 |
| **图片检测** | 9a82f90bfec61eb40d1c95605b894817 | f73a78954417a3713c36ec2d14eb2b5f | 需从易盾控制台获取 |
| **文本检测** | 待配置 | 待配置 | 待配置 |

### 服务地址

```
http://localhost:3002
```

---

## 配置说明

配置文件位置：`config.yml`

```yaml
yidun:
  # 音视频检测配置
  video:
    business_id: "YOUR_VIDEO_BUSINESS_ID"
    secret_id: "f58a38341ca6227014df7c3bf0e6f16f"
    secret_key: "526aa631ba5d518aedeb70b5a3b67371"
  
  # 图片检测配置
  image:
    business_id: "YOUR_IMAGE_BUSINESS_ID"
    secret_id: "9a82f90bfec61eb40d1c95605b894817"
    secret_key: "f73a78954417a3713c36ec2d14eb2b5f"
  
  # 文本检测配置
  text:
    business_id: "YOUR_TEXT_BUSINESS_ID"
    secret_id: "YOUR_TEXT_SECRET_ID"
    secret_key: "YOUR_TEXT_SECRET_KEY"
```

---

## API接口列表

| 接口名称 | 请求方法 | 路径 | 说明 |
|---------|---------|------|------|
| 文本检测提交 | POST | `/yidun/detect-text` | 提交文本进行异步检测 |
| 图片检测提交 | POST | `/yidun/detect-image` | 提交图片进行异步检测 |
| 视频检测提交 | POST | `/yidun/detect-video` | 提交视频进行检测 |
| 图片结果查询 | POST | `/yidun/GetImageResult` | 查询图片检测结果（轮询模式） |
| 图片检测回调 | POST | `/yidun/receive-image-callback` | 接收图片检测结果推送（推送模式） |
| 视频结果查询 | POST | `/yidun/GetVideoResult` | 查询视频检测结果（轮询模式） |
| 视频检测回调 | POST | `/yidun/receive-video-callback` | 接收视频检测结果推送（推送模式） |

**注意**：检测结果是异步的，提交接口只返回 `task_id`，需要通过回调或轮询获取结果。

---

## 1. 文本检测

### 提交文本检测任务

**接口地址**: `POST /yidun/detect-text`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| data_id | string | 是 | 数据唯一标识 |
| content | string | 是 | 待检测的文本内容 |
| ip | string | 否 | 用户IP地址 |
| token | string | 否 | 用户token（反作弊） |

**请求示例**:

```bash
curl -X POST http://localhost:3002/yidun/detect-text \
  -H "Content-Type: application/json" \
  -d '{
    "data_id": "text-001",
    "content": "这是一段需要检测的文本内容",
    "ip": "192.168.1.100"
  }'
```

**响应示例**:

```json
{
  "code": 0,
  "message": "",
  "data": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
```

**响应说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| data | string | 任务ID (task_id)，用于后续查询检测结果 |

---

## 2. 图片检测

### 2.1 提交图片检测任务

**接口地址**: `POST /yidun/detect-image`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| data_id | string | 是 | 数据唯一标识 |
| image_url | string | 是 | 图片URL地址 |
| callback_url | string | 否 | 回调地址 |

**请求示例**:

```bash
curl -X POST http://localhost:3002/yidun/detect-image \
  -H "Content-Type: application/json" \
  -d '{
    "data_id": "img-001",
    "image_url": "https://example.com/image.jpg"
  }'
```

**响应示例**:

```json
{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
    "name": "img-001",
    "dataId": "img-001",
    "dealingCount": 0
  }
}
```

**响应说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| taskId | string | 任务ID，用于后续查询检测结果 |
| name | string | 图片唯一标识 |
| dataId | string | 客户图片唯一标识 |
| dealingCount | int64 | 缓冲池排队待处理数据量 |

### 2.2 查询图片检测结果（轮询模式）

**接口地址**: `POST /yidun/GetImageResult`

**SDK调用信息**:
- SDK方法: `ImageClient.ImageCallback(request)`
- 请求地址: `http://as.dun.163.com/v5/image/callback/results`
- 请求参数: `yidunRequestId` (taskId)

**请求示例**:

```bash
curl -X POST "http://localhost:3002/yidun/GetImageResult" \
  -H "Content-Type: application/json" \
  -d '{"taskId": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7"}'
```

**响应示例**:

```json
{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
    "status": 2,
    "suggestion": 0,
    "label": 100,
    "resultType": 2,
    "dataId": "img-001",
    "name": "img-001",
    "censorTime": 1629426386079,
    "url": "https://example.com/image.jpg",
    "antispam": {
      "taskId": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
      "name": "img-001",
      "dataId": "img-001",
      "status": 2,
      "suggestion": 0,
      "label": 100,
      "resultType": 2,
      "censorTime": 1629426386079,
      "censorSource": 0,
      "censorRound": 1,
      "labels": [
        {
          "label": 400,
          "level": 2,
          "rate": 1.0
        }
      ],
      "censorLabels": [
        {
          "code": "审核标签编码",
          "customCode": "自定义标签编码",
          "name": "审核标签名称",
          "desc": "风景"
        }
      ],
      "remark": "人审备注信息"
    },
    "ocr": { ... },
    "face": { ... },
    "quality": { ... },
    "logo": { ... },
    "discern": { ... },
    "ad": { ... },
    "userRisk": { ... },
    "anticheat": { ... },
    "riskControl": { ... },
    "aigc": { ... },
    "llmCheckInfo": [ ... ]
  }
}
```

**antispam 字段完整说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| taskId | string | 任务ID |
| name | string | 图片名称 |
| dataId | string | 客户数据ID |
| status | int | 检测状态：0=未开始，1=检测中，2=检测成功，3=检测失败 |
| suggestion | int | 处置建议：0=通过，1=嫌疑，2=不通过 |
| label | int | 一级分类 |
| secondLabel | string | 二级分类 |
| thirdLabel | string | 三级分类 |
| riskDescription | string | 风险描述 |
| resultType | int | 结果类型：1=机器结果，2=人审结果 |
| censorTime | int64 | 审核完成时间(毫秒时间戳) |
| censorSource | int | 审核来源 |
| censorRound | int | 审核轮数 |
| censorLabels | array | 审核标签数组 |
| remark | string | 审核备注 |
| overAllMarkDesc | string | 整体审核备注 |
| detailMarks | array | 细节标注 |
| labels | array | 分类标签详情 |
| url | string | 图片URL |
| imgMd5 | string | 图片MD5 |
| frameSize | int | 分帧数 |
| customLabels | array | 客户自定义标签 |
| censorExtension | object | 人审拓展字段 |
| strategyVersions | array | 策略版本 |
| hitType | int | 命中策略类型 |
| strategyType | int | 策略类型：1=公有策略，2=私有策略 |
| hitResult | string | 命中结果 |
| hitSource | int | 特征添加来源 |
| hidden | bool | 是否有隐藏文件 |
| hiddenFormat | string | 隐藏文件格式 |
| publicOpinionInfo | string | 舆情信息 |

**labels 数组结构**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| label | int | 标签类型 |
| level | int | 判断结果：0=正常，1=不确定，2=确定 |
| rate | float | 置信度 |
| subLabels | array | 二级分类详情 |
| explain | string | LLM解释说明 |
| isLlmCheck | bool | 是否LLM检测命中 |

**censorLabels 数组结构**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | string | 审核标签编码 |
| customCode | string | 自定义标签编码 |
| name | string | 审核标签名称 |
| desc | string | 审核标签描述 |
| parentLabelId | string | 父标签ID |
| depth | int | 标签深度 |

### 2.3 接收图片检测回调（推送模式）

**接口地址**: `POST /yidun/receive-image-callback`

**易盾回调配置**:
- HTTP URL: 回调地址 `callbackUrl`
- HTTP Method: POST
- Content-Type: application/x-www-form-urlencoded

**请求参数** (form-data):

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| secretId | string | 是 | 产品密钥ID |
| businessId | string | 是 | 业务ID |
| signature | string | 是 | 请求签名 |
| callbackData | string | 是 | 回调数据(JSON字符串) |

**请求体示例**:

```
callbackData={"antispam":{...}}&signature=xxx&secretId=xxx&businessId=xxx
```

**回调数据格式**:

```json
{
  "antispam": {
    "taskId": "a2e53718f9c348d09206e4671304ca7c",
    "suggestion": 2,
    "remark": "人审备注信息，填写才会返回",
    "dataId": "dataId",
    "name": "name",
    "labels": [
      {
        "label": 400,
        "level": 2,
        "rate": 1.0
      },
      {
        "label": 500,
        "level": 0,
        "rate": 1.0
      }
    ],
    "censorLabels": [
      {
        "code": "审核标签编码",
        "customCode": "自定义标签编码",
        "name": "审核标签名称",
        "desc": "风景"
      }
    ],
    "resultType": 2,
    "censorTime": 1622036595467,
    "censorSource": 0,
    "censorRound": 1
  }
}
```

**Suggestion值说明**:

| 值 | 含义 |
|----|------|
| 0 | 通过 |
| 1 | 嫌疑，需人工审核 |
| 2 | 不通过 |

**Status值说明**:

| 值 | 含义 |
|----|------|
| 0 | 未开始 |
| 1 | 检测中 |
| 2 | 检测成功 |
| 3 | 检测失败 |

---

## 3. 视频检测

### 提交视频检测任务

**接口地址**: `POST /yidun/detect-video`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| data_id | string | 是 | 数据唯一标识 |
| video_url | string | 是 | 视频URL地址 |
| callback_url | string | 否 | 回调地址 |

**请求示例**:

```bash
curl -X POST http://localhost:3002/yidun/detect-video \
  -H "Content-Type: application/json" \
  -d '{
    "data_id": "video-001",
    "video_url": "https://example.com/video.mp4"
  }'
```

**响应示例**:

```json
{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
    "dataId": "video-001",
    "dealingCount": 0
  }
}
```

**响应说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| taskId | string | 任务ID，用于后续查询检测结果 |
| dataId | string | 调用检测时传递的数据ID |
| dealingCount | int64 | 缓冲池排队待处理数据量 |

**注意**: 视频检测是异步的，检测时间取决于视频长度（几分钟到几十分钟）。建议配置回调地址接收结果。

### 3.2 查询视频检测结果（轮询模式）

**接口地址**: `POST /yidun/GetVideoResult`

**SDK调用信息**:
- SDK方法: `VideoClient.Callback(request)`
- 请求地址: `http://as.dun.163.com/v2/videosolution/callback/results`
- 请求参数: `yidunRequestId` (taskId)

**请求示例**:

```bash
curl -X POST "http://localhost:3002/yidun/GetVideoResult" \
  -H "Content-Type: application/json" \
  -d '{"taskId": "c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8"}'
```

**响应示例**:

```json
{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "18xrunm6fr35t49nnv506ukg02009q66",
    "status": 2,
    "suggestion": 2,
    "label": 100,
    "resultType": 1,
    "dataId": "video-001",
    "censorTime": 1633759853762,
    "duration": 71339,
    "antispam": {
      "taskId": "18xrunm6fr35t49nnv506ukg02009q66",
      "suggestion": 2,
      "status": 2,
      "resultType": 1,
      "censorSource": 2,
      "checkTime": 1633759861164,
      "censorTime": 1633759853762,
      "duration": 71339,
      "censorLabels": [
        {
          "code": "101",
          "desc": "自定义标签",
          "customCode": "68684"
        }
      ],
      "evidences": {
        "images": [...],
        "text": {...},
        "audio": {...},
        "video": {...}
      }
    },
    "language": { ... },
    "voice": { ... },
    "asr": { ... },
    "ocr": { ... },
    "discern": { ... },
    "logo": { ... },
    "face": { ... },
    "aigc": { ... },
    "quality": { ... }
  }
}
```

**antispam 字段完整说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| taskId | string | 任务ID |
| dataId | string | 客户数据ID |
| callback | string | 回调参数 |
| suggestion | int | 处置建议：0=通过，1=嫌疑，2=不通过 |
| status | int | 检测状态：0=未开始，1=检测中，2=检测成功，3=检测失败 |
| resultType | int | 结果类型：1=机器结果，2=人审结果 |
| censorRound | int | 人审轮次 |
| censor | string | 人审操作人 |
| censorSource | int | 审核来源：0=易盾人审，1=客户人审，2=易盾机审 |
| checkTime | int64 | 机器检测结束时间 |
| censorTime | int64 | 人工审核完成时间 |
| duration | int64 | 音视频时长(毫秒) |
| durationMs | int64 | 音频时长(毫秒) |
| label | int | 一级垃圾类型 |
| secondLabel | string | 二级垃圾类型 |
| thirdLabel | string | 三级垃圾类型 |
| riskDescription | string | 风险描述 |
| picCount | int64 | 截图数量 |
| censorLabels | array | 审核标签数组 |
| censorExtension | object | 质检扩展结果 |
| evidences | object | 机器检测证据信息 |
| solutionExtra | object | 额外信息 |
| reviewEvidences | object | 人审证据信息 |

**evidences 对象说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| text | object | 文本证据（标题、简介等） |
| images | array | 图片证据（封面、截图中的图片） |
| audio | object | 音频证据（人声内容） |
| video | object | 视频证据（视频画面） |

**CensorSource值说明**:

| 值 | 含义 |
|----|------|
| 0 | 易盾人审 |
| 1 | 客户人审 |
| 2 | 易盾机审 |

### 3.3 接收视频检测回调（推送模式）

**接口地址**: `POST /yidun/receive-video-callback`

**易盾回调配置**:
- HTTP URL: 回调地址 `callbackUrl`
- HTTP Method: POST
- Content-Type: application/x-www-form-urlencoded

**请求参数** (form-data):

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| secretId | string | 是 | 产品密钥ID |
| signature | string | 是 | 请求签名 |
| callbackData | string | 是 | 回调数据(JSON字符串) |

**请求体示例**:

```
callbackData={"antispam":{...}}&signature=xxx&secretId=xxx
```

**回调数据格式**:

```json
{
  "antispam": {
    "taskId": "18xrunm6fr35t49nnv506ukg02009q66",
    "suggestion": 2,
    "status": 2,
    "resultType": 1,
    "censorSource": 2,
    "checkTime": 1633759861164,
    "censorTime": 1633759853762,
    "duration": 71339,
    "censorLabels": [
      {
        "code": "101",
        "desc": "自定义标签",
        "customCode": "68684"
      }
    ],
    "evidences": {
      "images": [
        {
          "censorType": 0,
          "labels": [
            {
              "label": 100,
              "level": 2,
              "rate": 0.9999,
              "subLabels": [
                {
                  "details": {
                    "hitInfos": [
                      {
                        "group": "色情部位分组",
                        "value": "女胸"
                      }
                    ]
                  },
                  "rate": 1,
                  "subLabel": 10002
                }
              ]
            }
          ],
          "name": "gpqis0e92czvfliemjpa3neg02009q6a",
          "resultType": 1,
          "status": 2,
          "suggestion": 2,
          "taskId": "0b2dd0e561a8457fbfcf7d79378eec37"
        }
      ],
      "text": {
        "taskId": "44i3effo1j5w5for9l8xtdjg02009q6a",
        "suggestion": 2,
        "resultType": 1,
        "censorType": 0,
        "isRelatedHit": false,
        "labels": [
          {
            "label": 200,
            "level": 2,
            "subLabels": [
              {
                "subLabel": "200009",
                "details": {
                  "hitInfos": [
                    {
                      "value": "加我",
                      "positions": [
                        {
                          "fieldName": "content",
                          "startPos": 5,
                          "endPos": 8
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        ]
      },
      "audio": {
        "taskId": "18xrunm6fr35t49nnv506ukg02009q66",
        "dataId": "",
        "status": 2,
        "suggestion": 2,
        "label": 100,
        "resultType": 1,
        "callback": "",
        "censorSource": 2,
        "censorTime": 1633759861065,
        "segments": [
          {
            "startTime": 0,
            "endTime": 6,
            "content": "第一次用这个软件上了半天，全是长得漂亮呢？",
            "type": 0,
            "labels": [
              {
                "label": 100,
                "level": 2,
                "subLabels": [
                  {
                    "subLabel": "100001",
                    "details": {
                      "hitInfos": [
                        {
                          "value": "120",
                          "startTime": 1684201,
                          "endTime": 1684201
                        }
                      ],
                      "keywords": [
                        {
                          "word": "自定义敏感词"
                        }
                      ],
                      "libInfos": [
                        {
                          "listType": 1,
                          "entity": "127.0.0.1"
                        }
                      ]
                    }
                  }
                ]
              }
            ]
          }
        ],
        "duration": 71
      },
      "video": {
        "taskId": "18xrunm6fr35t49nnv506ukg02009q66",
        "dataId": "",
        "status": 2,
        "suggestion": 2,
        "resultType": 1,
        "censorSource": 2,
        "censorTime": 1633759858920,
        "pictures": [
          {
            "type": 1,
            "url": "https://xxx.nosdn.127.net/xxx.jpg",
            "startTime": 5000,
            "endTime": 5000,
            "labels": [
              {
                "label": 100,
                "level": 2,
                "rate": 0.95157,
                "subLabels": [
                  {
                    "subLabel": 10007,
                    "rate": 0.926,
                    "details": {
                      "hitInfos": [
                        {
                          "value": "卡通色情",
                          "group": "色情部位分组"
                        }
                      ]
                    }
                  }
                ]
              }
            ],
            "censorSource": 2,
            "frontPics": [
              {
                "url": "https://xxx.nosdn.127.net/xxx_0_0.jpg"
              }
            ],
            "backPics": [
              {
                "url": "https://xxx.nosdn.127.net/xxx_2_10000.jpg"
              }
            ]
          }
        ]
      }
    }
  }
}
```

**Suggestion值说明**:

| 值 | 含义 |
|----|------|
| 0 | 通过 |
| 1 | 嫌疑，需人工审核 |
| 2 | 不通过 |

**Status值说明**:

| 值 | 含义 |
|----|------|
| 0 | 未开始 |
| 1 | 检测中 |
| 2 | 检测成功 |
| 3 | 检测失败 |

**images/images.labels 结构说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| label | int | 标签类型 |
| level | int | 级别：0=正常，1=嫌疑，2=确定违规 |
| rate | float | 置信度 |
| subLabels | array | 二级分类详情 |
| subLabels.details.hitInfos | array | 命中信息 |
| subLabels.details.hitInfos.group | string | 分组名称 |
| subLabels.details.hitInfos.value | string | 命中值 |

**audio.segments 结构说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| startTime | int | 开始时间(秒) |
| endTime | int | 结束时间(秒) |
| content | string | 语音识别原文 |
| type | int | 片段类型：0=语音识别，1=声纹检测 |
| labels | array | 分类标签 |
| labels.details.keywords | array | 自定义敏感词 |
| labels.details.libInfos | array | 自定义名单 |
| labels.details.hitInfos | array | 命中内容 |

**video.pictures 结构说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| type | int | 截图类型 |
| url | string | 截图URL |
| startTime | int64 | 开始时间(毫秒) |
| endTime | int64 | 结束时间(毫秒) |
| labels | array | 分类标签 |
| frontPics | array | 关联前帧图片 |
| backPics | array | 关联后帧图片 |

---

## 错误码说明

| code | 说明 |
|------|------|
| 0 | 成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

**易盾API错误码**:

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 401 | 认证失败（SecretID/SecretKey错误） |
| 403 | 权限不足 |
| 429 | 请求频率超限 |

---

## Go代码调用示例

```go
// 文本检测
func detectText() (string, error) {
    req := map[string]interface{}{
        "data_id": "text-001",
        "content": "这是一段测试文本",
    }
    jsonData, _ := json.Marshal(req)
    resp, err := http.Post("http://localhost:3002/yidun/detect-text", "application/json", bytes.NewBuffer(jsonData))
    // ...
}

// 图片检测
func detectImage() (string, error) {
    req := map[string]interface{}{
        "data_id":  "img-001",
        "image_url": "https://example.com/image.jpg",
    }
    jsonData, _ := json.Marshal(req)
    resp, err := http.Post("http://localhost:3002/yidun/detect-image", "application/json", bytes.NewBuffer(jsonData))
    // ...
}

// 视频检测
func detectVideo() (string, error) {
    req := map[string]interface{}{
        "data_id":  "video-001",
        "video_url": "https://example.com/video.mp4",
    }
    jsonData, _ := json.Marshal(req)
    resp, err := http.Post("http://localhost:3002/yidun/detect-video", "application/json", bytes.NewBuffer(jsonData))
    // ...
}
```

---

**最后更新**: 2026-05-07