一步完成人脸上传、注册与多智能体绑定

接口介绍

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

一次调用完成:图片上传对象存储 → 注册人脸 → 绑定到智能体列表。返回的 face_uid 以 AGI 开头。

  • 图片以 base64 传入,支持 data:image/...;base64, 前缀,解码后不超过 5MB;服务端上传对象存储后,用生成的 store_url 注册,不支持外部图片直链。
  • 同图去重:同一张图在去重窗口内(默认 1 天)重复调用会自动复用已注册的人脸,跳过上传与注册、只补绑本次的智能体——组织智能体超过单次上限分批绑定时不产生重复人脸。
  • face_group_name 同时写入人脸记录与各智能体的人脸分组;该分组不存在时平台自动创建(默认分组除外),已存在则复用。
  • agent_codes 可选:不传时自动绑定租户下全部 NORMAL(非模板)智能体;租户下没有智能体或超过平台配置的上限(默认 10 个)时返回错误,此时需显式传入,且同样受该上限约束。
  • 绑定在服务端并行执行,全部成功返回 bound_agent_codes。任一失败返回 face_bind_failed,data 携带 face_record_id、face_uid、bound_agent_codes、failed_agent_codes,可用绑定接口补绑,或用删除接口清理。
  • 只写智能体层;设备侧在事务提交后异步下发(约 10s 感知)。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。

请求参数

字段类型必填说明
tenant_idinteger (int64)是目标租户 ID,必须与操作者租户匹配
face_group_namestring是人脸分组名称,同时写入人脸记录与智能体人脸列表
face_img_base64string是人脸图片 base64,允许 data URI 前缀,解码后不超过 5MB
file_namestring否文件名(含扩展名),仅用于对象名后缀;缺省按 content_type 推导
content_typestring否图片 MIME 类型,默认 image/jpeg
name_zhstring否被注册用户中文名
sexstring否性别
birthdaystring否生日,如 2000-01-01
introductionstring否人物介绍(会做内容风控)
register_user_imgstring否注册用户头像的平台存储地址
agent_codesarray of string否要绑定的智能体编码;数量上限由平台配置控制(默认 10 个);不传时自动绑定租户全部 NORMAL(非模板)智能体
nick_namestring否人脸昵称,应用到全部目标智能体
greet_textstring否打招呼文案,应用到全部目标智能体
memoryinteger否是否启用记忆:0 关闭,1 开启

调用示例

接口采用 AK/SK 签名鉴权,请求头需携带 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature。签名 = HMAC-SHA256(AppSecret, METHOD\nPATH\nTIMESTAMP\nNONCE),只使用 URL path,不含 query。

下方命令可直接复制运行:替换凭证后先跑一次即可验证连通性(在线调试),再按「请求参数」修改 -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/registration-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,
    "face_group_name": "default",
    "face_img_base64": "<图片 base64>",
    "file_name": "face.jpg",
    "content_type": "image/jpeg",
    "name_zh": "test-user",
    "agent_codes": ["AI_AGENT_28159402", "AI_AGENT_28159403"],
    "nick_name": "Alice",
    "greet_text": "Hello",
    "memory": 1
  }'

返回参数

字段类型说明
codeinteger状态码,成功为 0
messagestring错误提示;成功时为 success
data.face_record_idinteger创建的人脸记录 ID
data.face_uidstring人脸 UID,以 AGI 开头
data.face_group_namestring人脸分组名称
data.face_img_urlstring图片的对象存储地址
data.bound_agent_codesarray of string绑定成功的智能体编码(按请求顺序)

返回示例

json
{
  "code": 0,
  "message": "success",
  "data": {
    "face_record_id": 990002,
    "face_uid": "AGI8F3C...",
    "face_group_name": "default",
    "face_img_url": "https://tos.example.com/face/xxx.jpg",
    "bound_agent_codes": ["AI_AGENT_28159402", "AI_AGENT_28159403"]
  }
}

部分绑定失败时,data 结构为:

json
{
  "face_record_id": 990002,
  "face_uid": "AGI8F3C...",
  "bound_agent_codes": ["AI_AGENT_28159402"],
  "failed_agent_codes": ["AI_AGENT_28159403"]
}

常见错误

  • 图片 base64 非法或解码后超过 5MB。
  • 租户下没有可绑定智能体,或智能体数量超过平台配置上限(默认 10 个)但未传 agent_codes。
  • 智能体不存在或不属于当前租户。
  • 图片无法完成特征提取,或人物介绍未通过内容风控。
  • 操作者不是租户管理员。