AIMoCap Docs

API Reference

Request and response fields for AIMoCap async mocap jobs, plus a Python example.

Async workflow

1. Create a job

POST /api/v1/mocap/jobs

Request body:

{
  "title": "tennis-02",
  "sourceType": "upload",
  "sourceFilename": "tennis_02.mp4",
  "sourceBytes": 24500812,
  "sourceDurationSec": 18.4,
  "trimStartSec": 1.2,
  "trimEndSec": 13.8,
  "targetId": "default"
}

Field reference:

Field	Type	Required	Notes
`title`	string	No	Optional job title
`sourceType`	string	Yes	Fixed to `upload` in v1
`sourceFilename`	string	Yes	Original filename
`sourceBytes`	number	Yes	File size in bytes
`sourceDurationSec`	number	Yes	Full clip duration
`trimStartSec`	number	Yes	Selected start time
`trimEndSec`	number	Yes	Selected end time
`targetId`	string	Yes	`default`, `unitree_g1`, or `avatar:{avatarId}`

Response:

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

2. Upload the source file

Upload the source clip to uploadUrl with PUT.

3. Complete upload admission

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

If admission succeeds:

the job moves into the queue
API v-credit is consumed

4. Poll job status

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

Example response fields:

{
  "job": {
    "id": "mocap_xxx",
    "status": "processing",
    "targetIds": ["default"]
  },
  "events": [],
  "result": null
}

5. Read the final result

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

Common result fields:

Field	Notes
`jobId`	Job identifier
`status`	Final job status
`targetId`	Output target
`previewVideoUrl`	Preview video URL
`manifestUrl`	Result manifest URL
`createdAt`	Creation timestamp
`updatedAt`	Last update timestamp
`completedAt`	Completion timestamp

Target-specific result fields:

Target	`resultType`	Result field
`default`	`fbx`	`fbxUrl`
`avatar:{avatarId}`	`fbx`	`fbxUrl`
`unitree_g1`	`robot_motion_json`	`motionJsonUrl`

Python example

import time
import requests

BASE_URL = "https://aimocap.net"
API_KEY = "sk-your-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",
    "sourceType": "upload",
    "sourceFilename": "tennis_02.mp4",
    "sourceBytes": len(video_bytes),
    "sourceDurationSec": 18.4,
    "trimStartSec": 1.2,
    "trimEndSec": 13.8,
    "targetId": "default",
}

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("result type:", result["resultType"])
print("preview:", result.get("previewVideoUrl"))
print("fbx:", result.get("fbxUrl"))
print("motion json:", result.get("motionJsonUrl"))

Documentation