上传素材到 TOS 对象存储
接口介绍
接口路径:PUT <upload_url>(获取上传地址返回的预签名地址,直连对象存储,不经过平台网关)
把实际的人脸图片(或声纹音频)文件字节直传到 TOS 对象存储。目标 bucket 与对象 path 由平台签发 upload_url 时已经指定并编入地址,调用方原样使用整个地址即可,不能也不需要自行指定。完整链路:
- 获取上传地址,得到带签名的
upload_url与原始地址store_url; - 本接口:用 HTTP PUT 把图片字节上传到
upload_url对应的 TOS bucket 与 path; - 以
store_url作为face_img_url调用注册接口,得到人脸 ID(face_record_id/face_uid); - 用人脸 ID 调用绑定接口绑定一个或多个智能体。
- 预签名地址一次性使用,有效期约 1 小时(加密租户以返回地址实际有效期为准),拿到后尽快上传。
- 该链路不做并发与去重处理:每次获取地址都会生成随机对象名,重复上传、重复注册会产生新对象和新的人脸记录,是否重复由调用方自行保证;需要去重或一步完成时改用一步接口。
- 上传成功不产生新地址:带签名地址即本次使用的
upload_url(仅本次上传有效),原始地址即store_url(后续注册与绑定都传它,需自行保存)。
请求参数
本接口没有 JSON 请求体,参数全部在 HTTP 层:
| 项目 | 必填 | 说明 |
|---|---|---|
| 方法 | 是 | PUT,必须与签名方法一致;用 GET/POST 请求同一地址会因方法不匹配校验失败 |
| 地址 | 是 | upload_url 完整地址(含全部签名 query 参数),原样使用,不可截断 query 或修改 host/path |
Header Content-Type | 建议 | 文件 MIME 类型,与获取上传地址时传入的 content_type 保持一致,如 image/png、audio/wav |
| Body | 是 | 文件原始字节(raw bytes);不是 base64 字符串,也不是 multipart 表单 |
无需携带 X-App-Id、X-Signature 等鉴权头:签名已包含在 upload_url 的 query 参数中,额外添加 Authorization 类头反而可能导致校验失败。
调用示例
下方命令可直接复制运行:把 <upload_url> 替换为获取上传地址返回的 data.upload_url,face-001.png 替换为实际文件。
bash
# upload_url 形如 https://<bucket>.tos.example.com/<对象path>?<签名参数>
# bucket 与对象 path 由平台指定,调用方原样使用整个地址
curl -sS -X PUT \
-H "Content-Type: image/png" \
--data-binary @face-001.png \
"<upload_url>" \
-o /dev/null -w "%{http_code}\n"
# 输出 200 即上传成功;校验完整性可加 -D - 查看 ETag 响应头
返回参数
TOS 直传不返回 JSON,成功即 HTTP 200:
| 项目 | 说明 |
|---|---|
| HTTP 状态码 | 200 表示上传成功,文件已写入签发地址指定的 bucket 与 path |
| ETag 响应头 | 对象内容的 MD5,可用于校验文件完整性 |
上传完成后可用的两个地址均来自获取上传地址的返回:
| 地址 | 说明 |
|---|---|
带签名地址 upload_url | 本次上传使用的预签名地址,一次性、短期有效,仅用于本次 PUT 上传 |
原始地址 store_url | 不带签名的对象存储地址,注册时作为 face_img_url / origin_audio_url 传入 |
返回示例
text
HTTP/1.1 200 OK
ETag: "6d8f3c9a1b2e4f5a7c8d9e0f1a2b3c4d"
常见错误
403签名校验失败:地址过期(约 1 小时)、已被使用过、query 被截断或改动,或Content-Type与签发时不一致。400请求体非法:误传 base64 字符串或 multipart 表单,应传文件原始字节。- 用 GET/POST 请求
upload_url(方法与签名不匹配),包括在浏览器中直接打开。 - 注册时报素材不存在:上传未成功就调用了注册接口,或注册传入的不是
store_url。