Hook Cloner

Create viral hook-style UGC videos featuring AI actors showcasing your product with attention-grabbing hooks. Choose between two powerful workflows: UGCL 2.0 for maximum customization or UGCL 1.0 for extended duration support.

Create Hook Cloner Video

Generate viral hook-style videos with AI actors presenting your product.

POST /ugc/hook-cloner

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": "Stop scrolling! You need to see this...",
  "actions": "Looking surprised, pointing at product, energetic gestures",
  "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 hook 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": "Wait, you guys haven't tried this yet? Let me show you why everyone is talking about it...",
  "actions": "Holding product dramatically, showing features",
  "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 hook 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

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

curl -X POST https://api.ugclab.app/api/v1/ugc/hook-cloner \
  -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": "Stop scrolling! This product changed everything for me!",
    "actions": "Looking surprised, dramatic pause, holding product up",
    "duration": "15s",
    "tier": "standard"
  }'

const response = await fetch('https://api.ugclab.app/api/v1/ugc/hook-cloner', {
  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: 'Stop scrolling! This changed my life!',
    actions: 'Excited expression, pointing at product',
    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/hook-cloner',
    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': 'Stop scrolling! This changed my life!',
        'actions': 'Excited expression, pointing at product',
        '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

Start with attention-grabbing phrases like "Stop scrolling!", "Wait...", or "POV:" for maximum engagement.

Attention-grabbing hooks: Start with phrases like "Stop scrolling!", "Wait...", or "POV:" for maximum engagement.
Authentic scripts: Write scripts that sound natural and conversational, like real UGC content.
High-quality product images: Use clear, well-lit product photos for best results.
Descriptive actions: Be specific about emotions and movements for more engaging videos.
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