Avatar is uploaded but not retarget-tested
Keep it out of API automation until A-pose, binding, test motion, and publish have passed review.
Automating against a target that only proved file upload, not motion quality.
CUSTOM AVATAR API
Custom avatar mocap API planning
Plan AIMoCap API usage around published custom avatar targets, web setup, and repeatable motion jobs.
For teams that want API jobs to use custom avatar targets prepared in Studio.
Short answer
A custom avatar mocap API should let a product run repeatable mocap jobs against character targets that have already been prepared, tested, and published.
When to use AIMoCap
Use AIMoCap when your team prepares avatars in Studio first, then wants API jobs to reuse those published targets for automated video mocap workflows.
When not to use AIMoCap
Do not use this API path to skip avatar setup. New FBX characters still need upload, A-pose, binding, retarget testing, and publish steps before they are reliable targets.
Related AIMoCap resources
Custom avatar API planning is different from a generic mocap API integration because the target character is part of the pipeline.
AIMoCap keeps avatar preparation and API processing as separate stages: prepare and publish the avatar through the character workflow, then run repeatable API jobs against supported targets.
This boundary helps teams avoid brittle automation. The API job can focus on upload, queueing, polling, and download while the avatar quality gate remains in the Studio retarget-test process.
A good custom-avatar API plan names the target lifecycle before automation starts: who owns the avatar source file, who approves binding, what test motion passes, and when the target is safe for repeated jobs.
Custom avatar API boundaries
- Custom avatar targets should be prepared and validated before automation depends on them.
- A-pose editing, skeleton binding, retarget testing, and publish are Studio-side quality steps.
- API jobs are best used after a target is reusable, not as a shortcut around binding review.
- Custom avatar API automation consumes API v-credit separately from web Studio credits.
- Default FBX output, custom avatar output, and Unitree G1 robot output are distinct target concepts.
- A failed avatar retarget test should be fixed before the character becomes part of an API workflow.
- The public API job lifecycle remains asynchronous: create, upload, complete, poll, and download.
- A published avatar can still have context-specific limits; hand-heavy clips, extreme poses, and stylized proportions may need separate acceptance tests.
- Custom avatar automation should store both the job artifact and the avatar target version so regressions can be traced to source video, target setup, or algorithm output.
- If an avatar is updated after publication, teams should rerun a small acceptance set before routing production API jobs to the new target.
- An API client should not let users choose draft or untested avatar targets; automation should only expose published targets that have a known acceptance record.
- Custom avatar API jobs should store the published target version alongside source clip, trim range, terminal status, artifact URL, and cleanup verdict.
- If a custom-avatar API job fails on one target but Default output passes, the retry plan should inspect avatar setup before submitting more source videos.
Custom avatar API readiness matrix
Use this matrix before adding a custom avatar target to automated API jobs so teams can separate target readiness, acceptance testing, versioning, and user-facing fallback behavior.
Scenario
Recommended action
Watch for
Avatar passed one simple test clip
Run a small acceptance set with walking, turns, hand motion, and the real source-video style before using it broadly.
A target that works on one flattering clip but fails on production motion categories.
Avatar target is updated or rebound
Treat it as a new target version and rerun acceptance tests before routing API jobs to it.
Hard-to-debug changes where the API job is blamed for a target setup regression.
API automation exposes avatar selection to users
Expose only published targets with target-version metadata, acceptance notes, and clear fallback behavior.
Allowing draft or untested targets into automated jobs and turning setup failures into API support incidents.
Custom avatar API objections
Custom-avatar API users usually need to know whether avatar setup is already complete before automated jobs start using that target.
Published avatar readiness is a prerequisite
API jobs should use a prepared custom avatar only after upload, A-pose review, binding, retarget test, and publish have made the target reusable.
Bad results need two debug tracks
When a custom avatar API output looks wrong, teams should inspect both source-video quality and avatar setup rather than assuming the API job alone failed.
Automation benefits from stable targets
Custom avatar API workflows work best when the same published target is reused across many clips with consistent acceptance notes.
Why custom avatar API needs a setup boundary
Use these facts to decide whether this workflow matches your output, integration, and cleanup needs.
Quality gate before scale
Custom characters vary in skeleton structure and pose quality, so a retarget test is the practical gate before using the avatar in automated jobs.
Published target reuse
The API workflow becomes valuable after the avatar is reusable; repeated jobs can then target the same prepared character without redoing setup each time.
Separated accounting
Automated jobs consume API v-credit, while avatar preparation remains a separate Studio workflow and should not be mixed with API usage reporting.
Target versioning
Custom-avatar API jobs become easier to support when the artifact stores which published target version was used.
Acceptance coverage
A reusable avatar target should be tested on the kinds of motion the product will actually process, not only on a single setup demo.
Automation readiness packet
A production custom-avatar API page should cover target version, accepted clips, API lifecycle, artifact review, failed-job handling, and cleanup verdicts.
Draft-target exclusion
API automation is safer when draft avatars stay out of the selectable target list until their setup and retarget tests pass.
Custom avatar API planning workflow
01
Prepare the avatar before API automation
Upload the FBX character, adjust A-pose if needed, bind the skeleton, run a retarget test, and publish only after the result is approved.
02
Use published targets in repeatable jobs
Once a character target is published, API automation can focus on source video upload, complete-upload, queued processing, polling, and result retrieval.
03
Keep target setup and API usage separate
Avatar setup is a quality gate. API v-credit tracks automated mocap usage separately from web Studio credits and from the one-time character preparation workflow.
04
Version the target decision
Record the published avatar target, test result, approval date, and any known limitations before API jobs depend on it at scale.
05
Run an API readiness packet
Before routing production clips to the avatar target, test create/upload/complete/poll/download plus avatar-version trace, artifact review, and rejection handling.
Common questions
Can AIMoCap API use custom avatars?
A custom avatar should first be prepared, tested, and published through the character workflow. After that, API planning can treat it as a reusable target for repeatable mocap jobs.
Can I upload a new FBX avatar directly inside every API job?
No. New avatars need a setup and quality workflow: upload, A-pose, binding, retarget test, and publish before they are reliable targets.
Why separate Studio avatar setup from API jobs?
Avatar quality depends on skeleton mapping and retarget results. Keeping setup separate prevents an automated API pipeline from repeatedly failing on an unvalidated character.
Does custom avatar API usage consume web credits?
API mocap jobs use API v-credit. Web Studio credits and API v-credit are tracked separately.
Is a custom avatar target the same as Unitree G1?
No. Custom avatars are animation-character targets. Unitree G1 is a robot-oriented target with different downstream artifacts and validation needs.
What should I validate before using a custom avatar in API jobs?
Validate A-pose, skeleton binding, retarget test quality, source-video categories, published target version, and whether the avatar handles the motions your product will process.
What should custom-avatar API jobs store?
Store job ID, source clip, trim range, requested target, published avatar version, result artifact, preview verdict, and cleanup or rejection reason.
Should draft avatars be available to API automation?
No. API automation should use published avatar targets with acceptance records; draft targets should stay in setup until pose, binding, and retarget tests pass.
What should a custom-avatar API readiness test include?
Test create, upload, complete-upload, polling, result download, target-version trace, representative source clips, and how failures are classified between source video and avatar setup.
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.
Async mocap API job workflow
Understand the async job lifecycle for AIMoCap API jobs: create, upload, complete, poll, and download.
Unitree G1 robot motion API
Request Unitree G1 as an AIMoCap API target when your integration needs robot motion output from video.
Motion capture API for video jobs
Build async video mocap jobs with upload, polling, and downloadable motion outputs through the AIMoCap API.
Sources reviewed
These related AIMoCap resources document the workflow boundaries, output formats, and implementation details referenced on this page.