绑定人脸到智能体

接口介绍

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

将已注册的人脸追加到指定智能体的人脸列表(与平台内“添加至智能体”同链路),只写智能体层,不接收设备 SN。

  • 同一人脸重复绑定不会重复追加,但会按本次入参刷新称呼、招呼语、记忆开关与分组;未传字段保持原值。
  • agent_code 必须存在且属于当前租户;face_record_id 需先通过注册接口创建。
  • 设备侧人脸由智能体与设备的绑定链路派生;事务提交后自动异步下发(约 10s 感知),调用方无需再触发部署。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。

请求参数

字段类型必填说明
tenant_idinteger (int64)是目标租户 ID,必须与操作者租户匹配
agent_codestring是智能体 Code
agent_timestampinteger (int64)否兼容保留,服务端当前不消费
knowledge_listarray of string否兼容保留,服务端当前不消费
face_recordsarray是本次绑定的人脸记录列表
face_records.face_record_idinteger (int32)是(记录项内)人脸记录 ID
face_records.nick_namestring否设备侧称呼
face_records.greet_textstring否打招呼文案
face_records.memoryinteger否是否启用记忆:0 关闭,1 开启;非 0/1 报错
face_records.face_group_namestring否人脸分组名称
face_records.facesarray否嵌套子人脸,结构同父级;展平后各自使用自身设置

调用示例

签名方式同获取上传地址:请求头携带 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"
    }]
  }'

返回参数

字段类型说明
codeinteger状态码,成功为 0
messagestring错误提示;成功时为 success
datanull绑定成功时为空

返回示例

json
{"code": 0, "message": "success", "data": null}

常见错误

  • agent_code 不存在或不属于当前租户。
  • 人脸添加至智能体失败(如超出智能体人脸数量上限)。
  • 缺少 agent_code、face_records 或 face_record_id。
  • 操作者不是租户管理员。