> ## 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 Text)
> Generate a reusable 3D Motion from a text prompt.
Send `application/json` to generate a 3D skeletal animation from a text prompt. Text-generated Motions always use `type: glb` because they do not have a render-ready 2D video counterpart.
This uses the same `POST /v1/motions` endpoint as [Create Motion (from Video)](/v1/api-reference/motions/create), but the content type and request fields are different. It replaces the old, now-removed `POST /v1/animations/generate` endpoint.
**Pricing** (1 credit = \$0.01): a flat **10 credits** per request, independent of `duration_seconds`. This is a different rate from the per-second `glb` extraction on [Create Motion (from Video)](/v1/api-reference/motions/create). See [Pricing and retention](/v1/pricing).
## Request parameters
Send `application/json`.
| Parameter | Type | Required | Default | Description |
| ------------------ | ------------------------- | :------: | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | string (1–400 characters) | Yes | — | Natural-language description of the movement to generate. Include the action, direction, pace, and relevant body parts for a more specific result. |
| `duration_seconds` | number | No | `5` | Requested animation length in seconds. It is rounded to the nearest frame at 30 FPS; values outside `[3, 60]` return `400` instead of being clamped. Does not affect the flat 10-credit price. |
| `guidance_scale` | number | No | `5` | Controls how strongly generation follows the text prompt. Values must be between `0` and `30`; out-of-range input returns `400`. |
| `smooth` | boolean | No | `true` | Whether to smooth the generated animation to reduce abrupt frame-to-frame joint changes. |
| `name` | string | No | `""` | Optional display label returned by detail and list operations. It does not affect motion generation. |
| `task_id` | string | No | — | Optional caller-generated idempotency ID for safe retries. Use the same stable value for the same intended generation and a new value for separate work. |
## Response parameters
Returns `200 OK` with a queued 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 for a text-generated Motion because it has no 2D render capability. |
| `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 | Always `glb`. |
| `glb` | object or null | Yes | Contains `{status, skeletons, error}` while generating and after completion. Ready Motions provide both `mixamo` and `metahuman` skeletons. |
| `vsplat` | null | Yes | Always `null` for a Motion. |
```json theme={null}
{
"id": "mot_550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"name": "Cartwheel",
"progress": 0,
"capabilities": [],
"created_at": "2026-07-21T10:00:00+00:00",
"completed_at": null,
"error": null,
"type": "glb",
"vsplat": null,
"glb": {
"status": "queued",
"skeletons": [],
"error": null
}
}
```
## Examples
```go Go theme={null}
payload := strings.NewReader(`{"text":"a person doing a cartwheel","duration_seconds":5,"guidance_scale":7.5,"smooth":true,"name":"Cartwheel","task_id":"motion-cartwheel-001"}`)
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/motions", payload)
req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
```
```javascript JavaScript theme={null}
const response = await fetch("https://apis.viggle.ai/v1/motions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VIGGLE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
text: "a person doing a cartwheel",
duration_seconds: 5,
guidance_scale: 7.5,
smooth: true,
name: "Cartwheel",
task_id: "motion-cartwheel-001",
}),
});
const motion = await response.json();
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://apis.viggle.ai/v1/motions",
headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
json={
"text": "a person doing a cartwheel",
"duration_seconds": 5,
"guidance_scale": 7.5,
"smooth": True,
"name": "Cartwheel",
"task_id": "motion-cartwheel-001",
},
)
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" \
-H "Content-Type: application/json" \
-d '{"text":"a person doing a cartwheel","duration_seconds":5,"guidance_scale":7.5,"smooth":true,"name":"Cartwheel","task_id":"motion-cartwheel-001"}'
```
## Next step
Use [Get Motion](/v1/api-reference/motions/get) to poll the returned ID until `status` is `ready`, then [Export 3D Motion (for 3D/game engines)](/v1/api-reference/motions/export) to retrieve the `mixamo` or `metahuman` glb.
Follow the complete create, poll, and export flow.
## 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 text-to-video (`vid_` prefix), and read the
unified view over every video the caller owns — H3 generations and
character+motion Renders (`render_` prefix) — merged into one
resource.
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` or
`motion_video_url`. `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.
name:
description: |
Optional label for `render` or `all`. A `glb`-only Motion
currently returns an empty name.
type: string
default: ''
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 30 FPS default. The value must be greater
than zero and applies only to `type=glb` or `all`.
type: number
minimum: 0
exclusiveMinimum: true
default: 30
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.
````