# AI3D API v2 model: hy-motion-mixamo Generate short Mixamo-compatible humanoid motion clips from a text prompt with the Yosun HY-Motion Mixamo Hugging Face Space. - AI3D model ID: `hy-motion-mixamo` - Task: `text_to_motion` - AI3D provider adapter: `gradio` (Hugging Face Space) - Space: - Underlying model: Tencent HY-Motion 1.0 Lite - Availability: check `GET https://api.ai3d.dev/v2/models`; customer-key model allowlists and plan policy may restrict access. - Shared implementation guide: - API reference: - Tencent license copy: ## License acceptance Read the linked Tencent HY-Motion 1.0 Community License Agreement and Acceptable Use Policy before submitting a job. The licensed territory excludes the European Union, the United Kingdom, and South Korea. Do not use or distribute the model or its outputs outside the licensed territory. Do not use the model or outputs to improve another AI model, except Tencent HY-Motion 1.0 or its derivatives. All other restrictions in the license and its Acceptable Use Policy apply. The Terms of Service also incorporates these restrictions. Set `input.accepted` to `true` only after reviewing and agreeing to these terms and confirming that the use is within the licensed territory. The API rejects jobs without this explicit acceptance. AI3D routes the call to the Space's generation callback, which receives that acceptance value. ## Request Use the AI3D v2 job API. Do not call Gradio directly or put Hugging Face credentials in a client. The worker wakes the Space if it is paused, sends the text prompt and generation controls, polls the callback, and archives its returned animation file. ```bash curl -X POST https://api.ai3d.dev/v2/jobs \ -H "Authorization: Bearer $AI3D_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: hy-motion-" \ -d '{"model":"hy-motion-mixamo","input":{"accepted":true,"prompt":"A person walks forward, turns left, then waves hello."}}' ``` - Method and URL: `POST https://api.ai3d.dev/v2/jobs` - Authentication: `Authorization: Bearer ` with write permission and this model allowed on the key. - Source: text only; do not provide `image_url`, `video_url`, `source_job_id`, or `model_url`. - Required `input` fields: `accepted: true` and `prompt`. - Optional job controls: `viewer_style`, `publish`, `slug`, and paired `webhook_url`/`webhook_secret`. - Price: fixed AI3D price of $0.10 per Hugging Face Space job. Check `/v2/billing/prices` before submission. Accepted `input` fields: - `accepted`: must be `true` after reviewing the Tencent license and confirming the job is within its licensed territory. - `prompt`: required string, 1–500 characters and no more than 60 words. Describe one person's movement in English. - `duration`: 0.5–5 seconds in 0.5-second increments; default `3.0`. - `cfg_scale`: 1–10 in 0.5 increments; default `5.0`. - `seed`: non-negative integer or `null`; default `null`. - `export_format`: `glb` or `bvh`; default `glb`. - `loop`: boolean; default `false`. Blends the end toward the start for looping. - `zero_root_xz`: boolean; default `false`. Removes horizontal root movement to keep the animation in place. Prompts work best when they describe a single humanoid's body movement. Clothing, scenery, camera directions, multiple people, and exact in-place walking are not reliably controlled by the model. ## Job lifecycle and output 1. Check `GET https://api.ai3d.dev/v2/models`; `hy-motion-mixamo` must appear in the enabled catalog. Check `/v2/billing/prices` for the current price. 2. Submit `POST /v2/jobs` with a fresh `Idempotency-Key`. A successful request returns `202 Accepted` and a job ID. 3. Poll `GET /v2/jobs/{job_id}` with the same bearer key until the status is `succeeded`, `failed`, or `submission_unknown`. 4. On success, download the animation file from its authenticated artifact `download_url`. The default GLB animation clip can be previewed with a compatible Mixamo rig; BVH files are intended for animation tools such as Blender. The clip contains animation data only and has no avatar mesh. The model is powered by Tencent HY-Motion 1.0. The Space uses its Lite variant and retargets generated motion to Mixamo-compatible bone names. Tencent claims no rights in outputs; you are responsible for their use under the license. ## Wake-up and retry safety The worker checks the Hugging Face runtime before generation. If the Space is `PAUSED` or `STOPPED`, it requests a restart and waits for serving status. A cold start can keep the job queued while Cloud Tasks retries. The worker needs `HF_TOKEN` configured with `repo.write` permission for the Space owner; API clients do not need Hugging Face credentials. If submission times out, retry the identical request with the same idempotency key. Do not automatically create a second job when the status is `submission_unknown`; the Space may have accepted the generation before its response was saved.