绑定人脸到智能体
接口介绍
接口路径:POST /api/V1/open-portal/app/linksoul/agent-faces/bindings
将已注册的人脸追加到指定智能体的人脸列表(与平台内“添加至智能体”同链路),只写智能体层,不接收设备 SN。
- 同一人脸重复绑定不会重复追加,但会按本次入参刷新称呼、招呼语、记忆开关与分组;未传字段保持原值。
agent_code必须存在且属于当前租户;face_record_id需先通过注册接口创建。- 设备侧人脸由智能体与设备的绑定链路派生;事务提交后自动异步下发(约 10s 感知),调用方无需再触发部署。
- 操作者用户 ID 由平台网关注入
X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tenant_id | integer (int64) | 是 | 目标租户 ID,必须与操作者租户匹配 |
| agent_code | string | 是 | 智能体 Code |
| agent_timestamp | integer (int64) | 否 | 兼容保留,服务端当前不消费 |
| knowledge_list | array of string | 否 | 兼容保留,服务端当前不消费 |
| face_records | array | 是 | 本次绑定的人脸记录列表 |
| face_records.face_record_id | integer (int32) | 是(记录项内) | 人脸记录 ID |
| face_records.nick_name | string | 否 | 设备侧称呼 |
| face_records.greet_text | string | 否 | 打招呼文案 |
| face_records.memory | integer | 否 | 是否启用记忆:0 关闭,1 开启;非 0/1 报错 |
| face_records.face_group_name | string | 否 | 人脸分组名称 |
| face_records.faces | array | 否 | 嵌套子人脸,结构同父级;展平后各自使用自身设置 |
调用示例
签名方式同获取上传地址:请求头携带 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature。
下方命令可直接复制运行:替换凭证后先跑一次即可验证连通性(在线调试),再按「请求参数」修改 -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/bindings"
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,
"agent_code": "AI_AGENT_28159402",
"face_records": [{
"face_record_id": 990002,
"nick_name": "Alice",
"greet_text": "Hello",
"memory": 1,
"face_group_name": "default"
}]
}'
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| message | string | 错误提示;成功时为 success |
| data | null | 绑定成功时为空 |
返回示例
json
{"code": 0, "message": "success", "data": null}
常见错误
agent_code不存在或不属于当前租户。- 人脸添加至智能体失败(如超出智能体人脸数量上限)。
- 缺少
agent_code、face_records或face_record_id。 - 操作者不是租户管理员。