一步完成人脸上传、注册与多智能体绑定
接口介绍
接口路径: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_id | integer (int64) | 是 | 目标租户 ID,必须与操作者租户匹配 |
| face_group_name | string | 是 | 人脸分组名称,同时写入人脸记录与智能体人脸列表 |
| face_img_base64 | string | 是 | 人脸图片 base64,允许 data URI 前缀,解码后不超过 5MB |
| file_name | string | 否 | 文件名(含扩展名),仅用于对象名后缀;缺省按 content_type 推导 |
| content_type | string | 否 | 图片 MIME 类型,默认 image/jpeg |
| name_zh | string | 否 | 被注册用户中文名 |
| sex | string | 否 | 性别 |
| birthday | string | 否 | 生日,如 2000-01-01 |
| introduction | string | 否 | 人物介绍(会做内容风控) |
| register_user_img | string | 否 | 注册用户头像的平台存储地址 |
| agent_codes | array of string | 否 | 要绑定的智能体编码;数量上限由平台配置控制(默认 10 个);不传时自动绑定租户全部 NORMAL(非模板)智能体 |
| nick_name | string | 否 | 人脸昵称,应用到全部目标智能体 |
| greet_text | string | 否 | 打招呼文案,应用到全部目标智能体 |
| memory | integer | 否 | 是否启用记忆: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
}'
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| message | string | 错误提示;成功时为 success |
| data.face_record_id | integer | 创建的人脸记录 ID |
| data.face_uid | string | 人脸 UID,以 AGI 开头 |
| data.face_group_name | string | 人脸分组名称 |
| data.face_img_url | string | 图片的对象存储地址 |
| data.bound_agent_codes | array 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。 - 智能体不存在或不属于当前租户。
- 图片无法完成特征提取,或人物介绍未通过内容风控。
- 操作者不是租户管理员。