企业视频开放平台 API（/business） ​

重要：第 1、2 节接口维护说明
POST /business/upload 与 POST /business/download 功能仍提供，后续将逐步不再维护。
新接入请优先使用第 3～5 节（COS 直传：uploadCosCredential → PUT → uploadCosConfirm；结果下载：downloadCosCredential）。

通用约定 ​

骨架类型详情表（bonetype） ​

请求参数 bonetype 为整数，表示输出骨架/格式类型。

说明：服务端对 bonetype 的合法范围另有校验，与 capturetype 的组合约束以接口实际校验为准；上表侧重格式能力与限制说明。

1. 视频上传（后续将逐步不再维护。新接入请优先使用第3，4节） ​

1.1 接口功能 ​

提交 MP4 视频文件 与 制作参数，上传成功后返回 videoId 等。可配置 rollbackUrl，在视频制作完成时由服务端 POST 回调。

1.2 请求方法 ​

POST

1.3 请求路径 ​

https://www.qmai.vip/business/upload

1.4 请求参数 ​

Content-Type：multipart/form-data

1.5 响应信息 ​

响应体为 JSON（CompanyVideoResponse）。

2. 文件下载（后续将逐步不再维护。新接入请优先使用第5节） ​

2.1 接口功能 ​

根据 companyKey、videoId 查询动捕结果，服务端将多个结果文件打包为 ZIP，在响应体中返回二进制内容。

2.2 请求方法 ​

POST

2.3 请求路径 ​

https://www.qmai.vip/business/download

2.4 请求参数（JSON） ​

2.5 响应信息 ​

响应体为 JSON（CompanyDownResponse）。

若服务端内部异常（如无动捕结果文件等），可能返回 HTTP 500 且无 body。

3. 申请 COS 上传凭证 ​

3.1 接口功能 ​

为当前企业生成 直传对象存储的预签名 PUT 地址 及 cosObjectKey。客户端向该 URL PUT 上传 MP4 成功后，再调用 第 4 节 提交业务参数并创建动捕任务。

服务端将 cosObjectKey 与企业做短时绑定，第 4 节会校验该绑定。

3.2 请求方法 ​

POST

3.3 请求路径 ​

https://www.qmai.vip/business/uploadCosCredential

3.4 请求参数（JSON） ​

3.5 响应信息 ​

常见失败：No user information found, please check input key!、Only .mp4 suffix is supported（均为 status=600）。

成功示例：

{
  "message": "OK",
  "status": "200",
  "uploadUrl": "https://example-bucket.cos.ap-guangzhou.myqcloud.com/companyVideoDirect/your-company-key/550e8400-e29b-41d4-a716-446655440000.mp4?q-sign-algorithm=sha1&q-ak=***&q-sign-time=1710000000;1710000300&q-key-time=1710000000;1710000300&q-header-list=host&q-url-param-list=&q-signature=***",
  "cosObjectKey": "companyVideoDirect/your-company-key/550e8400-e29b-41d4-a716-446655440000.mp4",
  "expiresInSeconds": 300
}

3.6 调用步骤 ​

1. 调用本节接口获取 uploadUrl、cosObjectKey。
2. 使用 HTTP PUT 将 MP4 二进制发往 uploadUrl（请求体为文件内容；Header 以预签名要求为准）。
3. 调用 第 4 节，JSON 中携带 cosObjectKey 及业务字段。

4. 确认 COS 上传并创建任务 ​

4.1 接口功能 ​

在客户端已把视频上传到对象存储后，本接口根据 cosObjectKey 启动动捕任务。

业务字段与 第 1 节 中除 videoFile 外的参数含义一致；本节须显式提供 videoName（逻辑名，不可为空，不允许表情符号）。

4.2 请求方法 ​

POST

4.3 请求路径 ​

https://www.qmai.vip/business/uploadCosConfirm

4.4 请求参数（JSON） ​

直传专用 ​

业务参数（与第 1 节一致，无文件） ​

绑定校验：须在 第 3 节 成功且预签名有效期内完成 PUT，且 companyKey 与申请凭证时一致。失败时 message 可能为：Invalid or expired cosObjectKey, please request a new upload credential。

4.5 响应信息 ​

同 第 1 节（CompanyVideoResponse）。成功示例：

{
  "message": "Video uploaded successfully",
  "videoId": "xxxxxxxx",
  "status": "200",
  "videoStatus": "To be produced",
  "data": null
}

4.6 Python 示例 ​

import requests

base = "https://www.qmai.vip/business/"
company_key = "your-company-key"
video_path = r"data\xiaoyu.mp4"

cred = requests.post(base + "uploadCosCredential", json={"companyKey": company_key}).json()
if cred.get("status") != "200":
    raise RuntimeError(cred)

with open(video_path, "rb") as f:
    requests.put(cred["uploadUrl"], data=f).raise_for_status()

payload = {
    "companyKey": company_key,
    "cosObjectKey": cred["cosObjectKey"],
    "videoName": "xiaoyu",
    "bonetype": 1,
    "capturetype": "0",
    "poseType": 1,
}
print(requests.post(base + "uploadCosConfirm", json=payload).text)

5. 获取结果文件下载凭证 ​

5.1 接口功能 ​

根据 videoId、companyKey 解析该任务下可下载的动捕结果文件列表，返回 每个文件的文件名 与 GET 下载地址（预签名 URL 或已是 http(s) 的链接）。不返回 ZIP 二进制，由客户端自行拉取或打包。

5.2 请求方法 ​

POST

5.3 请求路径 ​

https://www.qmai.vip/business/downloadCosCredential

5.4 请求参数（JSON） ​

5.5 响应信息 ​

