删除人脸与声纹
接口介绍
接口路径: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_id | integer (int64) | 是 | 目标租户 ID,必须与操作者租户匹配 |
| registered_user_id | integer (int64) | 见说明 | 按注册人(操作者)用户 ID 精确匹配;除 tenant_id 外至少提供一个条件 |
| registered_user_name | string | 见说明 | 按注册人(操作者)姓名精确匹配;开放接口场景通常匹配不到 |
| registered_face_uid | string | 见说明 | 按人脸 UID 精确匹配 |
| face_group_name | string | 见说明 | 按人脸分组名称精确匹配 |
| registered_start_timestamp | integer (int64) | 见说明 | 注册时间起点(毫秒),须与结束时间成对提供 |
| registered_end_timestamp | integer (int64) | 见说明 | 注册时间终点(毫秒),不能早于起点 |
| earliest_face_count | integer | 见说明 | 删除注册时间最早的 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
}'
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| message | string | 错误提示;成功时为 success |
| data.deleted_face_count | integer | 本次删除的人脸记录数量 |
返回示例
json
{"code": 0, "message": "success", "data": {"deleted_face_count": 1}}
常见错误
- 未提供除
tenant_id以外的条件。 - 时间范围不成对,或结束时间早于开始时间。
earliest_face_count小于 1。- 没有匹配的人脸记录。
- 操作者不是租户管理员。