注册人脸与声纹

接口介绍

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

创建人脸记录,可同时注册声纹。face_img_url 与 voice_prints 至少提供一项,素材必须是获取上传地址返回的 store_url,不支持外部直链。

  • 不支持更新。face_record_id 可选;同租户下该 ID 已有 active 人脸时返回“已存在”。
  • 成功后返回 face_record_id 与 face_uid,后续绑定与删除可直接使用,无需自行指定 ID。
  • face_group_name 对应的分组不存在时平台自动创建(默认分组除外),注册后即可在平台页面按分组看到。
  • introduction 会做内容风控;图片/音频需能完成特征提取。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。

请求参数

字段类型必填说明
tenant_idinteger (int64)是目标租户 ID,必须与操作者租户匹配
face_record_idinteger (int32)否调用方指定的人脸记录 ID;同租户下已有 active 记录时拒绝创建
face_group_namestring是人脸分组名称,如 default
face_img_urlstring见说明人脸图片的平台存储地址;与 voice_prints 至少提供一项
name_zhstring否被注册用户中文名
sexstring否性别
birthdaystring否生日,如 2000-01-01
introductionstring否人物介绍(会做内容风控)
register_user_imgstring否注册用户头像的平台存储地址
voice_printsarray见说明声纹列表;与 face_img_url 至少提供一项
voice_prints.voice_print_idstring否声纹 ID,更新已有声纹时提供
voice_prints.origin_audio_urlstring是(声纹项内)声纹音频的平台存储地址
voice_prints.signature_audio_urlstring否已签名音频地址
voice_prints.namestring否音频名称
ref_sentence_zhstring否中文语音注册参考句
ref_sentence_enstring否英文语音注册参考句
ignore_voice_text_checkboolean否是否忽略语音文本校验,默认 false
ignore_voice_duration_checkboolean否是否忽略语音时长校验,默认 false

调用示例

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

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",
    "name_zh": "test-user",
    "face_img_url": "<获取上传地址接口返回的 store_url>",
    "voice_prints": [{
      "voice_print_id": "voice-1",
      "origin_audio_url": "<获取上传地址接口返回的 store_url>",
      "name": "sample"
    }]
  }'

返回参数

字段类型说明
codeinteger状态码,成功为 0
messagestring错误提示;成功时为 success
data.face_record_idinteger创建或更新的人脸记录 ID
data.face_uidstring人脸 UID,可用于后续绑定与删除

返回示例

json
{
  "code": 0,
  "message": "success",
  "data": {
    "face_record_id": 990002,
    "face_uid": "face-uid-1"
  }
}

常见错误

  • face_record_id 已存在。
  • face_img_url 与 voice_prints 均未提供。
  • 图片/音频素材无法完成特征提取。
  • 内容风控未通过。
  • 操作者不是租户管理员。