Motions - Viggle API

A Motion is a reusable driving action from a video, or a 3D animation generated from a text prompt. It is not a background scene. Use a Motion’s mot_... ID as motion_id when creating a Render. All endpoints on this page require Authorization: Bearer YOUR_API_KEY. Field-by-field detail lives on the split reference pages: Create from Video, Create from Text, Import, List, Get, Delete, Export.

Create a Motion from video

POST /v1/motions The request body carries one of two shapes, by Content-Type. multipart/form-data creates a Motion from a driving video:

Field	Type	Required	Default	Description
`motion_video`	file	One of	—	Driving video uploaded as a file.
`motion_video_url`	string	One of	—	Publicly reachable URL for the driving video.
`name`	string	No	`""`	Optional human-readable label.
`type`	string	No	`render`	`render` (no charge), `glb` (5 credits per second of source video, rounded up), or `all` (billed for both).

For type=glb or all, the request also accepts enable_smoothing, target_fps, and task_id. Reusable Motion thumbnails are generated internally from the source video. See Create Motion (from Video) for exact behavior.

curl -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "[email protected]" \
  -F "name=Dance loop"

Create a Motion from text

The same POST /v1/motions endpoint accepts application/json to generate a Motion from a text prompt. This request is always type: glb and replaces the old, now-removed POST /v1/animations/generate. It costs a flat 10 credits, independent of duration_seconds — a different rate from the per-second glb extraction above:

Field	Type	Required	Default	Description
`text`	string	Yes	—	Motion prompt, 1–400 characters.
`duration_seconds`	number	No	`5`	Duration in `[3, 60]`, rounded to the nearest frame at 30 fps.
`guidance_scale`	number	No	`5`	Classifier-free guidance scale in `[0, 30]`.
`smooth`	boolean	No	`true`	Apply motion smoothing.
`name`	string	No	`""`	Optional Motion label.
`task_id`	string	No	—	Client-supplied idempotency key.

curl -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"a person doing a cartwheel","duration_seconds":5}'

Import a Motion template

POST /v1/motions/import Imports a Motion from a Viggle template. Send a JSON request body. Costs 1 credit per second of the source template’s duration, with a minimum of 1 credit.

Field	Type	Required	Default	Description
`template_id`	string	One of	—	Template ID copied from Viggle. This is the preferred field.
`template_uuid`	string	One of	—	Backward-compatible alias for `template_id`.
`name`	string	No	`Imported:` + first 8 chars of the template ID	Optional label for the imported Motion.

curl -X POST "https://apis.viggle.ai/v1/motions/import" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"}'

template_id takes precedence when both template fields are sent. Send only the preferred template_id in new integrations.

Get a Motion

GET /v1/motions/{motion_id}

curl "https://apis.viggle.ai/v1/motions/mot_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

List Motions

GET /v1/motions Returns the most recently created active Motions for the current account, newest first, capped at 100 with no cursor.

curl "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

Delete a Motion

DELETE /v1/motions/{motion_id}

curl -X DELETE "https://apis.viggle.ai/v1/motions/mot_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

Export a Motion’s 3D animation

GET /v1/motions/{motion_id}/export Only meaningful for a glb/all Motion, or one generated from text. download_type is the skeleton itself — mixamo or metahuman — both pre-generated, so either can be requested without regenerating. There is no fbx.

curl "https://apis.viggle.ai/v1/motions/mot_456def/export?download_type=mixamo" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

Motion response fields

All Motion endpoints return the same resource shape as Characters, plus a glb sub-object: id, status, name, progress, capabilities, type, glb, created_at, completed_at, and error. glb is {status, skeletons, error} when type requested an extraction/generation, otherwise null; skeletons is empty until ready, then [mixamo, metahuman]. A Motion ID looks like mot_550e8400-e29b-41d4-a716-446655440000; preserve it exactly.

Endpoint response rules

Endpoint	Success status	Response	Parameters
`POST /v1/motions` (multipart)	`200`	Motion object	One video source; optional 3D extraction controls depend on `type`.
`POST /v1/motions` (JSON)	`200`	Motion object (always `type: glb`)	`text` required; `duration_seconds`, `guidance_scale`, `smooth`, `name` optional.
`POST /v1/motions/import`	`200`	Motion object	One of `template_id` or `template_uuid` is required; `name` optional.
`GET /v1/motions`	`200`	`{ "data": [Motion] }`	No parameters.
`GET /v1/motions/{motion_id}`	`200`	Motion object	`motion_id` is required.
`DELETE /v1/motions/{motion_id}`	`200`	`{ "status": "deleted" }`	`motion_id` is required.
`GET /v1/motions/{motion_id}/export`	`200`	MotionExport object	`motion_id` required; `download_type` optional.

​Create a Motion from video

​Create a Motion from text

​Import a Motion template

​Get a Motion

​List Motions

​Delete a Motion

​Export a Motion’s 3D animation

​Motion response fields

​Endpoint response rules

Create a Motion from video

Create a Motion from text

Import a Motion template

Get a Motion

List Motions

Delete a Motion

Export a Motion’s 3D animation

Motion response fields

Endpoint response rules