Pixverse Motion Control Mimic API Documentation

Pixverse Motion Control Mimic API Documentation

Playground

PixVerse Motion Control Mimic is a fast AI motion transfer model that transfers motion from a reference video onto a target image to create natural character animation from a still image and motion clip. Ready-to-use REST inference API for character animation, pose transfer, reference motion videos, social media clips, advertising creatives, and professional image-to-video workflows with simple integration, no coldstarts, and affordable pricing.

Features

PixVerse Motion Control Mimic transfers motion from a reference video onto a target image to generate an animated result. Upload a character or object image, provide a motion reference video, choose an output quality tier, and generate a video that follows the motion pattern of the source clip.

Why Choose This?

• Motion transfer from video Use a real motion clip to drive the movement of a static character or subject image.

• Simple two-input workflow Just provide one image and one motion reference video.

• Multiple quality tiers Choose 360p, 540p, or 720p depending on your quality and budget needs.

• Useful for stylized animation Great for turning character art, avatars, or stylized figures into motion-driven clips.

• Production-ready API Suitable for character animation, social content, concept prototyping, and motion-transfer workflows.

Parameters

How to Use

1. Upload your image — provide the character, object, or subject you want to animate.
2. Upload your motion video — provide the reference clip whose movement should be mimicked.
3. Choose quality — select 360p, 540p, or 720p.
4. Submit — run the model and download the generated animation.

Example Use Case

Animate a stylized character image using the body movement from a dance or walking reference video.

Pricing

Pricing depends on quality and reference video duration.

Billing Rules

• Billing is based on the uploaded reference video duration
• Billed duration is rounded up to the next whole second
• Minimum billed duration is 1 second
• Maximum billed duration is 30 seconds
• 360p costs $0.090 per billed second
• 540p costs $0.100 per billed second
• 720p costs $0.120 per billed second

Example Costs

Best Use Cases

• Character animation — Bring illustrated or stylized characters to life with real motion input.
• Avatar motion transfer — Apply human movement to a custom avatar image.
• Social media content — Create short animated clips from static artwork and motion footage.
• Concept prototyping — Quickly test how a character or product might move.
• Stylized performance clips — Combine real movement with a designed visual subject.

Pro Tips

• Use a clean target image with a clearly visible full body or main subject.
• Choose a motion reference video with clear, readable movement.
• Start with shorter clips when testing motion quality.
• Use 360p for quick experiments and 720p for better final output.
• Keep the reference motion simple if you want more stable results.

Notes

• Both image and video are required.
• quality defaults to 360p.
• Billing is based on the reference video duration, rounded up to the next whole second.
• Videos longer than 30 seconds are billed as 30 seconds.
• Pricing depends only on quality and billed video duration.
• Reference videos must be no longer than 30 seconds. Pricing is capped at 30 seconds only if the platform enforces or trims the input to the supported 30-second limit.

Related Models

• PixVerse Models — Useful when you want prompt-driven animation instead of motion transfer.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "quality": "360p"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/pixverse/motion-control/mimic" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL=$(printf '%s' "${TASK}" | jq -r '.urls.get // empty')
if [ -z "${RESULT_URL}" ]; then RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"; fi

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    created|processing) sleep 2 ;;
    *) printf 'Unexpected status: %s
' "${STATUS}" >&2; exit 1 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters