Motions

A Motion is a reusable driving action from a video. It is not a background scene. Use a Motion’s mot_... ID as motion_id when creating a Render. All endpoints in this page require Authorization: Bearer YOUR_API_KEY.

Create a Motion

POST /v1/motions Creates an asynchronous Motion. Send multipart/form-data.

Field	Type	Required	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.

Provide exactly one Motion source: motion_video or motion_video_url. Use a valid driving video that the service can read. For URL input, the URL must be reachable by Viggle’s servers for the duration of the request.

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

Example: create from a URL

curl -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "motion_video_url=https://example.com/dance.mp4" \
  -F "name=Remote dance"

Import a Motion template

POST /v1/motions/import Imports a Motion from a Viggle template. Send a JSON request body.

Field	Type	Required	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	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"}'

The response is a Motion resource. Poll it by ID until it is ready.

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}

Path parameter	Type	Required	Description
`motion_id`	string	Yes	Full Motion ID, for example `mot_550e8400-e29b-41d4-a716-446655440000`.

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

List Motions

GET /v1/motions This endpoint currently has no query parameters and returns all Motions for the current account.

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

The response uses the same { "data": [Resource, ...] } shape as List Characters.

{
  "data": [
    {
      "id": "mot_456def",
      "status": "ready",
      "name": "Dance loop",
      "progress": 100,
      "capabilities": ["video_render"],
      "created_at": "2026-07-17T10:00:00Z",
      "completed_at": "2026-07-17T10:00:20Z",
      "error": null
    }
  ]
}

Delete a Motion

DELETE /v1/motions/{motion_id}

Path parameter	Type	Required	Description
`motion_id`	string	Yes	Full Motion ID, for example `mot_550e8400-e29b-41d4-a716-446655440000`.

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

Motion response fields

All Motion endpoints return the same resource fields as Characters: id, status, name, progress, capabilities, created_at, completed_at, and error. 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`	`200`	Motion object	One required video source; `name` is optional.
`POST /v1/motions/import`	`200`	Motion object	One of `template_id` or `template_uuid` is required; `name` is 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 Started

Guides

Advanced

Reference

Create a Motion

Example: create from a URL

Import a Motion template

Get a Motion

List Motions

Delete a Motion

Motion response fields

Endpoint response rules

​Create a Motion

​Example: create from a URL

​Import a Motion template

​Get a Motion

​List Motions

​Delete a Motion

​Motion response fields

​Endpoint response rules

Create a Motion

Example: create from a URL

Import a Motion template

Get a Motion

List Motions

Delete a Motion

Motion response fields

Endpoint response rules