POST videos/motion-control

Motion Control

May 13, 2026

Request Headers
Request Body
Responses
Model
Examples
Try It

Drive a character image with motion extracted from a reference video. Upload a portrait (the character) and a short motion clip — PixVerse animates the character following the motion of the clip. Useful for transferring dance moves, gestures, or full-body action onto a still image.

Upload the character image and the motion video using POST /files.
PixVerse validates the character image before submission — if it cannot detect a clear person or animal subject, the request is rejected with 422.
This endpoint does not accept a prompt — motion comes entirely from the reference video.

https://api.useapi.net/v2/pixverse/videos/motion-control

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

API token is required, see Setup useapi.net for details.

Request Body

{
    "email": "Optional PixVerse API account email",
    "frame_1_path": "upload/a1b2c3d4-1111-2222-3333-character000001.webp",
    "video_1_path": "upload/e5f6a7b8-4444-5555-6666-motionvideo0001.mp4",
    "quality": "720p",
    "off_peak_mode": false,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference here"
}

email is optional, if not specified API will randomly select account from available accounts.
frame_1_path is required — character image path uploaded via POST /files. Must contain a clear subject (person or animal); ambiguous or empty images will be rejected with 422.
video_1_path is required — motion reference video path uploaded via POST /files.

Motion video limits (enforced by PixVerse upstream):
- Duration: 1–30 sec
- File size: ≤ 50 MB
- Dimensions: ≤ 1920 × 1920 px
model is optional. Currently only one engine is supported. Supported values: v5.6 (default).
quality is optional. Video quality. Supported values: 360p, 540p, 720p (default).
off_peak_mode is optional. Set to true to generate during low-demand periods at a reduced credit cost. Discount varies by subscription plan: Pro 30% off, Premium 50% off, Ultra unlimited free. Results are usually delivered within 24 hours. Off-Peak generations are not tracked by the scheduler, don’t count toward concurrent-job limits, and the replyUrl webhook is not called — use GET videos to retrieve results. Supported values: false (default), true.
replyUrl is optional. This is the preferred and most optimal way to receive results quickly — the API polls every 10 seconds and will call the provided replyUrl once the PixVerse video is completed or failed. Maximum length 1024 characters. We recommend using sites like webhook.site to test callback URL functionality.
replyRef is optional, place here your reference id which will be stored and returned along with this PixVerse video response / result. Maximum length 1024 characters.
maxJobs is optional, if not specified value from selected accounts/email will be used. Valid range: 1…8 It should not exceed the number of concurrent generations supported by your account subscription plan.

Responses

200 OK

Use the returned video_id to retrieve video status and results using GET /videos. Locate the video in the response array and check if the field video_status_final is true or video_status_name is COMPLETED. The field url will contain the generated video link.

If you specify the optional parameter replyUrl, the API will call the provided replyUrl with video progress updates until the video is complete or fails.
```
{
    "video_id": "user:<userid>-pixverse:<email>-video:<number>"
}
```
400 Bad Request
```
{
  "error": "<Error message>"
}
```
401 Unauthorized
```
{
  "error": "Unauthorized"
}
```

412 Insufficient credits

{
  "error": "All Credits have been used up. Please upgrade your membership or purchase credits."
}

422 Unprocessable Content

Character image was rejected — PixVerse could not detect a clear person or animal subject.
```
{
  "error": "Character image was rejected — upload a clear photo with a person or animal as the subject"
}
```

429 Too Many Requests

Wait in a loop for at least 10..30 seconds and retry again.

{
    "error":
      "Account <email> is busy executing <maxJobs> tasks."
      "All configured accounts are running at maximum capacity."
}

{
  "error": "Reached the limit for concurrent generations."
}

596 Pending mod message

Your PixVerse.ai account has a pending error. Most likely, you changed your account password or your PixVerse.ai account was placed on hold. Once the issue is resolved, update your account to clear the error by executing POST accounts/email before making any new API calls.
```
{
  "error":
    "Your PixVerse account has pending error."
    "Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls."
}
```

Model

{ // TypeScript, all fields are optional
    video_id: string
    error: string
}

Examples

curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v2/pixverse/videos/motion-control" \
     -d '{"frame_1_path": "upload/…webp", "video_1_path": "upload/…mp4", "quality": "720p"}'

const frame_1_path = "provide path of uploaded character image via POST /files";
const video_1_path = "provide path of uploaded motion video via POST /files";
const apiUrl = `https://api.useapi.net/v2/pixverse/videos/motion-control`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({
  frame_1_path, video_1_path, quality: '720p'
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

import requests
frame_1_path = "provide path of uploaded character image via POST /files"
video_1_path = "provide path of uploaded motion video via POST /files"
apiUrl = f"https://api.useapi.net/v2/pixverse/videos/motion-control"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
body = {
    "frame_1_path": f"{frame_1_path}",
    "video_1_path": f"{video_1_path}",
    "quality": "720p"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())