图片黑名单管理

查询图片黑名单

GET /api/open/v1/image-blacklist

权限：open:image_blacklist:read

查询参数：

参数	类型	必填	说明
page	int	否	页码，默认 1
page_size	int	否	每页条数，默认 100，最大 10000
status	string	否	状态筛选：active / disabled
source	string	否	来源筛选

响应示例：

{
    "code": 200,
    "message": "success",
    "data": {
        "list": [
            {
                "id": 1,
                "md5": "d41d8cd98f00b204e9800998ecf8427e",
                "source": "manual",
                "status": "active",
                "hit_count": 5,
                "created_at": "2025-01-01T00:00:00"
            }
        ],
        "total": 12345
    }
}

注意：该接口仅返回 MD5 值及基础信息，不返回拒绝原因等内部管理字段。每页最大支持 10000 条，便于外部系统批量同步全量黑名单。

---

批量添加到黑名单

POST /api/open/v1/image-blacklist

权限：open:image_blacklist:write

请求体：

字段	类型	必填	说明
items	array	是	最多 1000 条
items[].md5	string	是	图片 MD5（32 位十六进制）
items[].source	string	否	来源标记，默认 external
items[].reject_reason	string	否	拒绝原因，默认 开放接口添加

请求示例：

{
    "items": [
        {
            "md5": "d41d8cd98f00b204e9800998ecf8427e",
            "source": "external",
            "reject_reason": "外部系统标记"
        },
        {
            "md5": "098f6bcd4621d373cade4e832627b4f6"
        }
    ]
}

响应示例：

{
    "code": 200,
    "message": "success",
    "data": {
        "added": 1,
        "skipped": 0,
        "restored": 1,
        "errors": []
    }
}

响应字段说明：

字段	说明
added	新增成功的条数
skipped	已存在且 active，被跳过的条数
restored	已存在但 disabled，被恢复为 active 的条数
errors	处理失败的条目，含 index、md5、reason

注意：单次最多添加 1000 条。已存在且处于 active 状态的记录会被自动跳过；已存在但处于 disabled 状态的记录会自动恢复为 active。

---

批量检查黑名单

POST /api/open/v1/image-blacklist/check

权限：open:image_blacklist:read

请求体：

字段	类型	必填	说明
md5_list	array	是	最多 500 个 MD5 值

请求示例：

{
    "md5_list": [
        "d41d8cd98f00b204e9800998ecf8427e",
        "098f6bcd4621d373cade4e832627b4f6"
    ]
}

响应示例：

{
    "code": 200,
    "message": "success",
    "data": {
        "blocked": ["d41d8cd98f00b204e9800998ecf8427e"],
        "allowed": ["098f6bcd4621d373cade4e832627b4f6"]
    }
}

响应字段说明：

字段	说明
blocked	命中黑名单的 MD5 列表
allowed	未命中黑名单的 MD5 列表
invalid	格式错误的 MD5 列表（仅当存在无效值时返回）

注意：仅检查 active 状态的记录。单次最多检查 500 个 MD5。适用于上传图片前快速校验是否已被拦截。

---

从黑名单移除

DELETE /api/open/v1/image-blacklist/{record_id}

权限：open:image_blacklist:write

路径参数：

参数	类型	说明
record_id	int	黑名单记录 ID（通过查询接口获取）

响应示例：

{
    "code": 200,
    "message": "success",
    "data": null
}

注意：该操作为永久删除，不可恢复。记录 ID 可通过 GET /image-blacklist 查询获取。