删除人脸与声纹

接口介绍

接口路径:POST /api/V1/open-portal/app/linksoul/agent-faces/deletions

按条件批量硬删除人脸,并级联清理声纹、设备绑定关系、对象存储图片与敏感记忆。

  • 除 tenant_id 外至少提供一个条件,多个条件之间为 AND。
  • registered_start_timestamp 与 registered_end_timestamp 必须成对提供,且结束时间不能早于开始时间;earliest_face_count 必须大于 0。
  • registered_user_id / registered_user_name 匹配的是注册人(操作者),不是被注册人;开放接口注册的人脸通常没有注册人姓名,建议用 registered_face_uid、face_group_name 或时间范围。
  • 没有匹配记录时返回“未找到匹配的人脸记录”。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。

请求参数

字段类型必填说明
tenant_idinteger (int64)是目标租户 ID,必须与操作者租户匹配
registered_user_idinteger (int64)见说明按注册人(操作者)用户 ID 精确匹配;除 tenant_id 外至少提供一个条件
registered_user_namestring见说明按注册人(操作者)姓名精确匹配;开放接口场景通常匹配不到
registered_face_uidstring见说明按人脸 UID 精确匹配
face_group_namestring见说明按人脸分组名称精确匹配
registered_start_timestampinteger (int64)见说明注册时间起点(毫秒),须与结束时间成对提供
registered_end_timestampinteger (int64)见说明注册时间终点(毫秒),不能早于起点
earliest_face_countinteger见说明删除注册时间最早的 N 条,必须大于 0

调用示例

签名方式同获取上传地址:请求头携带 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature。

下方命令可直接复制运行:本接口为硬删除且不可恢复,请先用测试分组或测试人脸的 registered_face_uid 跑一次确认影响范围,再按「请求参数」收紧 -d 条件。

bash
APP_ID="app_xxxxxxxx"; APP_KEY="ak_xxxxxxxx"; APP_SECRET="sk_xxxxxxxx"
# 示例为生产域名;UAT 联调请替换为 https://open.uat.agibot.com(UAT 需使用该环境单独申请的应用凭证,不能与生产混用)
BASE_URL="https://open.agibot.com"
API_PATH="/api/V1/open-portal/app/linksoul/agent-faces/deletions"

TS_MS=$(( $(date +%s) * 1000 ))
NONCE="$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')"
SIGNATURE=$(printf 'POST\n%s\n%s\n%s' "$API_PATH" "$TS_MS" "$NONCE" \
  | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.* //')

# 示例:按人脸分组 + 注册时间范围删除
curl -sS -X POST "$BASE_URL$API_PATH" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: $APP_ID" \
  -H "X-App-Key: $APP_KEY" \
  -H "X-Timestamp: $TS_MS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE" \
  -d '{
    "tenant_id": 12345,
    "face_group_name": "default",
    "registered_start_timestamp": 1767225600000,
    "registered_end_timestamp": 1769817599000
  }'

返回参数

字段类型说明
codeinteger状态码,成功为 0
messagestring错误提示;成功时为 success
data.deleted_face_countinteger本次删除的人脸记录数量

返回示例

json
{"code": 0, "message": "success", "data": {"deleted_face_count": 1}}

常见错误

  • 未提供除 tenant_id 以外的条件。
  • 时间范围不成对,或结束时间早于开始时间。
  • earliest_face_count 小于 1。
  • 没有匹配的人脸记录。
  • 操作者不是租户管理员。