注册人脸与声纹
接口介绍
接口路径: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_id | integer (int64) | 是 | 目标租户 ID,必须与操作者租户匹配 |
| face_record_id | integer (int32) | 否 | 调用方指定的人脸记录 ID;同租户下已有 active 记录时拒绝创建 |
| face_group_name | string | 是 | 人脸分组名称,如 default |
| face_img_url | string | 见说明 | 人脸图片的平台存储地址;与 voice_prints 至少提供一项 |
| name_zh | string | 否 | 被注册用户中文名 |
| sex | string | 否 | 性别 |
| birthday | string | 否 | 生日,如 2000-01-01 |
| introduction | string | 否 | 人物介绍(会做内容风控) |
| register_user_img | string | 否 | 注册用户头像的平台存储地址 |
| voice_prints | array | 见说明 | 声纹列表;与 face_img_url 至少提供一项 |
| voice_prints.voice_print_id | string | 否 | 声纹 ID,更新已有声纹时提供 |
| voice_prints.origin_audio_url | string | 是(声纹项内) | 声纹音频的平台存储地址 |
| voice_prints.signature_audio_url | string | 否 | 已签名音频地址 |
| voice_prints.name | string | 否 | 音频名称 |
| ref_sentence_zh | string | 否 | 中文语音注册参考句 |
| ref_sentence_en | string | 否 | 英文语音注册参考句 |
| ignore_voice_text_check | boolean | 否 | 是否忽略语音文本校验,默认 false |
| ignore_voice_duration_check | boolean | 否 | 是否忽略语音时长校验,默认 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"
}]
}'
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| message | string | 错误提示;成功时为 success |
| data.face_record_id | integer | 创建或更新的人脸记录 ID |
| data.face_uid | string | 人脸 UID,可用于后续绑定与删除 |
返回示例
json
{
"code": 0,
"message": "success",
"data": {
"face_record_id": 990002,
"face_uid": "face-uid-1"
}
}
常见错误
face_record_id已存在。face_img_url与voice_prints均未提供。- 图片/音频素材无法完成特征提取。
- 内容风控未通过。
- 操作者不是租户管理员。