Quickstart

Make your first dance generation in five steps: get an API key, submit audio, poll for completion, then download a preview MP4 and 3D motion files.

This guide walks you through making your first MVNT API call. By the end you will have submitted an audio file, waited for the generation to complete, and downloaded both a preview MP4 and a 3D motion file.

1. Get an API key

   All MVNT API requests require a bearer token. Create one in MVNT Studio Platform:

   1. Sign in.
   2. Open the API Keys tab.
   3. Click Create Key and choose Production or Sandbox/Test.
   4. Copy the full key immediately — it is shown only once.

   Production keys have the prefix mvnt_live_. Test keys have the prefix mvnt_test_. Store your key in an environment variable so it stays out of your code:

   export MVNT_API_KEY=mvnt_live_xxxxxxxxxxxx
   

   Never paste your API key directly into source code, workflow files, or public repositories. See Authentication for security best practices.

2. Create a generation

   Submit a POST request to /generate-motion with your audio file and generation parameters. The API accepts multipart form data.

   curl -X POST "https://api.mvnt.studio/generate-motion" \
     -H "Authorization: Bearer $MVNT_API_KEY" \
     -F "file=@song.wav" \
     -F "style=All" \
     -F "model_version=v11_gender" \
     -F "sampler=ddim" \
     -F "n_steps=200"
   

   The API responds immediately with a job object. The status field starts as queued — the motion model has not started yet.

   {
     "job_id": "{job_id}",
     "status": "queued",
     "message": "Motion generation started (model=v11_gender, style=All, seed=-1)",
     "trim_start": 0.0,
     "trim_end": 0.0,
     "mode": "standard",
     "sampler": "ddim",
     "n_steps": 200,
     "backend": "local",
     "queue_depth": 0
   }
   

   Save the job_id value — you will use it to poll status and download outputs.

3. Poll for completion

   Send a GET request to /job/{job_id} to check the status of your job. Repeat until the status reaches a terminal state.

   curl "https://api.mvnt.studio/job/{job_id}" \
     -H "Authorization: Bearer $MVNT_API_KEY"
   

   The status field moves through the following lifecycle:

   Status	Meaning
   queued	The job has been accepted and is waiting to run
   running	The motion model is actively generating
   completed	Outputs are ready to download
   failed	The job failed; any credit hold is released
   cancelled	The job was cancelled before completion

   Poll every 2–5 seconds for short audio clips. For longer audio or partner integrations, increase the interval to avoid rate-limiting your own requests.

4. Download the preview MP4

   Once the status is completed, download the preview MP4. This is the default human-readable output and is suitable for product UI, QA reviews, and motion-transfer workflows.

   curl -L "https://api.mvnt.studio/render-mp4/{job_id}" \
     -H "Authorization: Bearer $MVNT_API_KEY" \
     --output preview.mp4
   

   The -L flag tells curl to follow redirects if the endpoint returns one.

5. Download motion files

   For 3D pipelines — Blender, Unity, Unreal, or custom retargeting — download the BVH or GLB file.

   BVH

   curl -L "https://api.mvnt.studio/download-bvh/{job_id}" \
     -H "Authorization: Bearer $MVNT_API_KEY" \
     --output motion.bvh
   

   curl -L "https://api.mvnt.studio/download-glb/{job_id}" \
     -H "Authorization: Bearer $MVNT_API_KEY" \
     --output motion.glb
   

   Output entitlements depend on your MVNT Studio plan. Check your plan’s output access in MVNT Studio Platform.

Next steps

You have completed a full generation cycle. From here you can:

• Open the API Reference tab for every parameter accepted by POST /generate-motion
• Learn about output formats and when to use MP4 vs BVH vs GLB
• Set up a ComfyUI integration to run MVNT inside a visual node workflow