API Documentation

Reference

FMotion API

Video in, BVH out, over a simple REST API. Submit a job, poll for the result, download the motion data.

Introduction

The FMotion API turns video into motion capture. Send a video, get back a full-body 3D skeleton with hands and fingers as industry-standard BVH. Jobs run asynchronously: you submit a video, then poll for the result.

Base URL: https://fmotion.ai. All endpoints accept and return JSON.

Authentication

Create an API key in Settings → API. Pass it as a Bearer token on every request. Keys are shown once at creation; store them securely.

Authorization: Bearer fm_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keep keys server-side. Anyone with a key can spend your credits. Revoke a leaked key from the API tab; it stops working immediately.

Pricing & credits

Usage is metered per second of input video. One credit covers 15 seconds of video by default, so a 10-second clip costs about 0.67 credits. Credits are deducted when a job is accepted and refunded automatically if the job fails.

Buy credits in Billing, or enable auto-reload in the API tab to top up automatically when the balance runs low. Metered (postpaid) billing through Stripe is rolling out for high-volume users.

Submit a job

POST/api/v1/jobs

Submit a publicly reachable video URL. Returns immediately with a job id; processing continues in the background.

Request body

FieldTypeDescription

video_urlstringRequired. Publicly reachable URL of the video to process.

namestringOptional. A label for the job.

filenamestringOptional. Original filename (helps the decoder).

curl -X POST https://fmotion.ai/api/v1/jobs \
  -H "Authorization: Bearer $FMOTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://example.com/clip.mp4"}'

Response (202)

{
  "id": "b4af88b8-...",
  "status": "queued",
  "seconds_billed": 8.4,
  "credits_charged": 0.6,
  "poll_url": "/api/v1/jobs/b4af88b8-..."
}

Check job status

GET/api/v1/jobs/{id}

Poll this until status is completed or failed. When completed, bvh_url holds the result. Poll every few seconds.

curl https://fmotion.ai/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $FMOTION_KEY"

Response

{
  "id": "b4af88b8-...",
  "status": "completed",
  "progress": 100,
  "bvh_url": "https://.../result.bvh",
  "characters": null,
  "processing_time": 19.2,
  "error": null
}

FieldTypeDescription

statusstringqueued | processing | completed | failed

progressnumber0–100 percent complete.

bvh_urlstringDownload URL for the BVH (when completed).

charactersarrayPer-person BVH files for multi-person clips.

errorstringFailure reason when status is failed (credits auto-refunded).

Errors

FieldTypeDescription

400clientMissing or invalid video_url.

401authMissing, malformed, revoked or unknown API key.

402billingNo credits and no card on file.

413clientVideo exceeds the 200MB limit.

502serverUpstream processing could not accept the job (credits refunded).

Limits

Maximum video size: 200 MB per request.
Jobs are processed asynchronously; typical turnaround is seconds to a few minutes.
Credits are charged on accept and refunded automatically on failure.