Client receives a network timeout after job creation
Recover and poll the original job ID if it was returned or persisted before retrying creation.
Duplicate jobs that consume usage and make support history hard to understand.
MOTION CAPTURE API
Motion capture API for video jobs
Build async video mocap jobs with upload, polling, and downloadable motion outputs through the AIMoCap API.
For developers looking for a motion capture API instead of a manual-only mocap tool.
Short answer
AIMoCap's motion capture API is designed for applications that need durable request state: create a job, attach uploaded source video, poll status, and store the returned artifacts.
When to use AIMoCap
Use AIMoCap when a motion capture API workflow needs upload URLs, queued processing, result polling, v-credit accounting, and target-aware outputs such as Default or Unitree G1.
When not to use AIMoCap
Do not use this API when you need real-time live capture, synchronous per-frame solving, undocumented private targets, or hardware-ready robot control without downstream validation.
Related AIMoCap resources
A motion capture API is useful when mocap needs to run inside another product, batch workflow, or internal tool rather than only inside a browser Studio.
AIMoCap uses an asynchronous job model: create a job, upload the video to the returned upload URL, complete the upload, poll for status, then download the available outputs.
The API path is intentionally separate from web Studio usage. API jobs use API v-credit and can be labeled separately in history so automated processing is not confused with manual Studio credits.
A strong API integration should be observable. The client should know whether a job is waiting for upload, queued, processing, completed, failed validation, failed processing, or missing a specific target artifact.
Developer-facing API boundaries
- The API is asynchronous; clients should poll job status rather than waiting for a single blocking response.
- For a broad motion-capture API integration, Default and Unitree G1 are the current public targets that clients should model explicitly.
- Default output is animation-oriented and can include downloadable FBX motion.
- Unitree G1 output is robot-oriented and should be validated in the downstream robotics or simulation environment.
- For motion-capture API integrations, API v-credit is tracked separately from web Studio credits.
- Trim start and end are optional; final validation uses AIMoCap-side source metadata rather than trusting user-provided file size.
- Motion-capture API jobs can request FBX export FPS values of 24, 30, 60, and 120 when using animation-oriented output.
- A production client should preserve the original job ID across upload, complete-upload, polling, and result download retries.
- A missing target artifact should be handled differently from a failed job, because one target can fail or be unavailable while other artifacts may still exist.
- For user-facing products, expose queued and processing states instead of collapsing every long-running job into a generic timeout.
Motion capture API production-readiness matrix
Use this matrix before wiring mocap into a user-facing app or batch pipeline so integration teams can separate job lifecycle reliability, artifact availability, retry behavior, and billing traces.
Scenario
Recommended action
Watch for
Job completes but one expected artifact is missing
Check which target was requested and whether the result type is supported for that target before treating the whole job as failed.
Assuming Default FBX, robot output, preview video, and custom avatar results are interchangeable artifacts.
Users upload varied source videos
Surface source-quality guidance, trim controls, status states, and retry advice in the product UI.
Blaming the API for clips with cropped bodies, heavy occlusion, unstable cameras, or unclear trim ranges.
Motion capture API integration objections
Teams comparing motion capture APIs usually worry about reliability, retries, billing, and whether result artifacts can be tied back to a source request.
A mocap API is a job system
The client should persist create/upload/complete/poll/download state instead of treating mocap as a single synchronous conversion call.
Failure modes need product handling
Invalid FPS, file-size limits, insufficient v-credit, queue delays, and processing failures should have separate client behavior so users do not see one generic error.
Artifact identity matters
API clients should store which target produced which artifact because Default FBX, preview assets, and Unitree G1 output serve different downstream owners.
API integration facts
Use these facts to decide whether this workflow matches your output, integration, and cleanup needs.
Queue-safe lifecycle
The create-upload-complete-poll flow lets client apps avoid long synchronous requests while the mocap job moves through queued, processing, and completed states.
Usage accounting boundary
API jobs consume API v-credit and should be displayed separately from web Studio credit usage, especially when the same account uses both interfaces.
Target-aware results
A single integration should request the output targets it actually needs; animation FBX output and Unitree G1 robot output are different artifacts.
State observability
The API is more useful when clients persist each stage: create, upload, complete-upload, queue, process, package, complete, and download.
Artifact specificity
Clients should store which artifact came from which target so downstream tools do not mistake preview video, FBX, or robot motion data for the same result type.
Lifecycle acceptance record
For a motion capture API launch test, keep the created job ID, upload URL stage, complete-upload response, queue status, final status, result artifact URLs, and the exact user-visible state shown for each transition.
Duplicate-job retry proof
The client should prove that retrying upload, complete-upload, polling, and result download does not create duplicate jobs or lose a job that is still queued or processing.
Support state map
Map API lifecycle states to support copy before release: waiting for upload, queued, processing, source rejected, processing failed, completed, and artifact unavailable need different troubleshooting paths.
Motion capture API lifecycle
01
Create an async job
Send a title, supported target IDs, optional trim fields, and export FPS. The response returns a job ID and an upload URL for the source video.
02
Upload and admit the source
Upload the video to the returned URL, then call complete-upload so AIMoCap can verify the source object, enforce file and plan limits, and place the job into the queue.
03
Poll and download outputs
Poll the job endpoint until completion. Download preview, FBX, or Unitree G1 motion output only when the requested target produced that artifact.
04
Record operational state
Store job ID, requested targets, upload status, terminal status, artifact URLs, v-credit cost, and retry history so support can trace every API run.
Common questions
Is the AIMoCap motion capture API synchronous?
No. It is designed as an async job API. Create the job, upload source video, complete the upload, poll status, and download outputs after completion.
Which targets can API jobs request?
The current public API target set includes Default and Unitree G1. Clients should request only the targets needed for their workflow.
When are API v-credits charged?
API v-credit is tied to API job processing and remains separate from web Studio credits. System-side failures should be handled by the API lifecycle and ledger logic rather than mixed with manual Studio usage.
Can the API return both animation and robot outputs?
A job can request supported targets, but each output type has a different downstream purpose. FBX is animation-oriented, while Unitree G1 output is robot-oriented.
Should clients send file size or duration as trusted billing values?
No. Clients can provide helpful metadata when documented, but AIMoCap validates source size and duration through the upload and processing lifecycle.
What states should a motion capture API client display?
A useful client distinguishes waiting for upload, queued, processing, completed, source validation failure, processing failure, and missing or unavailable target artifacts.
How should an API client handle timeouts?
Persist the job ID early, retry only the failed stage, and poll the original job before creating a duplicate job.
Related AIMoCap guides
Continue through this topic cluster to compare output formats, API options, and workflow boundaries.
Mocap API
Async job creation, upload, polling, and downloads.
API decision checklist
Use output, limits, and accounting to evaluate fit.
Output formats guide
Compare animation, preview, and robot artifacts.
FBX animation API from video
Use AIMoCap API jobs to request Default output and download animation-ready FBX motion after processing.
Robot motion API for video mocap
Use target-aware AIMoCap API jobs when your integration needs robot motion output such as Unitree G1.
Video to FBX API workflow
Create AIMoCap video-to-FBX API jobs, upload source clips, poll status, and download outputs when processing completes.
Sources reviewed
These related AIMoCap resources document the workflow boundaries, output formats, and implementation details referenced on this page.