获取人脸素材上传地址
接口介绍
接口路径:POST /api/V1/open-portal/app/linksoul/agent-faces/upload-urls
发放人脸/声纹素材的预签名上传地址,文件直传对象存储、不经过平台服务:
- 调用本接口获取
upload_url与store_url; - 使用 HTTP PUT 将文件字节直传到
upload_url(见上传素材到 TOS 对象存储); - 以
store_url作为face_img_url(人脸)或origin_audio_url(声纹)调用注册接口。
upload_url一次性使用,有效期约 1 小时(加密租户以返回地址实际有效期为准),拿到后尽快上传。- 每次上传都会生成随机对象名(UUID + 原扩展名),同名文件不会覆盖,
store_url每次不同,需自行保存。 - 平台不代拉外部 URL,也不提供已上传素材或人脸记录的查询能力。
- 操作者用户 ID 由平台网关注入
X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tenant_id | integer (int64) | 是 | 目标租户 ID,必须与操作者租户匹配 |
| file_name | string | 是 | 文件名(含扩展名),决定对象名后缀,如 face-001.png |
| content_type | string | 否 | 文件 MIME 类型,如 image/png、audio/wav |
调用示例
接口采用 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/upload-urls"
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, "file_name": "face-001.png", "content_type": "image/png"}'
# 从返回中取出 upload_url 后直传
curl -sS -X PUT -H "Content-Type: image/png" --data-binary @face-001.png "<upload_url>"
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| message | string | 错误提示;成功时为 success |
| data.upload_url | string | 预签名 PUT 地址,一次性使用 |
| data.store_url | string | 文件存储地址,注册时作为 face_img_url / origin_audio_url 传入;需自行保存 |
| data.original_file_name | string | 回显请求中的文件名 |
返回示例
json
{
"code": 0,
"message": "success",
"data": {
"upload_url": "https://tos.example.com/img/face/dev/xxx.png?...",
"store_url": "https://tos.example.com/img/face/dev/xxx.png",
"original_file_name": "face-001.png"
}
}
常见错误
tenant_id与操作者租户不匹配。file_name为空。- 操作者不是租户管理员。