> ## 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.

# API quickstart

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

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](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](guides/authentication) for security best practices.

**2. List dance styles**

Call `GET /styles` to list available style names. Use one of the returned `name` values as the `style` field when you create a generation.

```bash theme={null}
curl "https://api.mvnt.studio/v1/styles" \
  -H "Authorization: Bearer $MVNT_API_KEY"
```

**3. Create a generation**

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

```bash theme={null}
curl -X POST "https://api.mvnt.studio/v1/generations" \
  -H "Authorization: Bearer $MVNT_API_KEY" \
  -F "audio=@song.wav" \
  -F "style=All" \
  -F "trim_start=0" \
  -F "trim_end=20" \
  -F "temperature=1.0"
```

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

```json theme={null}
{
  "id": "{id}",
  "status": "queued",
  "message": "Motion generation started (model=v11_gender, style=All, seed=-1)",
  "trim_start": 0.0,
  "trim_end": 20.0,
  "mode": "standard"
}
```

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

**4. Poll for completion**

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

```bash theme={null}
curl "https://api.mvnt.studio/v1/generations/{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 |
| `processing` | 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.

**5. 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/v1/generations/{id}/output?format=mp4" \
  -H "Authorization: Bearer $MVNT_API_KEY" \
  --output preview.mp4
```

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

> [!NOTE]
>
> Optional query parameters: `preset=standard` (1920×1080) or `preset=shorts` (1080×1920), and `camera_mode=tracking`, `dynamic`, or `idol`. MP4 rendering can take a while — use a generous client timeout.

**6. Download the GLB motion file**

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

```bash theme={null}
curl -L "https://api.mvnt.studio/v1/generations/{id}/output?format=glb" \
  -H "Authorization: Bearer $MVNT_API_KEY" \
  --output motion.glb
```

> [!NOTE]
>
> Output entitlements depend on your MVNT Studio plan. Check your plan's output access in [MVNT Studio Platform](https://www.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 /v1/generations`
* Learn about [output formats](guides/outputs) and when to use MP4 vs GLB
* Set up a [ComfyUI integration](https://mvnt.studio/docs/integrations/comfyui.md) to run MVNT inside a visual node workflow


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.