获取人脸素材上传地址

接口介绍

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

发放人脸/声纹素材的预签名上传地址,文件直传对象存储、不经过平台服务:

  1. 调用本接口获取 upload_url 与 store_url;
  2. 使用 HTTP PUT 将文件字节直传到 upload_url(见上传素材到 TOS 对象存储);
  3. 以 store_url 作为 face_img_url(人脸)或 origin_audio_url(声纹)调用注册接口。
  • upload_url 一次性使用,有效期约 1 小时(加密租户以返回地址实际有效期为准),拿到后尽快上传。
  • 每次上传都会生成随机对象名(UUID + 原扩展名),同名文件不会覆盖,store_url 每次不同,需自行保存。
  • 平台不代拉外部 URL,也不提供已上传素材或人脸记录的查询能力。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。

请求参数

字段类型必填说明
tenant_idinteger (int64)是目标租户 ID,必须与操作者租户匹配
file_namestring是文件名(含扩展名),决定对象名后缀,如 face-001.png
content_typestring否文件 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>"

返回参数

字段类型说明
codeinteger状态码,成功为 0
messagestring错误提示;成功时为 success
data.upload_urlstring预签名 PUT 地址,一次性使用
data.store_urlstring文件存储地址,注册时作为 face_img_url / origin_audio_url 传入;需自行保存
data.original_file_namestring回显请求中的文件名

返回示例

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 为空。
  • 操作者不是租户管理员。