内容审核接口 V2
提交文本、图片或视频做内容审核。文本和图片同步返回结论,视频异步受理后查询或回调。
提交文本、图片或视频,返回多模态审核结论。文本和图片同步返回;请求里带视频时异步受理,再用任务号查询结果。传了回调地址时,完成后会再 POST 同一份结果。
| 方法与路径 | 说明 |
|---|---|
POST /api/moderation | 提交审核。文本、图片同步返回;带视频异步受理 |
GET /api/tasks/{request_id} | 查询异步任务 |
| 环境 | 根地址 |
|---|---|
| 测试 | https://test-star-api.aiaibase.com |
| 正式 | https://star-api.aiaibase.com |
路径接在根地址后面。例如测试环境提交审核:
text
POST https://test-star-api.aiaibase.com/api/moderation请求体为 JSON,Content-Type: application/json。认证只使用请求头:
text
Authorization: Bearer {API Key}{API Key} 只能放在服务端。文档站的在线 demo 如果要在浏览器里调用,必须走服务端代理,不要把 Key 写进前端包体。
text、images、video 至少传一个,可以同时传。文本和图片走图文联合审核,视频单独审核。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
channel | 是 | string | 渠道标识,如 web、app |
checks | 是 | object | 检查项,不能为空 |
text | 三选一 | string | 待审核文本 |
images | 三选一 | string[] | 图片 URL 列表,必须公网可访问 |
video | 三选一 | string | 视频 URL,必须公网可访问。走异步 |
notice_url | 否 | string | 异步回调地址。传了必须同时传 client_request_id |
client_request_id | 条件 | string | 调用方请求号。异步时必填。同一 Key 下相同值不重复计费 |
checks
至少开启一个有效检查项:minor、qrcode、ad、blood_violence、contact、external_link 任一为 true。只传 porn 会返回业务码 4102。
| 字段 | 类型 | 说明 |
|---|---|---|
minor | bool | 未成年人 |
age_limit | int | 年龄阈值,10–25。仅 minor 为 true 时生效;超出范围会被夹取 |
qrcode | bool | 二维码 |
ad | bool | 广告 / 水印 |
blood_violence | bool | 血腥暴力 |
contact | bool | 联系方式 |
external_link | bool | 外链检查总开关 |
link_policy | object | 外链策略。external_link 为 true 时必填 |
porn | bool | 已废弃。兼容接受但不生效,不要在新代码里使用 |
link_policy
| 字段 | 说明 |
|---|---|
mode | strict、standard、loose。默认 standard |
action | reject、review、pass_with_tag。默认 reject |
whitelist | 域名字符串数组,命中不判违规 |
blacklist | 域名字符串数组 |
文本和图片在同一次请求里返回结论。
json
{
"success": true,
"data": {
"approved": true,
"message": "审核没问题(执行审核项:minor、ad;age_limit=18)",
"reasons": ["审核通过"],
"hits": {},
"labels": [],
"model_version": "audit-v2.0",
"upstream_task_id": "493318ef74b874d1e0f1294482477bf9"
},
"meta": {
"request_id": "317013cd-0000-0000-0000-000000000000",
"timestamp": "2026-11-03T11:00:00+08:00"
}
}| 字段 | 说明 |
|---|---|
approved | true 通过,false 拒绝 |
message | 结论摘要。文案可能调整,不要用于程序判断 |
reasons | 原因数组 |
hits | 命中项,如 {"contact": true}。无命中为 {} |
labels | 命中标签数组,如 ["contact"]、["external_link"] |
model_version | 判定版本,如 audit-v2.0 |
upstream_task_id | 上游任务号,排查用 |
approved 为 false 是审核结论,不是错误,不要当成系统错误处理。
带 video 提交后立即返回受理结果。此时还没有审核结论。
json
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "web-video-001"
},
"meta": {
"request_id": "317013cd-0000-0000-0000-000000000000",
"timestamp": "2026-11-03T11:00:00+08:00"
}
}用受理响应里的 meta.request_id 查询:
text
GET /api/tasks/{request_id}
Authorization: Bearer {API Key}- 未完成:
data.status为accepted或running。 - 完成:
data与同步响应字段一致,包含approved、message、reasons、hits、labels、model_version、upstream_task_id。 - 建议轮询间隔 2–5 秒。任务记录保留 24 小时。
- 传了
notice_url时,完成后会 POST 同样的data到该地址。处理要幂等。
前端处理:
- 带
video提交,拿到meta.request_id。 - 展示「审核中」,按 2–5 秒轮询
GET /api/tasks/{request_id}。 - 拿到
approved后停止轮询,按通过或拒绝渲染。 - 超过 24 小时,或返回业务码
3601时,提示失败并让用户重新提交。
失败时 HTTP 可能是 200,但 success 为 false。业务码在 error.code。
| code | 含义 | 处理 |
|---|---|---|
1001 | 至少提供文本、图片或视频中的一项 | 表单校验 |
1000 | 任务不存在 | 停止轮询,提示重新提交 |
4102 | 参数不合法。未知检查项、无有效检查项,或外链策略缺失 | 按 error.details[].field 定位 |
5003 | 认证信息无效 | 检查 Key。Key 在服务端 |
3600 | 上游处理失败 | 可提示重试 |
3601 | 上游处理超时,或任务超过 24 小时 | 提示重新提交 |
1004 | 请求实体过大 | 减少素材数量 |
文本通过:
bash
curl -X POST 'https://test-star-api.aiaibase.com/api/moderation' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"channel": "web",
"text": "今天天气不错",
"checks": {
"ad": true,
"minor": true,
"age_limit": 18
}
}'外链拒绝:
bash
curl -X POST 'https://test-star-api.aiaibase.com/api/moderation' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"channel": "web",
"text": "详情看 https://evil-example.com/promo",
"checks": {
"external_link": true,
"link_policy": {
"mode": "standard",
"action": "reject",
"whitelist": ["inaiai.com", "*.inaiai.com"]
}
}
}'视频异步:
bash
curl -X POST 'https://test-star-api.aiaibase.com/api/moderation' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"channel": "web",
"video": "https://example.com/a.mp4",
"checks": {
"minor": true,
"age_limit": 18,
"blood_violence": true
},
"client_request_id": "web-video-001"
}'
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
-H 'Authorization: Bearer {API Key}'- 测试环境:
https://test-star-api.aiaibase.com - 测试 Key:向后端索取,不要写进仓库或前端。
- 视频测试素材:
https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4 - 已验证样本:文本通过、文本命中联系方式、图片、视频异步、外链拒绝与白名单、只传
porn返回4102、无素材返回1001、无效 Key 返回5003。