内容审核接口 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。

字段类型说明
minorbool未成年人
age_limitint年龄阈值,10–25。仅 minor 为 true 时生效;超出范围会被夹取
qrcodebool二维码
adbool广告 / 水印
blood_violencebool血腥暴力
contactbool联系方式
external_linkbool外链检查总开关
link_policyobject外链策略。external_link 为 true 时必填
pornbool已废弃。兼容接受但不生效,不要在新代码里使用
字段说明
modestrict、standard、loose。默认 standard
actionreject、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"
  }
}
字段说明
approvedtrue 通过,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 到该地址。处理要幂等。

前端处理:

  1. 带 video 提交,拿到 meta.request_id。
  2. 展示「审核中」,按 2–5 秒轮询 GET /api/tasks/{request_id}。
  3. 拿到 approved 后停止轮询,按通过或拒绝渲染。
  4. 超过 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。