Create succeeded but upload failed
Reuse the existing job ID when possible and retry the upload stage instead of creating a second job.
Duplicate jobs that make history, billing, and support traces hard to explain.
MOCAP API
Async mocap API job workflow
Understand the async job lifecycle for AIMoCap API jobs: create, upload, complete, poll, and download.
For developers who need a non-blocking mocap API workflow.
Short answer
An async mocap API separates job creation, upload, queue admission, processing, polling, and download so clients do not hold one request open for the full solve.
When to use AIMoCap
Use AIMoCap's async flow when your application needs reliable job state transitions, retry boundaries, and downloadable artifacts after processing completes.
When not to use AIMoCap
Do not use the async API as a synchronous conversion endpoint or assume a created job has consumed v-credit before source validation and runner preflight complete.
Related AIMoCap resources
Async mocap API searches are more engineering-specific than broad AI mocap API searches. The main question is how to run long video-processing jobs without blocking a client request.
AIMoCap splits the workflow into explicit phases: create a job, upload the source, complete the upload, wait for queue processing, poll status, and download results.
This lifecycle matters because each stage has a different failure mode. A client should treat upload errors, queue limits, source validation failures, processing failures, and completed artifacts as separate outcomes.
Async API state boundaries
- Job creation and queue admission are separate steps.
- Upload failure should be handled before a job is considered processable.
- Clients should poll status and handle queued, processing, completed, and failed states.
- Result URLs are only useful after the corresponding artifact is ready.
- API v-credit is charged around validated processing, not merely because a client opened a create request.
- A retry strategy should distinguish upload retry, complete-upload retry, status polling, and result download retry.
- The async flow is designed for product integrations, not real-time live capture.
- Clients should persist job IDs before upload starts, because upload or complete-upload network errors can happen after the job record exists.
- A terminal failed state should be shown with stage context instead of being treated like a missing result.
- Polling timeout should usually mean continue polling the same job ID, not create a new job or tell the user the backend failed.
- A client-side request timeout after complete-upload can happen while the backend job is already queued or processing, so the status endpoint should remain the source of truth.
- Download retries should verify artifact size or checksum where possible, because a completed job and a partially downloaded file are different states.
Async mocap retry decision matrix
Use this matrix to keep retries idempotent and avoid turning recoverable network failures into duplicate mocap jobs.
Scenario
Recommended action
Watch for
Upload completed but polling timed out
Keep polling the original job status and show queued or processing state rather than a generic processing failure.
Frontend timeouts that hide a backend job still running normally.
Job failed after validation or processing
Show the stage-aware failure if available and let the user retry with a better source clip or different target.
Retrying blindly without knowing whether the failure was upload, source validation, queue admission, runner processing, or packaging.
Result download failed after job completed
Retry the artifact download and verify file size rather than rerunning the mocap job.
Spending v-credit again because the client confused a network download problem with a processing problem.
API integration concerns
Developer-facing mocap searches are rarely about slogans. They are about whether uploads are reliable, billing is auditable, failed jobs are explainable, and returned artifacts fit the actual pipeline.
Persist the job ID before upload work starts
Teams evaluating a async mocap API usually worry about long-running jobs and retries, so the integration should store the job ID for async job processing, upload the source video, call complete-upload, and poll instead of waiting on one fragile request.
Price predictability depends on separate API usage
For async mocap API, developers often need to explain automated job cost to finance or product teams. AIMoCap keeps API v-credit separate from web Studio credits so async job processing traffic can be audited independently.
Output target mismatch is the common integration bug
In async job processing, API users should test whether they need Default FBX, Unitree G1 robot output, or a prepared custom avatar target before scaling traffic; the same source video can produce different async mocap API artifacts for different downstream teams.
Exercise request timeout recovery
For async mocap API work, include a create response saved before upload, a complete-upload request that times out, a resumed polling session, a terminal failed job, and a completed job with a retried artifact download.
Expose resumable state, not just a spinner
An async client should record the AIMoCap job ID, last successful stage, next polling time, terminal status, and artifact readiness so users can leave and return without losing the processing trail.
Why async state modeling matters
Use these facts to decide whether this workflow matches your output, integration, and cleanup needs.
Long-running processing
Video mocap jobs can outlive a normal HTTP request, so polling and terminal state handling are safer than synchronous conversion semantics.
Clear failure ownership
Upload, validation, runner preflight, algorithm processing, packaging, and result download failures require different user messages and retry behavior.
Ledger clarity
API v-credit should map to validated processing work, which is why the lifecycle should not be collapsed into a single opaque call.
Idempotency discipline
Async mocap API retries should be stage-aware so a failed network request does not create duplicate jobs, duplicate uploads, or confusing user histories after the backend accepted work.
Status is source of truth
After complete-upload, the status endpoint should drive the UI because request timeouts do not prove that the backend job stopped.
Download is a separate stage
A completed job can still have a failed client-side download, so artifact retry logic should be separate from job retry logic.
Async resume record
For async mocap API testing, save the job ID immediately after creation, then prove the client can resume after upload timeout, complete-upload timeout, polling interruption, and delayed artifact readiness.
Async retry proof
The client should prove that retrying complete-upload after a timeout does not mislabel a queued backend job as failed or create a duplicate job that consumes credits twice.
Async state map
Async UI copy needs resumable states such as uploading, uploaded, queued, processing, packaging, completed, failed validation, and failed processing so users can leave and return safely.
Async mocap job lifecycle
01
Create a pending job
Send title, target IDs, optional trim fields, and export FPS. The response gives the client a job ID and upload path, but the job is not useful until the source upload is completed.
02
Upload and complete source
Upload the video to the returned upload URL, then call complete-upload. AIMoCap validates the object and admits the job to the queue only after the upload is complete.
03
Poll terminal status
Poll the job status instead of blocking the original request. Download preview, FBX, robot JSON, or other available artifacts after the job reports completed.
04
Make retries stage-aware
Retry upload, complete-upload, polling, and download differently; do not create a new job when the existing job ID can still be recovered and polled.
05
Map backend states to product states
Show uploading, queued, processing, completed, failed, and result-ready distinctly so client timeouts do not look like algorithm failure.
Common questions
Why is the AIMoCap API asynchronous?
Video mocap is a long-running job. The async flow lets clients upload, queue, poll, and download results without keeping a single request open for the full solve.
When should a client start polling?
Start polling after the source upload is completed and the job has been admitted into the processing flow. Before that, upload or validation errors should be handled directly.
What should the client do when a job fails?
Show a stage-aware error when available, avoid treating failed jobs as downloadable results, and let users retry from the appropriate stage instead of silently creating duplicate work.
Is async mocap API billing separate from Studio billing?
Yes. API jobs use API v-credit and should appear separately from web Studio credit usage.
What makes retries safe in an async mocap API?
Persist the job ID, retry the failed stage only, keep polling recoverable jobs, and avoid creating duplicate jobs just because upload or complete-upload returned a network error.
What should a client do when polling times out?
Keep the original job ID and resume polling later. A client timeout does not prove the backend job failed, especially after upload completion.
Should a completed job be rerun if artifact download fails?
Usually no. Retry the download and verify the artifact first; rerun only when the backend job or artifact generation actually failed.
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.
Markerless video mocap API
AIMoCap exposes a markerless video mocap API for supported targets, trim fields, export FPS, polling, and result download.
AI mocap API for production pipelines
Use AIMoCap API v-credit, async jobs, and target-aware outputs to add AI video mocap to production tools.
Unitree G1 robot motion API
Request Unitree G1 as an AIMoCap API target when your integration needs robot motion output from video.
Sources reviewed
These related AIMoCap resources document the workflow boundaries, output formats, and implementation details referenced on this page.