AIMoCap Docs

API 接口说明

AIMoCap 异步 mocap 任务的请求字段、响应字段与 Python 示例。

异步工作流

1. 创建任务

POST /api/v1/mocap/jobs

请求体：

{
  "title": "tennis-02",
  "sourceFilename": "tennis_02.mp4",
  "sourceDurationSec": 18.4,
  "trimStartSec": 1.2,
  "trimEndSec": 13.8,
  "exportFps": 30,
  "mocapType": "full_body",
  "targetIds": ["default", "unitree_g1"]
}

字段说明：

字段	类型	必填	说明
`title`	string	否	可选任务标题。
`sourceFilename`	string	是	原始视频文件名。
`sourceDurationSec`	number	否	视频时长（秒），可缺省。
`trimStartSec`	number	否	裁剪开始时间（秒），缺省为 `0`。
`trimEndSec`	number	否	裁剪结束时间（秒），缺省为上传视频的结束时刻。
`exportFps`	number	否	支持 `24`、`30`、`60`、`120`，缺省为 `30`。
`mocapType`	string	否	`full_body` 或 `upper_body`，缺省为 `full_body`。
`targetIds`	string[]	是	一个任务可以请求一个或多个输出；当前支持 `default` 和 `unitree_g1`。

常见创建阶段错误：

export_fps_invalid
mocap_type_invalid
api_target_ids_required
api_target_unsupported
api_source_duration_invalid
api_duration_limit_exceeded
api_file_size_limit_exceeded
api_trim_range_invalid
api_concurrency_limit_exceeded
api_plan_inactive
insufficient_api_v_credits

响应：

{
  "jobId": "mocap_xxx",
  "status": "draft",
  "mocapType": "full_body",
  "uploadUrl": "https://...",
  "sourceKey": "..."
}

2. 上传源视频

使用 PUT 将源视频上传到 uploadUrl。

3. 完成上传

POST /api/v1/mocap/jobs/{jobId}/complete-upload

上传完成后，调用这个接口提交任务进入处理流程。AIMoCap 会校验上传文件、裁剪区间、账户限制与 API v-credit 余额，然后再开始 mocap 处理。

如果上传文件或请求片段超出当前 API plan 限制，任务会返回明确错误码，并且不会扣除 v-credit。

4. 计费

API 任务使用独立的 API v-credit，不会消耗网页端普通 credits。

v-credit 会在源视频通过处理准入后扣除。扣费数量按最终处理片段时长向上取整秒计算。如果扣费后发生系统侧处理失败，AIMoCap 会对该任务退回一次 v-credit。

5. 查询任务状态

GET /api/v1/mocap/jobs/{jobId}

响应字段示例：

{
  "job": {
    "id": "mocap_xxx",
    "status": "processing",
    "targetIds": ["default", "robot:unitree_g1"],
    "exportFps": 30,
    "mocapType": "full_body"
  },
  "events": [],
  "result": null
}

6. 读取最终结果

GET /api/v1/mocap/jobs/{jobId}/result

常见结果字段：

字段	说明
`jobId`	任务 ID。
`status`	最终任务状态。
`targetIds`	请求的公开输出目标，例如 `default` 和 `unitree_g1`。
`mocapType`	任务使用的捕捉类型：`full_body` 或 `upper_body`。
`previewVideoUrl`	预览视频 URL。
`outputs`	按 target 区分的输出数组。
`createdAt`	创建时间。
`updatedAt`	最近更新时间。
`completedAt`	完成时间。

outputs 中每一项的结构：

字段	说明
`targetId`	`default` 或 `unitree_g1`。
`resultType`	`fbx` 或 `robot_motion_json`。
`status`	输出状态。
`fbxUrl`	`default` 输出会包含。
`motionJsonUrl`	`unitree_g1` 输出会包含。

说明：

一个 API 任务可以同时生成 FBX 和 Unitree G1 机器人动作数据。
集成时应读取 outputs[] 来找到每个 target 对应的结果 URL。
自定义 avatar target 会在后续公开 API 更新中支持。

Python 示例

import time
import requests

BASE_URL = "https://aimocap.net"
API_KEY = "YOUR_AIMOCAP_API_KEY"
VIDEO_PATH = "tennis_02.mp4"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

with open(VIDEO_PATH, "rb") as f:
    video_bytes = f.read()

create_payload = {
    "title": "tennis-02",
    "sourceFilename": "tennis_02.mp4",
    "trimStartSec": 1.2,
    "trimEndSec": 13.8,
    "exportFps": 30,
    "mocapType": "full_body",
    "targetIds": ["default", "unitree_g1"],
}

create_resp = requests.post(
    f"{BASE_URL}/api/v1/mocap/jobs",
    json=create_payload,
    headers=headers,
)
create_resp.raise_for_status()
create_data = create_resp.json()["data"]

upload_resp = requests.put(
    create_data["uploadUrl"],
    data=video_bytes,
    headers={"Content-Type": "video/mp4"},
)
upload_resp.raise_for_status()

complete_resp = requests.post(
    f"{BASE_URL}/api/v1/mocap/jobs/{create_data['jobId']}/complete-upload",
    headers=headers,
)
complete_resp.raise_for_status()

while True:
    job_resp = requests.get(
        f"{BASE_URL}/api/v1/mocap/jobs/{create_data['jobId']}",
        headers=headers,
    )
    job_resp.raise_for_status()
    job_data = job_resp.json()["data"]
    status = job_data["job"]["status"]
    if status in {"completed", "failed", "canceled"}:
        break
    time.sleep(5)

result_resp = requests.get(
    f"{BASE_URL}/api/v1/mocap/jobs/{create_data['jobId']}/result",
    headers=headers,
)
result_resp.raise_for_status()
result = result_resp.json()["data"]

print("preview:", result.get("previewVideoUrl"))
for output in result.get("outputs", []):
    print(output["targetId"], output["resultType"], output.get("fbxUrl") or output.get("motionJsonUrl"))

文档