files 元素

无动捕结果等内部错误时，可能 HTTP 500 且无 body。

成功示例：

{
  "message": "Success",
  "status": "200",
  "videoId": "1919191919",
  "archiveName": "demo_result.zip",
  "files": [
    {
      "fileName": "demo.fbx",
      "downloadUrl": "https://example-bucket.cos.ap-guangzhou.myqcloud.com/result/demo.fbx?q-signature=***"
    },
    {
      "fileName": "demo.bvh",
      "downloadUrl": "https://example-bucket.cos.ap-guangzhou.myqcloud.com/result/demo.bvh?q-signature=***"
    }
  ],
  "expiresInSeconds": 300
}

5.6 Python 示例 ​

import requests

payload = {
    "companyKey": "your-company-key",
    "videoId": "your-video-id",
    "videoSign": 1,
}

resp = requests.post(
    "https://www.qmai.vip/business/downloadCosCredential",
    json=payload,
)
resp.raise_for_status()

data = resp.json()
if data.get("status") != "200":
    raise RuntimeError(data.get("message"))

print("archiveName =", data.get("archiveName"))
for item in data.get("files", []):
    print(item["fileName"], "->", item["downloadUrl"])

6. 上传截图（人框检测） ​

6.1 接口功能 ​

上传 图片 供人框检测服务使用，返回检测结果字符串（如框坐标等），用于多人场景的 mulPersonInfo 等配置。

6.2 请求方法 ​

POST

6.3 请求路径 ​

https://www.qmai.vip/business/uploadPic

6.4 请求参数 ​

Content-Type：multipart/form-data

6.5 响应信息 ​

响应体为 JSON（UploadPicResponse）。

企业不存在时：message 为 No user information found, please check input key!，status 为 600。

成功示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "SUCCESS",
    "multiAddr": "{\"boxes\":\"[[71, 402, 177, 285], [270, 363, 134, 327]]\"}",
    "status": "200",
    "videoStatus": ""
  }
}

6.6 Python 示例 ​

import requests

url = "https://www.qmai.vip/business/uploadPic"
data = {"companyKey": "your-company-key"}

with open(r"data\person.jpg", "rb") as f:
    files = {
        "picture": ("person.jpg", f, "image/jpeg")
    }
    resp = requests.post(url, data=data, files=files)

resp.raise_for_status()
result = resp.json()
if result.get("status") != "200":
    raise RuntimeError(result.get("message"))

print("multiAddr =", result.get("multiAddr"))

7. 消费记录查询 ​

7.1 接口功能 ​

分页查询当前 companyKey 对应企业的 CV 币消费/变动记录。

7.2 请求方法 ​

POST

7.3 请求路径 ​

https://www.qmai.vip/business/consumptionRecord

7.4 请求参数（JSON） ​

继承分页基类字段，并包含企业与时间筛选。

7.5 响应信息 ​

响应体为 JSON（FilterResponse<SurplusRecordDTO>）。

records 元素（SurplusRecordDTO）

成功示例：

{
  "records": [
    {
      "amount": 120,
      "signedAmount": "-120",
      "reason": "视频动捕消费",
      "duration": 15,
      "videoId": "1919191919",
      "videoName": "demo",
      "username": "enterprise_user",
      "createAt": "2026-04-07T10:30:00",
      "statusName": "已完成"
    }
  ],
  "total": 1,
  "size": 20
}

7.6 Python 示例 ​

import requests

payload = {
    "companyKey": "your-company-key",
    "page": 1,
    "size": 20,
    "startTime": "2026-04-01T00:00:00",
    "endTime": "2026-04-07T23:59:59",
}

resp = requests.post(
    "https://www.qmai.vip/business/consumptionRecord",
    json=payload,
)
resp.raise_for_status()

data = resp.json()
print("total =", data.get("total"))
for record in data.get("records", []):
    print(record.get("createAt"), record.get("signedAmount"), record.get("reason"))

8. 查询余额 ​

8.1 接口功能 ​

查询当前 companyKey 对应企业的 CV 币余额。

8.2 请求方法 ​

POST

8.3 请求路径 ​

https://www.qmai.vip/business/queryBalance

8.4 请求参数（JSON） ​

8.5 响应信息 ​

响应体为整数（Integer），表示当前 CV 币余额。

成功示例：

{
  "code": 0,
  "data": 1111,
  "message": "success"
}

8.6 Python 示例 ​

import requests

resp = requests.post(
    "https://www.qmai.vip/business/queryBalance",
    json={"companyKey": "your-company-key"},
)
resp.raise_for_status()

balance = resp.json()
print("balance =", balance)

9. 视频制作进度查询 ​

9.1 接口功能 ​

根据 videoId、companyKey 查询视频任务状态，并在成功时返回 可读的进度文案 与 上传参数快照（与上传表单字段对齐，便于核对）。

9.2 请求方法 ​

POST

9.3 请求路径 ​

https://www.qmai.vip/business/getStatus/{videoId}/{companyKey}

路径参数 videoId、companyKey 中若含特殊字符，请按 URL 规则编码。

9.4 请求参数 ​

无请求体；参数全部来自路径。

9.5 响应信息 ​

响应体为 JSON（CompanyVideoResponse）。

常见 message：企业不存在 No user information found, please check input key!；视频不存在 未查询到上传视频信息，请检查输入的视频ID!。

附录 ​

• 骨架类型、动捕类型、计费规则等以 视频上传接口 及官网更新为准。
• bonetype 能力与限制说明见本文 骨架类型详情表（bonetype）；若与官网表不一致，以官网及更新日志为准。

CopyRight © 千面动捕开放平台文档（项目内副本，发布时请与官网同步）