> ## Documentation Index
> Fetch the complete documentation index at: https://mvnt.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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