# Analyze Audio Endpoint
Source: https://mvnt.studio/docs/api-reference/analyze-audio-endpoint

/openapi.json post /analyze-audio
Analyze audio features and recommend dance styles.



# Cancel Job
Source: https://mvnt.studio/docs/api-reference/cancel-job

/openapi.json delete /job/{job_id}



# Download Bvh
Source: https://mvnt.studio/docs/api-reference/download-bvh

/openapi.json get /download-bvh/{job_id}



# Download Glb
Source: https://mvnt.studio/docs/api-reference/download-glb

/openapi.json get /download-glb/{job_id}
Export completed motion as an animated mesh-inclusive GLB.



# Generate Motion
Source: https://mvnt.studio/docs/api-reference/generate-motion

/openapi.json post /generate-motion



# Get Job Status
Source: https://mvnt.studio/docs/api-reference/get-job-status

/openapi.json get /job/{job_id}



# Get Styles
Source: https://mvnt.studio/docs/api-reference/get-styles

/openapi.json get /styles



# Render Mp4
Source: https://mvnt.studio/docs/api-reference/render-mp4

/openapi.json get /render-mp4/{job_id}
Render a BVH motion preview as MP4 with toon-shaded mannequin.

Sync def so FastAPI runs it in a threadpool -- won't block the event loop.



# Retarget Tripo Glb
Source: https://mvnt.studio/docs/api-reference/retarget-tripo-glb

/openapi.json post /retarget-tripo-glb
Retarget an animated mannequin GLB onto a Tripo T-pose character GLB.



# Variable output formats
Source: https://mvnt.studio/docs/guides/outputs

Every completed MVNT job can expose preview, motion, and metadata outputs. Learn which endpoint to call for MP4, BVH, and GLB.

Every completed MVNT job can expose multiple outputs: a preview MP4 video, motion files for 3D pipelines, and JSON metadata. After `GET /job/{job_id}` returns `status: "completed"`, call the output endpoint that matches the artifact you need.

## Output endpoints

Use the `job_id` returned by `POST /generate-motion` in each output path:

| Format      | Endpoint                     | Typical filename |
| ----------- | ---------------------------- | ---------------- |
| Preview MP4 | `GET /render-mp4/{job_id}`   | `preview.mp4`    |
| BVH motion  | `GET /download-bvh/{job_id}` | `motion.bvh`     |
| GLB motion  | `GET /download-glb/{job_id}` | `motion.glb`     |

All output endpoints require your API key and are authenticated the same way as every other MVNT API request. Downloading an output does not consume additional credits.

## Formats

<Tabs>
  <Tab title="Preview MP4">
    The preview MP4 is a rendered video of the generated motion — a character performing the dance against a neutral background. It is the fastest way to see your generation result and is ready for immediate human review or display in a product UI.

    **Endpoint**

    ```text theme={null}
    GET /render-mp4/{job_id}
    ```

    **Download example**

    ```bash theme={null}
    curl -L "https://api.mvnt.studio/render-mp4/{job_id}" \
      -H "Authorization: Bearer mvnt_live_xxxxxxxxxxxx" \
      --output preview.mp4
    ```

    **When to use preview MP4**

    * Display motion generation results in your product UI without any 3D rendering on your side
    * QA and visual review before exporting to a motion file
    * Motion-transfer workflows where the MP4 is the input to a downstream model
    * ComfyUI preview nodes that accept video input
    * Partner model cards, demos, and product screenshots

    <Note>
      Use the `-L` flag with curl to follow redirects if the endpoint returns one.
    </Note>
  </Tab>

  <Tab title="BVH">
    BVH (Biovision Hierarchy) is a text-based skeletal animation format that encodes bone hierarchy and keyframe data. It is widely supported by 3D tools and game engines and is the most portable format for motion retargeting work.

    **Endpoint**

    ```text theme={null}
    GET /download-bvh/{job_id}
    ```

    **Download example**

    ```bash theme={null}
    curl -L "https://api.mvnt.studio/download-bvh/{job_id}" \
      -H "Authorization: Bearer mvnt_live_xxxxxxxxxxxx" \
      --output motion.bvh
    ```

    **When to use BVH**

    * Blender: import directly via the BVH importer and retarget to any armature
    * Retargeting pipelines that need raw bone data without an embedded mesh
    * Motion analysis tools that parse keyframe sequences
    * Game engine import workflows (Unity, Godot, and others) that prefer BVH for skeletal animation data

    <Tip>
      BVH is usually the most flexible starting point because the format is human-readable and well-supported across toolchains.
    </Tip>
  </Tab>

  <Tab title="GLB">
    GLB is a binary glTF file that can include mesh, skeleton, materials, and animation in a single portable asset.

    **Endpoint**

    ```text theme={null}
    GET /download-glb/{job_id}
    ```

    **Download example**

    ```bash theme={null}
    curl -L "https://api.mvnt.studio/download-glb/{job_id}" \
      -H "Authorization: Bearer mvnt_live_xxxxxxxxxxxx" \
      --output motion.glb
    ```

    **When to use GLB**

    * Web 3D viewers and browser-based preview tools
    * Pipelines that prefer glTF-compatible assets
    * Workflows that need a mesh-inclusive animated asset
  </Tab>
</Tabs>

## Output path parameter

<ParamField type="string">
  The job ID returned by `POST /generate-motion`. Replace `{job_id}` with that returned value.
</ParamField>

## Choosing a format

| Format      | Best for                                        |
| ----------- | ----------------------------------------------- |
| Preview MP4 | Product UI, QA, demos, ComfyUI                  |
| BVH         | Blender, retargeting, game engines              |
| GLB         | Web 3D, glTF pipelines, mesh-inclusive previews |


# Quickstart
Source: https://mvnt.studio/docs/guides/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.

<Steps>
  <Step title="Get an API key">
    All MVNT API requests require a bearer token. Create one in [MVNT Studio Platform](https://www.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:

    ```bash theme={null}
    export MVNT_API_KEY=mvnt_live_xxxxxxxxxxxx
    ```

    <Warning>
      Never paste your API key directly into source code, workflow files, or public repositories. See [Authentication](/docs/authentication) for security best practices.
    </Warning>
  </Step>

  <Step title="Create a generation">
    Submit a `POST` request to `/generate-motion` with your audio file and generation parameters. The API accepts multipart form data.

    ```bash theme={null}
    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.

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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         |

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Download motion files">
    For 3D pipelines — Blender, Unity, Unreal, or custom retargeting — download the BVH or GLB file.

    <CodeGroup>
      ```bash BVH theme={null}
      curl -L "https://api.mvnt.studio/download-bvh/{job_id}" \
        -H "Authorization: Bearer $MVNT_API_KEY" \
        --output motion.bvh
      ```

      ```bash GLB theme={null}
      curl -L "https://api.mvnt.studio/download-glb/{job_id}" \
        -H "Authorization: Bearer $MVNT_API_KEY" \
        --output motion.glb
      ```
    </CodeGroup>

    <Note>
      Output entitlements depend on your MVNT Studio plan. Check your plan's output access in [MVNT Studio Platform](https://www.mvnt.studio/platform).
    </Note>
  </Step>
</Steps>

## 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](/docs/concepts/outputs) and when to use MP4 vs BVH vs GLB
* Set up a [ComfyUI integration](/docs/integrations/comfyui) to run MVNT inside a visual node workflow


# Use MVNT inside ComfyUI
Source: https://mvnt.studio/docs/integrations/comfyui

Install the comfyui-mvnt custom node package, connect your MVNT API key, and build an audio-to-dance workflow directly inside ComfyUI.

The `comfyui-mvnt` package adds MVNT motion generation as native nodes inside ComfyUI. Once installed, you can wire audio files through a chain of MVNT nodes to produce a 3D preview and a dance video — no separate API client or scripting required. The source repository is at [github.com/mvnt-app/ComfyUI-MVNT](https://github.com/mvnt-app/ComfyUI-MVNT).

## Install the package

Choose whichever method fits your ComfyUI setup.

<Tabs>
  <Tab title="ComfyUI Manager">
    1. Open ComfyUI Manager from the ComfyUI interface.
    2. Search for **MVNT**.
    3. Select `comfyui-mvnt` from the results and click **Install**.
    4. Restart ComfyUI when the install completes.
  </Tab>

  <Tab title="Comfy Registry">
    Run the following command from your terminal, then restart ComfyUI:

    ```bash theme={null}
    comfy node registry-install comfyui-mvnt
    ```
  </Tab>

  <Tab title="Manual">
    Clone the repository into your ComfyUI custom nodes directory, install the Python dependencies, then restart ComfyUI:

    ```bash theme={null}
    cd ComfyUI/custom_nodes
    git clone https://github.com/mvnt-app/ComfyUI-MVNT.git comfyui-mvnt
    cd comfyui-mvnt
    python3 -m pip install -r requirements.txt
    ```
  </Tab>
</Tabs>

## Set up your API key

You can provide your MVNT API key in two ways.

**Environment variable** — set this before launching ComfyUI:

```bash theme={null}
export MVNT_API_KEY=mvnt_live_xxxxxxxxxxxx
```

**Node field** — paste your key directly into the `api_key` field on any MVNT node in the ComfyUI canvas.

You can create and manage API keys in [MVNT Studio Platform](https://www.mvnt.studio/platform).

<Warning>
  Never export or commit a workflow JSON file that contains an API key. ComfyUI workflow exports can embed node field values, including the `api_key` field. If a key appears in a workflow file, logs, or Git history, revoke it immediately in [MVNT Studio Platform](https://www.mvnt.studio/platform) and generate a new one. Use the environment variable approach to keep keys out of workflow files entirely.
</Warning>

## Build a basic workflow

This section shows how to generate 3D dance motion from music using the ComfyUI toolbox. The workflow is a node-based pipeline where each chained node prepares, submits, and previews the audio-to-motion generation result.

<img alt="Complete MVNT ComfyUI workflow overview" />

<Steps>
  <Step title="Load Audio">
    <img alt="Load Audio node in ComfyUI" />

    Add a **Load Audio** node and point it to your input audio file. Currently, only .wav files are supported. This node is a standard ComfyUI node that passes audio data downstream.
  </Step>

  <Step title="MVNT Audio Segment">
    <img alt="MVNT Audio Segment node in ComfyUI" />

    Connect the audio output to an **MVNT Audio Segment** node. This node trims or segments the audio to a range suitable for dance generation.

    * `start_sec`: The segment start time, in seconds.
    * `duration_sec`: The duration of the generated audio segment, in seconds. Defaults to 10 seconds, supports up to 40 seconds, and can be adjusted in 0.1-second increments.
  </Step>

  <Step title="MVNT Generate Dance">
    <img alt="MVNT Generate Dance node in ComfyUI" />

    Wire the segmented audio into an **MVNT Generate Dance** node. This node submits the audio to the MVNT API and returns the generation outputs when the job completes. This node uses the MVNT model to generate 3D motion from music. By default, generation uses the MVNT original character. To generate with a custom character, see the [Character control section](#character-control).

    1. Choose the desired motion style in the `style` field.
    2. Enter your issued API key in `api_key`.
    3. Optional advanced input: set a seed value. The default is `-1`.

    You can now preview or save the generated output.
  </Step>

  <Step title="MVNT Preview Dance 3D">
    <img alt="MVNT Preview Dance 3D node in ComfyUI" />

    Connect the generation output to an **MVNT Preview Dance 3D** node to view the result in the ComfyUI canvas.
  </Step>

  <Step title="MVNT Render Dance Video">
    <img alt="MVNT Render Dance Video node in ComfyUI" />

    Render the generated output as a 2D video. For 2D video control using the kling `video_profile`, see the [Video control section](#video-control).

    * `video_profile`: Specify the rendering settings to use. The default is `Video Reference`.
  </Step>

  <Step title="Save Video">
    <img alt="Save Video node in ComfyUI" />

    Use `filename_prefix`, `format`, and `codec` to configure the file name and rendering information. When generation completes, you will find two output files in your ComfyUI output directory:

    ```text theme={null}
    mvnt_<job_id>.motion.glb
    mvnt_<job_id>.dance.mp4
    ```
  </Step>
</Steps>

## Character Control

Use character control when you want the generated dance to run on your own character instead of the MVNT original character. **MVNT Generate Dance** accepts an optional `character_glb` input. When a compatible character GLB is connected, MVNT generates the motion first, then retargets that motion to the supplied character. The `dance_3d` output becomes the animated custom-character GLB.

<Steps>
  <Step title="Load Image">
    <img alt="Load Image node in ComfyUI" />

    Add a **Load Image** node and select a clear, full-body character image. A front-facing image with the full body visible works best for creating a clean character reference.
  </Step>

  <Step title="MVNT Image-to-T-pose">
    <img alt="MVNT Image to T-Pose node in ComfyUI" />

    Connect the image to an **MVNT Image to T-Pose** node. This node converts the source character image into a front-facing T-pose image that can be used by a compatible character or rigging workflow.
  </Step>

  <Step title="Animate a custom character with Tripo">
    Use Tripo's [model generation workflow](https://docs.comfy.org/tutorials/partner-nodes/tripo/model-generation) to turn the T-pose character image into a rigged GLB that MVNT can animate.

    * Add Tripo's **Image to Model** and **Rig Model** nodes.
  </Step>
</Steps>

## Video Control

Use video control when you want the MVNT model to drive motion in a 2D image-to-video workflow. Generate dance motion with **MVNT Generate Dance**, use the `kling` video profile output as the motion reference, then follow Kling's [Motion Control workflow](https://docs.comfy.org/tutorials/partner-nodes/kling/kling-motion-control) to animate your target image.

* `reference_image`: Upload the image you want to animate.
* `reference_video`: The `kling` video profile output from **MVNT Generate Dance** is used automatically.


# MVNT API: audio-to-dance generation for developers
Source: https://mvnt.studio/docs/introduction

The MVNT API converts audio files into production-ready dance motion. Build web apps, ComfyUI workflows, and 3D pipelines with BVH, GLB, and MP4 outputs.

MVNT is a music-to-dance motion generation API. You send an audio file, MVNT runs a choreography model against it, and you get back a preview MP4 and 3D motion files — all through a single REST interface at `https://api.mvnt.studio`.

## What you can build

* **Web apps and creator tools** — generate and preview choreography in-browser using the preview MP4 output
* **3D pipelines** — import BVH or GLB into Blender, Unreal, Unity, or any retargeting pipeline for production handoff
* **Partner integrations** — connect MVNT through platforms such as ComfyUI workflows with the official MVNT custom node

## API endpoints

Core motion API endpoints include:

| Method   | Path                     | Description                                                          |
| -------- | ------------------------ | -------------------------------------------------------------------- |
| `POST`   | `/generate-motion`       | Submit an audio file and generation parameters to start a motion job |
| `GET`    | `/job/{job_id}`          | Poll the status and result metadata for a job                        |
| `DELETE` | `/job/{job_id}`          | Cancel a queued or running job                                       |
| `GET`    | `/render-mp4/{job_id}`   | Render a BVH motion preview as an MP4                                |
| `GET`    | `/download-bvh/{job_id}` | Download completed motion as a BVH file                              |
| `GET`    | `/download-glb/{job_id}` | Download completed motion as an animated mesh-inclusive GLB          |
| `GET`    | `/styles`                | List available dance styles for generation                           |
| `POST`   | `/analyze-audio`         | Analyze an audio file and recommend dance styles                     |
| `POST`   | `/retarget-tripo-glb`    | Retarget an animated mannequin GLB onto a Tripo T-pose character GLB |

## Base URLs

<CodeGroup>
  ```text Production theme={null}
  https://api.mvnt.studio
  ```
</CodeGroup>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="guides/quickstart">
    Make your first generation and download a motion file in minutes.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/root">
    Machine-readable reference for every endpoint, parameter, and response field.
  </Card>
</CardGroup>