Product in Hand

Create professional UGC videos featuring AI actors holding and showcasing your product. Choose between two powerful workflows: UGCL 2.0 for maximum customization or UGCL 1.0 for extended duration support.

Create Product in Hand Video

Generate videos with AI actors holding and presenting your product.

POST /ugc/product-in-hand

Request Headers

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

Workflows

UGCL 2.0 Workflow

Request Body (UGCL 2.0)

{
  "projectId": "clxxx...",
  "workflowType": "ugcl-2.0",
  "actorIds": ["clyyy..."],
  "productImageUrl": "https://example.com/product.jpg",
  "script": "Check out this amazing product! It's changed my life...",
  "actions": "Holding product, showing it to camera, smiling",
  "duration": "15s",
  "tier": "standard",
  "variants": 1,
  "refineScript": true,
  "refineActions": true
}

UGCL 2.0 Parameters

Parameter	Type	Required	Default	Description
`projectId`	string	Yes	-	Your project ID (CUID format)
`workflowType`	string	Yes	-	Must be `"ugcl-2.0"`
`actorIds`	string[]	Conditional	`[]`	Array of actor IDs (max 20). Required if no `customActors`
`customActors`	object[]	Conditional	`[]`	Array of custom actor definitions (max 20). Required if no `actorIds`
`productImageUrl`	string	Yes	-	HTTPS URL to your product image
`script`	string	Yes	-	The script for the actor to speak (10-500 characters)
`actions`	string	Yes	-	Actor actions with product (10-1000 characters)
`duration`	string	Yes	-	Video duration: `"10s"`, `"15s"`, or `"25s"` (storyboard)
`tier`	string	No	`"standard"`	Quality tier: `"standard"` or `"pro"`
`variants`	number	No	`1`	Number of video variants per actor (1-8)
`refineScript`	boolean	No	`true`	AI-enhance the script
`refineActions`	boolean	No	`true`	AI-enhance the actions

UGCL 2.0 Pricing

Duration	Standard Tier	Pro Tier
10s	63 credits	88 credits
15s	75 credits	125 credits
25s (storyboard)	113 credits	113 credits

UGCL 1.0 Workflow

Request Body (UGCL 1.0)

{
  "projectId": "clxxx...",
  "workflowType": "ugcl-1.0",
  "ugclabActorIds": ["clzzz..."],
  "productImageUrl": "https://example.com/product.jpg",
  "script": "I've been using this product for a month and the results are incredible...",
  "actions": "Unboxing, examining product closely",
  "ugclabMode": "pro",
  "veoDuration": "15s",
  "variants": 1
}

UGCL 1.0 Parameters

Parameter	Type	Required	Default	Description
`projectId`	string	Yes	-	Your project ID (CUID format)
`workflowType`	string	Yes	-	Must be `"ugcl-1.0"`
`ugclabActorIds`	string[]	Yes	-	Array of UGCLab actor IDs (1-20 required)
`productImageUrl`	string	Yes	-	HTTPS URL to your product image
`script`	string	Yes	-	The script for the actor to speak (10-500 characters)
`actions`	string	No	`""`	Actor actions with product (max 1000 characters)
`ugclabMode`	string	No	`"pro"`	Quality mode: `"std"` or `"pro"`
`veoDuration`	string	No	`"8s"`	Video duration: `"8s"`, `"15s"`, `"22s"`, `"30s"`
`variants`	number	No	`1`	Number of video variants per actor (1-8)

UGCL 1.0 Pricing

Duration	Standard Mode	Pro Mode
8s	32 credits	93 credits
15s	60 credits	133 credits
22s	88 credits	200 credits
30s	120 credits	267 credits

Product Image Requirements

Product images must be publicly accessible via HTTPS. HTTP, localhost, and private IPs are not supported.

Format: JPEG, PNG, or WebP
Protocol: Must be HTTPS (no HTTP, localhost, or private IPs)
Accessibility: URL must be publicly accessible
Recommended size: At least 512x512 pixels for best quality

Response

Success Response (202 Accepted)

{
  "data": {
    "jobs": [
      {
        "ugcId": "clxxx...",
        "actorId": "clyyy...",
        "variantIndex": 0,
        "status": "PENDING",
        "creditsCharged": 75
      }
    ],
    "totalCreditsCharged": 75,
    "remainingCredits": 4925
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Examples

# UGCL 2.0 Workflow
curl -X POST https://api.ugclab.app/api/v1/ugc/product-in-hand \
  -H "Authorization: Bearer ugc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "clxyz123...",
    "workflowType": "ugcl-2.0",
    "actorIds": ["clactor123..."],
    "productImageUrl": "https://example.com/my-product.jpg",
    "script": "I just discovered this amazing product!",
    "actions": "Holding product up to camera, pointing at features",
    "duration": "15s",
    "tier": "standard"
  }'

const response = await fetch('https://api.ugclab.app/api/v1/ugc/product-in-hand', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ugc_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId: 'clxyz123...',
    workflowType: 'ugcl-2.0',
    actorIds: ['clactor123...'],
    productImageUrl: 'https://example.com/my-product.jpg',
    script: 'Check out this amazing product!',
    actions: 'Holding product, showing features',
    duration: '15s',
    tier: 'standard',
    variants: 1,
  }),
});

const data = await response.json();

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

import requests

response = requests.post(
    'https://api.ugclab.app/api/v1/ugc/product-in-hand',
    headers={
        'Authorization': 'Bearer ugc_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'projectId': 'clxyz123...',
        'workflowType': 'ugcl-2.0',
        'actorIds': ['clactor123...'],
        'productImageUrl': 'https://example.com/my-product.jpg',
        'script': 'Check out this amazing product!',
        'actions': 'Holding product, showing features',
        'duration': '15s',
        'tier': 'standard',
        'variants': 1,
    }
)

data = response.json()

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

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`INVALID_ACTOR_IDS`	400	One or more actor IDs are invalid
`INVALID_UGCLAB_ACTOR_IDS`	400	One or more UGCLab actor IDs are invalid
`ACTOR_MISSING_IMAGE`	400	Some actors are missing image configuration
`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

High-quality product images: Use clear, well-lit product photos for best results.
Descriptive actions: Be specific about how the actor should interact with the product.
Natural scripts: Write scripts that sound authentic and conversational.
Test with Standard tier: Use tier: "standard" for testing to save credits.
Use webhooks: Configure webhooks for real-time status updates instead of polling.

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

On this page