Skip to main content
With Lucy Motion, you can control object motion in videos using precise trajectory paths. Instead of text prompts, you define keyframe coordinates to create predictable, controlled animations.
Output video is limited to 5 seconds.

​
Quick start

# Submit job
JOB_ID=$(curl -s -X POST https://api.decart.ai/v1/jobs/lucy-motion \
  -H "X-API-KEY: $DECART_API_KEY" \
  -F "data=@product-image.jpg" \
  -F 'trajectory=[{"frame":0,"x":0,"y":0},{"frame":1,"x":0.1,"y":0.2},{"frame":2,"x":0.2,"y":0.4}]' | jq -r '.job_id')

# Poll until completed
while true; do
  STATUS=$(curl -s -H "X-API-KEY: $DECART_API_KEY" \
    https://api.decart.ai/v1/jobs/$JOB_ID | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 2
done

# Download result
curl -H "X-API-KEY: $DECART_API_KEY" \
  https://api.decart.ai/v1/jobs/$JOB_ID/content --output motion-video.mp4

​
Parameters

  • data (required) — Input image file to animate.
  • trajectory (required) — Array of keyframe coordinates defining the motion path: [{frame: number, x: number, y: number}]. Coordinates are normalized (0–1).
  • seed (optional) — Random seed for reproducibility.
  • resolution (optional) — Output resolution: 720p (default).
For complete API documentation including response formats and error codes, see the API Reference.

​
Video specifications

  • Duration: Fixed 5 seconds
  • Resolution: 720p (720×1280 portrait or 1280×720 landscape)
  • Format: MP4 with H.264 encoding

​
Endpoint

​
Next steps

Try in the Platform

Try out Lucy Motion in the interactive platform.

Full API reference

Check out all the options for motion control in the API reference.

Video Editing

Learn how to edit your videos with Lucy Edit 2.