Motion Control

Create UGC videos by applying AI actor motion to your reference video. Perfect for recreating viral videos, TikTok trends, or specific movements with AI actors and optional product placement.

Motion Control uses the UGCL 1.0 workflow exclusively.

Create Motion Control Video

Generate videos by applying AI actor appearance and motion to your reference video.

POST /ugc/motion-control

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes	`application/json`

Request Body

{
  "projectId": "clxxx...",
  "ugclabActorIds": ["clzzz..."],
  "referenceVideoUrl": "https://example.com/reference-video.mp4",
  "videoDuration": 15,
  "productImageUrl": "https://example.com/product.jpg",
  "userPrompt": "Actor holding the product while dancing",
  "quality": "pro",
  "variants": 1
}

Parameters

Parameter	Type	Required	Default	Description
`projectId`	string	Yes	-	Your project ID (CUID format)
`ugclabActorIds`	string[]	Yes	-	Array of UGCLab actor IDs (1-20 required)
`referenceVideoUrl`	string	Yes	-	HTTPS URL to reference video (MP4 or WebM, max 50MB)
`videoDuration`	number	Yes	-	Duration of reference video in seconds (1-30)
`productImageUrl`	string	No	-	HTTPS URL to product image for placement
`userPrompt`	string	No	-	Additional instructions for the AI (max 1000 characters)
`quality`	string	No	`"pro"`	Quality mode: `"std"` or `"pro"`
`variants`	number	No	`1`	Number of video variants per actor (1-8)

Reference Video Requirements

Reference videos must be publicly accessible via HTTPS. Maximum duration is 30 seconds.

Formats: MP4, WebM
Max size: 50MB
Max duration: 30 seconds
Protocol: Must be HTTPS (no HTTP, localhost, or private IPs)
Accessibility: URL must be publicly accessible

Pricing

Motion Control pricing is based on video duration and quality:

Quality	Credits per Second
Standard (`std`)	6 credits
Pro (`pro`)	10 credits

Example calculations:

Duration	Standard	Pro
5 seconds	30 credits	50 credits
10 seconds	60 credits	100 credits
15 seconds	90 credits	150 credits
30 seconds	180 credits	300 credits

Credits are multiplied by the number of actors and variants.

Response

Success Response (202 Accepted)

{
  "data": {
    "jobs": [
      {
        "ugcId": "clxxx...",
        "ugclabActorId": "clzzz...",
        "variantIndex": 0,
        "status": "PENDING",
        "creditsCharged": 150
      }
    ],
    "totalCreditsCharged": 150,
    "remainingCredits": 4850
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Examples

# Basic motion control
curl -X POST https://api.ugclab.app/api/v1/ugc/motion-control \
  -H "Authorization: Bearer ugc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "clxyz123...",
    "ugclabActorIds": ["clugcactor123..."],
    "referenceVideoUrl": "https://example.com/dance-video.mp4",
    "videoDuration": 15,
    "quality": "pro",
    "variants": 1
  }'

# With product placement
curl -X POST https://api.ugclab.app/api/v1/ugc/motion-control \
  -H "Authorization: Bearer ugc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "clxyz123...",
    "ugclabActorIds": ["clugcactor123..."],
    "referenceVideoUrl": "https://example.com/unboxing-motion.mp4",
    "videoDuration": 10,
    "productImageUrl": "https://example.com/my-product.jpg",
    "userPrompt": "Actor excitedly holding and showing the product",
    "quality": "pro",
    "variants": 2
  }'

const response = await fetch('https://api.ugclab.app/api/v1/ugc/motion-control', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ugc_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId: 'clxyz123...',
    ugclabActorIds: ['clugcactor123...'],
    referenceVideoUrl: 'https://example.com/dance-video.mp4',
    videoDuration: 15,
    quality: 'pro',
    variants: 1,
  }),
});

const data = await response.json();

if (response.ok) {
  console.log('Jobs created:', data.data.jobs);
  console.log('Credits charged:', data.data.totalCreditsCharged);
} else {
  console.error('Error:', data.error.message);
}

import requests

response = requests.post(
    'https://api.ugclab.app/api/v1/ugc/motion-control',
    headers={
        'Authorization': 'Bearer ugc_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'projectId': 'clxyz123...',
        'ugclabActorIds': ['clugcactor123...'],
        'referenceVideoUrl': 'https://example.com/dance-video.mp4',
        'videoDuration': 15,
        'quality': 'pro',
        'variants': 1,
    }
)

data = response.json()

if response.ok:
    print(f"Jobs created: {len(data['data']['jobs'])}")
    print(f"Credits charged: {data['data']['totalCreditsCharged']}")
else:
    print(f"Error: {data['error']['message']}")

Use Cases

Recreate Viral Videos

Use trending TikTok or Instagram videos as reference to create your own version with AI actors:

Download the trending video
Upload to your hosting
Use the URL as referenceVideoUrl
AI will apply the same movements to your selected actors

Product Demonstrations

Combine motion control with product placement:

Use a video showing product handling motions
Add your product image via productImageUrl
The AI will integrate your product into the movements

Consistent Brand Content

Create multiple videos with consistent movements but different actors:

Use the same referenceVideoUrl
Select multiple ugclabActorIds
Generate variants for A/B testing

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`INVALID_UGCLAB_ACTOR_IDS`	400	One or more UGCLab actor IDs are invalid
`ACTOR_MISSING_IMAGE`	400	Some actors are missing image configuration
`VIDEO_DOWNLOAD_FAILED`	400	Failed to download reference video
`INSUFFICIENT_CREDITS`	402	Not enough credits in workspace
`PROJECT_NOT_FOUND`	404	Project not found in workspace
`IP_RATE_LIMITED`	429	Too many authentication attempts
`RATE_LIMIT_EXCEEDED`	429	API rate limit exceeded
`INTERNAL_ERROR`	500	Internal server error

Best Practices

Clear reference videos: Use videos with clear, visible movements for best results.
Appropriate duration: Keep videos under 15 seconds for optimal quality and faster processing.
Product prompts: When using productImageUrl, add a userPrompt describing how the actor should interact with the product.
Test with Standard: Use quality: "std" for testing before running pro quality jobs.
Use webhooks: Configure webhooks for real-time status updates instead of polling.
Video hosting: Ensure your reference video URL is publicly accessible and stable.

Actors API - Get actor IDs
Projects API - Get project IDs
Job Status API - Check job progress
Authentication - API key setup

On this page