> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Motion (from Video)
> Create a reusable Motion from a driving video.
Send `multipart/form-data` with a driving video uploaded as a file or supplied by URL. `type` selects what gets produced: `render` (default) creates only the render-ready 2D Motion, `glb` creates only the 3D skeletal animation, and `all` produces both and is billed for both.
This uses the same `POST /v1/motions` endpoint as [Create Motion (from Text)](/v1/api-reference/motions/create-from-text), but the content type and request fields are different.
**Pricing** (1 credit = \$0.01): `type=render` has **no separate preprocessing charge**. `type=glb` costs **5 credits per second** of source video, rounded up. `type=all` is billed for both. See [Pricing and retention](/v1/pricing).
## Request parameters
Send `multipart/form-data`.
| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `motion_video` | file | One of | — | Driving video uploaded directly as the motion source. Supply exactly one source field; visible body movement is extracted for reuse. |
| `motion_video_url` | string | One of | — | Publicly reachable HTTP(S) URL of the driving video. Supply this instead of `motion_video` and keep it accessible while ingestion starts. |
| `video_url` | string | One of | — | Backward-compatible alias for `motion_video_url`. Do not send both URL fields. |
| `name` | string | No | `""` | Optional label for `render` or `all`. A `glb`-only Motion currently returns an empty name. |
| `type` | string | No | `render` | Outputs to create: `render` produces the reusable 2D Motion (**no charge**), `glb` produces only the 3D animation (**5 credits per second of source video, rounded up**), and `all` produces both and is billed for both. |
Provide exactly one of `motion_video`, `motion_video_url`, or `video_url`. Prefer `motion_video_url` in new integrations.
The following compatibility fields apply to the reusable 2D Motion created by `type=render` or `all`; they have no effect on a `glb`-only request.
| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `model` | string | No | Service default | 2D preprocessing model: `V3`, `v3`, `V3_Preview`, `V4`, `v4`, `V4_Preview`, or `V4_BaseSG`. This is unrelated to 3D GLB extraction. |
| `thumbnail_path` | string | No | Generated internally | Existing thumbnail URI/path for the reusable Motion. Normally omit it and let the service generate the thumbnail. |
| `thumbnail_url` | string | No | Generated internally | Multipart-only backward-compatible alias for `thumbnail_path`. Do not send both fields. |
The following fields apply only when `type` is `glb` or `all`.
| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `enable_smoothing` | boolean | No | `false` | Whether to smooth extracted joint motion to reduce frame-to-frame jitter. Applies only to `type=glb` or `all` and may slightly soften abrupt movements. |
| `target_fps` | number | No | `25` | Target extraction and GLB timeline frame rate. Must be greater than `0`; omit to use the extraction service's 25 FPS default. |
| `smooth_velocity_threshold` | number | No | `0.12` | Non-negative velocity threshold used by temporal smoothing. Applies only when `enable_smoothing=true`. |
| `apply_std_joints` | boolean | No | `true` | Whether dynamic extraction applies standard-joint normalization. |
| `task_id` | string | No | — | Caller-generated idempotency ID for `type=glb`. Use a unique, stable value when retrying the same work; for `type=all`, the service keys the companion extraction with the created Motion ID. |
Worker payload fields such as extraction/output paths, templates, character
PKLs, and tracking masks remain service-managed and are not accepted as
public request parameters.
## Response parameters
Returns `200 OK` with a Motion object.
| Field | Type | Always present | Description |
| - | - | :-: | - |
| `id` | string | Yes | Public Motion ID beginning with `mot_`. Store it exactly as returned. |
| `status` | string | Yes | Normally `queued`; terminal values are `ready` and `failed`. |
| `name` | string | Yes | Supplied label, or an empty string. |
| `progress` | integer or null | Yes | Progress from 0 to 100 when available. |
| `capabilities` | string\[] | Yes | Empty until ready; ready render-capable Motions include `video_render`. |
| `created_at` / `completed_at` | string or null | Yes | ISO 8601 timestamps. |
| `error` | object or null | Yes | Structured failure details when status is `failed`. |
| `type` | string | Yes | Echoes the requested `type`: `render`, `glb`, or `all`. |
| `glb` | object or null | Yes | `null` for a `render`-only Motion. Otherwise `{status, skeletons, error}` — `skeletons` is empty until ready, then `[mixamo, metahuman]` (both variants are always generated together). |
| `vsplat` | null | Yes | Always `null` for a Motion. |
```json theme={null}
{
"id": "mot_550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"name": "Dance loop",
"progress": 0,
"capabilities": [],
"created_at": "2026-07-21T10:00:00+00:00",
"completed_at": null,
"error": null,
"type": "render",
"vsplat": null,
"glb": null
}
```
## Examples
```go Go theme={null}
file, _ := os.Open("dance.mp4"); defer file.Close()
body := &bytes.Buffer{}; writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("motion_video", "dance.mp4"); io.Copy(part, file)
writer.WriteField("name", "Dance loop"); writer.Close()
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/motions", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type", writer.FormDataContentType())
resp, err := http.DefaultClient.Do(req); if err != nil { panic(err) }; defer resp.Body.Close()
```
```javascript JavaScript theme={null}
const form = new FormData(); form.append("motion_video", videoFile); form.append("name", "Dance loop");
const response = await fetch("https://apis.viggle.ai/v1/motions", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}, body:form});
const motion = await response.json();
```
```python Python theme={null}
import os, requests
with open("dance.mp4", "rb") as video:
response = requests.post("https://apis.viggle.ai/v1/motions", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}, files={"motion_video": video}, data={"name": "Dance loop"})
response.raise_for_status(); motion = response.json()
```
```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions" -H "Authorization: Bearer $VIGGLE_API_KEY" -F "motion_video=@dance.mp4" -F "name=Dance loop"
```
To also extract a 3D glb animation, add `type=glb` (or `all` to keep the render too):
```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions" \
-H "Authorization: Bearer $VIGGLE_API_KEY" \
-F "motion_video=@dance.mp4" \
-F "type=all" \
-F "enable_smoothing=true" \
-F "smooth_velocity_threshold=0.12" \
-F "apply_std_joints=true" \
-F "target_fps=25"
```
## Next step
Use [Get Motion](/v1/api-reference/motions/get) to poll the ID, then [Export 3D Motion (for 3D/game engines)](/v1/api-reference/motions/export) once its `glb.status` is `ready`.
Generate a 3D Motion from a text prompt using the same endpoint with JSON.
## OpenAPI
````yaml openapi.yaml POST /v1/motions
openapi: 3.0.3
info:
title: Viggle API
description: Generate AI-powered character animation videos
version: 2.0.0
contact:
name: Viggle Support
url: https://viggle.ai
servers:
- url: https://apis.viggle.ai
description: Production server
security:
- bearerAuth: []
tags:
- name: Renders
description: Prepare inputs, create renders, observe progress, and retrieve results.
- name: Credits
description: Read the credit balance available to the calling principal.
- name: Characters
description: |
Create, list, inspect, and delete reusable character assets. `type`
selects whether creation also extracts a 3D vsplat; export its
download URL separately once ready.
- name: Motions
description: |
Create, list, inspect, and delete reusable motion assets, and import one
from an official motion template. `type` selects whether creation also
extracts or generates a 3D animation; export its download URL
separately once ready.
- name: Videos
description: >
Generate a MiniMax H3 video from text, frames, or references (`vid_`
prefix) or a character-animation video from a character image and/or
driving video
(`anim_` prefix), and read the unified view over every video the
caller owns — H3 generations, character-animation generations, and
character+motion Renders (`render_` prefix) — merged into one
resource.
- name: Images
description: |
Viggle Image — generate 1–6 PNG images from a text prompt with the
`qwen` model, optionally guided by up to 8 reference images
(`img_` prefix), and retrieve them by ID.
paths:
/v1/motions:
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
post:
tags:
- Motions
summary: Create a reusable motion asset
description: |
The request body carries one of two shapes and the `Content-Type`
selects between them.
`multipart/form-data` supplies the source video either as an
uploaded file or as `motion_video_url`. `type` selects what gets
produced from it: `render` (default, unchanged from before `type`
existed) is the render-ready 2D motion and has no separate
preprocessing charge; `glb` additionally extracts a 3D skeletal
animation and costs 5 credits per second of source video, rounded
up; `all` produces both and is billed for both.
`application/json` generates the 3D animation from a `text` prompt
instead of a video — there is no render-ready 2D counterpart for a
text-generated motion, so this shape always produces `type: glb`
only. This replaces the old `POST /v1/animations/generate`, and
costs a flat 10 credits regardless of `duration_seconds`.
Either shape lands on the same resource: poll
`GET /v1/motions/{motion_id}` until `status` is `ready`, then fetch
the glb's download URL, if any, from
`GET /v1/motions/{motion_id}/export`.
operationId: createMotion
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateMotionForm'
application/json:
schema:
$ref: '#/components/schemas/CreateMotionRequest'
responses:
'200':
description: Motion queued.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
'400':
$ref: '#/components/responses/ResourceBadRequest'
'401':
$ref: '#/components/responses/ResourceUnauthorized'
'402':
$ref: '#/components/responses/ResourcePaymentRequired'
'404':
$ref: '#/components/responses/ResourceNotFound'
'409':
$ref: '#/components/responses/ResourceConflict'
'500':
$ref: '#/components/responses/ResourceInternalServerError'
'503':
$ref: '#/components/responses/ResourceServiceUnavailable'
components:
parameters:
RequestId:
name: X-Request-Id
in: header
required: false
description: >-
Optional caller-supplied correlation ID, up to 128 characters. The
service returns the effective value in the response header for tracing
and support.
schema:
type: string
minLength: 1
maxLength: 128
SourceChannel:
name: X-Viggle-Source
in: header
required: false
description: >-
Optional source-channel label, up to 128 characters, used to attribute
traffic to an SDK, integration, product surface, or internal workflow.
schema:
type: string
minLength: 1
maxLength: 128
schemas:
CreateMotionForm:
description: |
Supply the source video as exactly one of `motion_video`,
`motion_video_url`, or the backward-compatible `video_url` alias.
`type` selects what gets produced from it — see
`createMotion`. The fields below `type` apply only when it is
`glb` or `all`.
This is the complete public contract; staged paths, output locations,
extraction templates, character PKLs, joint configuration, and
tracking masks are service-managed.
type: object
properties:
motion_video:
type: string
format: binary
description: >-
Driving video uploaded directly. Supply exactly one of
`motion_video` or `motion_video_url`.
motion_video_url:
type: string
format: uri
description: >-
Publicly reachable URL of the driving video. Supply this instead of
`motion_video`, and keep it accessible during ingestion.
video_url:
type: string
format: uri
deprecated: true
description: >-
Backward-compatible alias for `motion_video_url`. Do not send both
URL fields.
name:
description: |
Optional label for `render` or `all`. A `glb`-only Motion
currently returns an empty name.
type: string
default: ''
model:
type: string
enum:
- V3
- v3
- V3_Preview
- V4
- v4
- V4_Preview
- V4_BaseSG
description: >-
Optional 2D preprocessing model used by `type=render` or `all`. It
has no effect on a `glb`-only request. Omit to use the service
default.
thumbnail_path:
type: string
description: >-
Optional existing thumbnail URI/path for the reusable 2D Motion
created by `type=render` or `all`. It has no effect on `type=glb`.
thumbnail_url:
type: string
format: uri
deprecated: true
description: >-
Multipart-only backward-compatible alias for `thumbnail_path`. Do
not send both fields.
type:
type: string
description: >-
Outputs to produce: `render` for the reusable 2D Motion (no separate
preprocessing charge), `glb` for only the 3D animation (5 credits
per second of source video, rounded up), or `all` for both.
enum:
- render
- glb
- all
default: render
enable_smoothing:
type: boolean
description: >-
Whether to apply motion smoothing during 3D extraction. Applies only
to `type=glb` or `all` and may reduce frame-to-frame jitter.
default: false
target_fps:
description: |
Target extraction and GLB timeline frame rate. Omit to use the
extraction service's 25 FPS default. The value must be greater
than zero and applies only to `type=glb` or `all`.
type: number
minimum: 0
exclusiveMinimum: true
default: 25
smooth_velocity_threshold:
type: number
minimum: 0
default: 0.12
description: >-
Velocity threshold used by temporal smoothing. Applies only when
`enable_smoothing=true`.
apply_std_joints:
type: boolean
default: true
description: Whether dynamic extraction applies standard-joint normalization.
task_id:
description: |
Client-supplied idempotency key for `type=glb`. For `type=all`,
the service keys the companion extraction with the Motion ID.
Use a unique, stable non-empty value when retrying the same
creation request; reusing it for separate work causes a conflict.
type: string
minLength: 1
CreateMotionRequest:
description: |
Text-to-motion generation — the `application/json` shape of
`POST /v1/motions`. Always yields `type: glb` on the resulting
`Asset`. Formerly `GenerateMotionRequest`, the body of the
now-removed `POST /v1/animations/generate`. Costs a flat 10 credits,
independent of `duration_seconds`.
type: object
additionalProperties: false
required:
- text
properties:
text:
type: string
description: >-
Natural-language description of the desired movement. Be specific
about actions, direction, pacing, and body parts; maximum 400
characters.
minLength: 1
maxLength: 400
duration_seconds:
description: |
Requested animation length in seconds. It is rounded to the
nearest frame at 30 FPS; values outside [3, 60] are rejected with
HTTP 400 rather than clamped. Defaults to 5 seconds.
type: number
minimum: 3
maximum: 60
default: 5
guidance_scale:
description: >-
Controls how strongly generation follows the text prompt. Values
must be between 0 and 30; out-of-range input is rejected with HTTP
400 rather than clamped. Defaults to 5.
type: number
minimum: 0
maximum: 30
default: 5
smooth:
type: boolean
description: >-
Whether to smooth the generated animation to reduce abrupt
frame-to-frame joint changes.
default: true
name:
type: string
description: >-
Optional display name for the generated Motion; defaults to an empty
string.
default: ''
task_id:
type: string
description: >-
Optional caller-generated idempotency identifier for safe retries.
Reusing an existing ID for another task returns a conflict.
minLength: 1
Asset:
description: >
A character or motion asset. Both resources share one wire shape.
`progress` is null in list responses. `error` is always null, including
on a `failed` asset: read `status` to detect failure.
`type` reflects what was requested at creation. For characters it is
`render`, `vsplat`, or `all`; for motions it is `render`, `glb`,
or `all`. Assets created before `type` existed report `render`.
`vsplat` and `glb` carry that extraction's own status — never
download URLs, which come from `GET
/v1/characters/{character_id}/export`
or `GET /v1/motions/{motion_id}/export` instead — and are null unless
`type` requested that extraction. On an `all` asset, the top-level
`status` only reaches `ready` once both the 2D render and the 3D
extraction have; if either fails, the top-level `status` is `failed`
while the sub-object's own `status` still shows which one it was.
type: object
additionalProperties: false
required:
- id
- status
- name
- progress
- capabilities
- created_at
- completed_at
- error
- type
- vsplat
- glb
properties:
id:
type: string
description: >-
Public asset identifier. Character IDs normally begin with `char_`;
Motion IDs normally begin with `mot_`.
minLength: 1
status:
description: >-
Overall lifecycle of the asset. Use an asset for rendering or export
only after the required capability becomes `ready`.
allOf:
- $ref: '#/components/schemas/ResourceStatus'
name:
type: string
description: >-
Display name supplied at creation or derived during import; it may
be empty when a workflow does not accept a name.
progress:
type: integer
description: >-
Best-effort processing percentage from 0 through 100 on detail
responses; null in list responses or when unavailable.
nullable: true
minimum: 0
maximum: 100
capabilities:
description: |
What the asset can be used for. `video_render` appears once the
asset is ready.
type: array
items:
type: string
created_at:
description: >-
ISO 8601 timestamp with a UTC offset, for example
`2026-07-31T09:15:22+00:00`.
type: string
nullable: true
completed_at:
type: string
description: >-
ISO 8601 timestamp with a UTC offset when all requested processing
reached a terminal state; null while work is active.
nullable: true
error:
type: object
description: >-
Reserved top-level failure detail. It is currently always null;
detect failure from `status` and inspect extraction sub-objects when
applicable.
nullable: true
allOf:
- $ref: '#/components/schemas/ResourceError'
type:
type: string
description: >-
Work requested when the asset was created. `render` produces the 2D
render-ready asset, `vsplat`/`glb` requests 3D output, and `all`
requests both supported outputs.
enum:
- render
- vsplat
- glb
- all
default: render
vsplat:
description: |
Character vsplat extraction status. Null for motions, and for
characters whose `type` is `render`. The request parameters
(`model_precision`, etc.) submitted at creation are not echoed
back here — this is status only.
nullable: true
type: object
additionalProperties: false
required:
- status
- error
properties:
status:
description: >-
Lifecycle of the character's vsplat extraction, independent of
the top-level asset status.
allOf:
- $ref: '#/components/schemas/ResourceStatus'
error:
type: object
description: >-
Structured vsplat extraction failure when its status is
`failed`; otherwise null.
nullable: true
allOf:
- $ref: '#/components/schemas/ResourceError'
glb:
description: |
Motion 3D animation extraction/generation status. Null for
characters, and for motions whose `type` is `render`.
nullable: true
type: object
additionalProperties: false
required:
- status
- skeletons
- error
properties:
status:
description: >-
Lifecycle of the motion's 3D animation extraction or generation,
independent of the top-level asset status.
allOf:
- $ref: '#/components/schemas/ResourceStatus'
skeletons:
description: |
Skeleton variants ready to export via
`GET /v1/motions/{motion_id}/export?download_type=`.
Empty until `status` is `ready`; both variants are
generated up front, so this is either empty or
`[mixamo, metahuman]`.
type: array
items:
type: string
enum:
- mixamo
- metahuman
error:
type: object
description: >-
Structured 3D animation failure when its status is `failed`;
otherwise null.
nullable: true
allOf:
- $ref: '#/components/schemas/ResourceError'
ResourceStatus:
description: |
The public lifecycle shared by every asynchronous resource. It carries
the same values as `RenderStatus`.
type: string
enum:
- queued
- processing
- ready
- failed
- cancelled
ResourceError:
description: |
The failure attached to an asynchronous resource. `code` is a stable,
lower_snake_case string and deliberately not an enum: the extraction
and render workers own this vocabulary and add to it over time, and a
failure with no published mapping surfaces as `processing_failed`.
Published codes: `worker_stopped`, `motion_model_mismatch`,
`image_required`, `motion_video_required`, `unsupported_video_format`,
`video_too_long`, `video_too_large`, `video_resolution_too_high`,
`video_unreadable`, `invalid_background_mode`,
`video_dimensions_must_be_even`, `result_expired`,
`video_inaccessible`, `no_humans_detected`, `all_workers_busy`,
`task_failed`, `unexpected_error`, `processing_failed`.
type: object
additionalProperties: false
required:
- code
- message
- request_id
properties:
code:
type: string
description: >-
Stable, lower_snake_case asynchronous failure code. The vocabulary
is open, so clients must tolerate new values.
minLength: 1
message:
type: string
description: Human-readable explanation of the asynchronous processing failure.
request_id:
type: string
description: >-
Correlation identifier from the worker or originating request; null
when unavailable.
nullable: true
ResourceErrorResponse:
type: object
additionalProperties: false
required:
- error
properties:
error:
description: Top-level synchronous resource-operation error payload.
allOf:
- $ref: '#/components/schemas/ResourceHttpError'
ResourceHttpError:
description: |
The failure envelope of a synchronous resource request. Every code is
produced by one mapping in the API service, so the set is closed; a
failure with no published mapping surfaces as `processing_failed`.
The asynchronous `error` object on a resource carries the wider,
deliberately open vocabulary of `ResourceError` instead.
type: object
additionalProperties: false
required:
- code
- message
- request_id
properties:
code:
type: string
description: >-
Closed, lower_snake_case error code for a synchronous resource
request; use it for programmatic handling.
enum:
- authentication_required
- invalid_api_key
- insufficient_credits
- invalid_request
- motion_not_ready
- character_not_found
- motion_not_found
- not_found
- id_already_exists
- rate_limited
- service_unavailable
- task_failed
- internal_error
- processing_failed
message:
type: string
description: Human-readable explanation of the synchronous request failure.
request_id:
description: |
Always null on a synchronous failure. Correlate with the
`X-Request-Id` response header instead.
type: string
nullable: true
headers:
RequestId:
description: Stable request identifier for support and tracing.
schema:
type: string
responses:
ResourceBadRequest:
description: |
Invalid request. The resource operations answer every request-shape
rejection with `400`; they never answer `422`.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceUnauthorized:
description: Missing, invalid, or expired API key.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourcePaymentRequired:
description: Insufficient credits.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceNotFound:
description: |
The resource does not exist, or it is not owned by the calling
principal. The two cases are deliberately indistinguishable.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceConflict:
description: The client-supplied task ID is already in use.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceInternalServerError:
description: Unexpected server error.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
ResourceServiceUnavailable:
description: Service temporarily unavailable.
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or OAuth access token
description: |
Server-side SDK clients use a project API key. Remote MCP clients use
an OAuth access token. Never expose a project API key in browser code.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.