声明本次要上传的帧数。接口返回任务 ID 和一个批量上传地址。

POST https://www.watrixgait.com/v1/sequences
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "frame_count": 24
}

Response:
{
  "task_id": "seq_xxx",
  "upload": {
    "upload_url": "/v1/sequences/seq_xxx/uploads/batch",
    "upload_token": "...",
    "frame_count": 24,
    "upload_expires_at": "2026-08-13T12:00:00Z"
  }
}

以 multipart/form-data 一次上传全部图片。frames 是重复文件字段，服务端按字段出现顺序映射帧序号，文件名不参与逻辑。单次请求总大小最大 32 MB。

POST https://www.watrixgait.com/v1/sequences/{task_id}/uploads/batch
Content-Type: multipart/form-data

upload_token={upload.upload_token}
frames=<第 1 张图片文件内容>
frames=<第 2 张图片文件内容>

上传完成后使用空对象发起解析。接口自动读取已上传帧，并同步返回步态、ReID、人脸特征和 ReID 属性。任务成功不代表每条序列都有特征：算法会做人形质量评估，露出全身的有效帧少于 15 帧时该序列无效，相关特征数组返回为空。

POST https://www.watrixgait.com/v1/sequences/{task_id}/parse
Authorization: Bearer <api_key>
Content-Type: application/json

{}

Response:
{
  "task_id": "seq_xxx",
  "status": "succeeded",
  "sequence_count": 2,
  "sequences": [{
    "sequence_id": "seq_xxx_split_01",
    "batch": 0,
    "frame_count": 12,
    "frames": [
      {"frame_id": 0, "box": [120, 40, 220, 260]}
    ],
    "gait_feature": [0.1234, 0.5678],
    "reid_feature": [0.2345, 0.6789],
    "face_feature": [0.3456, 0.7890],
    "reid_structure_raw": [0, 12],
    "reid_attributes": [],
    "reid_summary": ""
  }, {
    "sequence_id": "seq_xxx_split_02",
    "batch": 1,
    "frame_count": 12,
    "frames": [],
    "gait_feature": [],
    "reid_feature": [],
    "face_feature": [],
    "reid_structure_raw": [],
    "reid_attributes": [],
    "reid_summary": ""
  }]
}

返回的 gait_feature、reid_feature、face_feature 都是已归一化的特征向量。业务侧需要比较两个特征是否相似时，使用同类型特征做点积计算，点积结果就是余弦相似度。

cosine_similarity(A, B) = dot(A, B) / (norm(A) * norm(B))

平台输出的 A、B 已归一化：
cosine_similarity(A, B) = dot(A, B)

JavaScript:
function dot(a, b) {
  return a.reduce((sum, v, i) => sum + v * b[i], 0);
}

const score = dot(sequenceA.gait_feature, sequenceB.gait_feature);