Quick Start: Motion 3D

Motion 3D extracts a 3D skeletal animation from a driving video — this is the type=glb path of POST /v1/motions. When it’s ready, request the glb with ?download_type=mixamo (or metahuman) from Export 3D Motion. The exported GLB works with Mixamo, MetaHuman, and other Unity-compatible animation workflows. See the Motion Quickstart for the render-ready 2D path instead, or Text-to-Motion to generate a 3D animation from a text prompt with no source video. Set VIGGLE_API_KEY and run the example below as-is — it uses a Viggle-hosted sample video, so you don’t need to prepare your own motion video first.

What you need

An API key from the Viggle Dashboard, exported as VIGGLE_API_KEY

The examples below reference a placeholder sample asset URL (https://assets.viggle.ai/samples/motion.mp4). Swap in your own motion_video/motion_video_url, or Viggle’s published sample asset once available.

Create, poll, and export the Motion

#!/usr/bin/env bash
set -euo pipefail

response=$(curl -s -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "motion_video_url=https://assets.viggle.ai/samples/motion.mp4" \
  -F "type=glb")
motion_id=$(echo "$response" | jq -r '.id')

for _ in $(seq 1 60); do
  motion=$(curl -s "https://apis.viggle.ai/v1/motions/$motion_id" \
    -H "Authorization: Bearer $VIGGLE_API_KEY")
  status=$(echo "$motion" | jq -r '.status')

  case "$status" in
    ready)
      exported=$(curl -s "https://apis.viggle.ai/v1/motions/$motion_id/export?download_type=mixamo" \
        -H "Authorization: Bearer $VIGGLE_API_KEY")
      echo "$exported" | jq -r '.glb_url'
      exit 0
      ;;
    failed)
      echo "Motion failed: $(echo "$motion" | jq -c '.error')" >&2
      exit 1
      ;;
  esac
  sleep 5
done

echo "Timed out waiting for motion $motion_id" >&2
exit 1

const baseUrl = "https://apis.viggle.ai/v1";
const headers = { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` };

async function createMotion() {
  const form = new FormData();
  form.append("motion_video_url", "https://assets.viggle.ai/samples/motion.mp4");
  form.append("type", "glb");

  const response = await fetch(`${baseUrl}/motions`, {
    method: "POST",
    headers,
    body: form,
  });
  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
  }
  return response.json();
}

async function waitForMotion(id) {
  for (let attempt = 0; attempt < 60; attempt++) {
    const response = await fetch(`${baseUrl}/motions/${id}`, { headers });
    if (!response.ok) {
      const body = await response.json().catch(() => ({}));
      throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
    }
    const motion = await response.json();
    if (["ready", "failed"].includes(motion.status)) return motion;
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  throw new Error(`Timed out waiting for motion ${id}`);
}

const created = await createMotion();
const motion = await waitForMotion(created.id);

if (motion.status !== "ready") {
  throw new Error(`Motion failed: ${JSON.stringify(motion.error)}`);
}

const exportResponse = await fetch(
  `${baseUrl}/motions/${motion.id}/export?download_type=mixamo`,
  { headers },
);
if (!exportResponse.ok) {
  const body = await exportResponse.json().catch(() => ({}));
  throw new Error(`HTTP ${exportResponse.status}: ${JSON.stringify(body.error ?? body)}`);
}
const exported = await exportResponse.json();
console.log(exported.glb_url);

import os
import time
import requests

base_url = "https://apis.viggle.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}

response = requests.post(
    f"{base_url}/motions",
    headers=headers,
    files={"motion_video_url": (None, "https://assets.viggle.ai/samples/motion.mp4")},
    data={"type": "glb"},
)
response.raise_for_status()
motion = response.json()

for _ in range(60):
    if motion["status"] in {"ready", "failed"}:
        break
    time.sleep(5)
    response = requests.get(f"{base_url}/motions/{motion['id']}", headers=headers)
    response.raise_for_status()
    motion = response.json()
else:
    raise TimeoutError(f"Timed out waiting for motion {motion['id']}")

if motion["status"] != "ready":
    error = motion.get("error") or {}
    raise RuntimeError(f"failed: {error.get('code')} {error.get('message')}")

exported = requests.get(
    f"{base_url}/motions/{motion['id']}/export",
    params={"download_type": "mixamo"},
    headers=headers,
)
exported.raise_for_status()
print(exported.json()["glb_url"])

Response

{
  "id": "mot_123abc",
  "status": "queued",
  "name": "",
  "progress": 0,
  "capabilities": [],
  "created_at": "2026-07-21T10:00:00+00:00",
  "completed_at": null,
  "error": null,
  "type": "glb",
  "vsplat": null,
  "glb": null
}

Poll GET /v1/motions/{motion_id} every five seconds. When status is ready, request GET /v1/motions/{motion_id}/export?download_type=mixamo; glb_url then points to the generated animation — it’s a signed link, valid for 1 hour and re-signed on every call. Request download_type=metahuman on the same motion_id for the other rig — both skeletons are pre-generated, so this never waits on new work. There is no fbx output. See Pricing and retention for how the glb extraction is billed by source-video duration.

Create Motion (from Video)

See every request and response field.

Get Started

Guides

Production

Quick Start: Motion 3D

What you need

Create, poll, and export the Motion

Response

Create Motion (from Video)

​What you need

​Create, poll, and export the Motion

​Response

Create Motion (from Video)

What you need

Create, poll, and export the Motion

Response