Talking Actor

Create professional UGC videos featuring ultra-realistic AI actors speaking your custom script. Choose between two powerful workflows: UGCL 2.0 for maximum customization or UGCL 1.0 for extended duration support.

Create Talking Actor Video

Generate videos with AI actors speaking your script.

POST /ugc/talking-actor

Request Headers

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

Workflows

UGCL 2.0 Workflow

The UGCL 2.0 workflow offers maximum customization with support for custom actors and storyboarding.

Request Body (UGCL 2.0)

{
  "projectId": "clxxx...",
  "workflowType": "ugcl-2.0",
  "actorIds": ["clyyy..."],
  "script": "Hello! Welcome to our product demo...",
  "actions": "Speaking enthusiastically, gesturing with hands",
  "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`
`script`	string	Yes	-	The script for the actor to speak (10-3000 characters)
`actions`	string	Yes	-	Actor actions and emotions (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
`storyboardScenes`	object[]	No	`null`	Storyboard scenes (2-3 scenes, 25s total). Only for `25s` duration

Custom Actor Object

{
  "characterDescription": "A professional woman in her 30s with dark hair",
  "environment": "Modern office with glass windows",
  "sceneContext": "Corporate presentation setting",
  "cinematography": "Medium close-up, soft lighting",
  "audioAmbience": "Quiet office background",
  "ugcKeywords": "professional, trustworthy, confident",
  "refineCharacter": true,
  "refineEnvironment": true,
  "refineSceneContext": true,
  "refineCinematography": true,
  "refineAudioAmbience": true,
  "refineUgcKeywords": true
}

Storyboard Scene Object

{
  "duration": 10,
  "script": "Scene 1 dialogue...",
  "actions": "Actor walks into frame",
  "refineScript": true,
  "refineActions": true
}

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

The UGCL 1.0 workflow uses cutting-edge video generation with extended duration support.

Request Body (UGCL 1.0)

{
  "projectId": "clxxx...",
  "workflowType": "ugcl-1.0",
  "ugclabActorIds": ["clzzz..."],
  "script": "Hello! Welcome to our product demo...",
  "actions": "Speaking naturally",
  "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)
`script`	string	Yes	-	The script for the actor to speak (10-2000 characters)
`actions`	string	No	`""`	Actor actions and emotions (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

# UGCL 2.0 Workflow
curl -X POST https://api.ugclab.app/api/v1/ugc/talking-actor \
  -H "Authorization: Bearer ugc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "clxyz123...",
    "workflowType": "ugcl-2.0",
    "actorIds": ["clactor123..."],
    "script": "Hi there! I just tried this amazing product.",
    "actions": "Speaking excitedly, making eye contact with camera",
    "duration": "15s",
    "tier": "standard",
    "variants": 1
  }'

# UGCL 1.0 Workflow
curl -X POST https://api.ugclab.app/api/v1/ugc/talking-actor \
  -H "Authorization: Bearer ugc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "clxyz123...",
    "workflowType": "ugcl-1.0",
    "ugclabActorIds": ["clugcactor123..."],
    "script": "Welcome to my honest review.",
    "ugclabMode": "pro",
    "veoDuration": "15s"
  }'

const response = await fetch('https://api.ugclab.app/api/v1/ugc/talking-actor', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ugc_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId: 'clxyz123...',
    workflowType: 'ugcl-2.0',
    actorIds: ['clactor123...'],
    script: 'Hi there! I just tried this amazing product.',
    actions: 'Speaking excitedly, holding product',
    duration: '15s',
    tier: 'standard',
    variants: 1,
  }),
});

const data = await response.json();

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

import requests

response = requests.post(
    'https://api.ugclab.app/api/v1/ugc/talking-actor',
    headers={
        'Authorization': 'Bearer ugc_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'projectId': 'clxyz123...',
        'workflowType': 'ugcl-2.0',
        'actorIds': ['clactor123...'],
        'script': 'Hi there! I just tried this amazing product.',
        'actions': 'Speaking excitedly, holding product',
        'duration': '15s',
        'tier': 'standard',
        'variants': 1,
    }
)

data = response.json()

if response.ok:
    print(f"Jobs created: {len(data['data']['jobs'])}")
    print(f"Total credits: {data['data']['totalCreditsCharged']}")
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

Use tier: "standard" for testing to save credits before final production runs.

Use webhooks: Instead of polling for status, configure webhooks to receive real-time updates.
Batch efficiently: Use multiple actors and variants in a single request rather than making multiple requests.
Handle rate limits: Implement exponential backoff when you receive 429 responses.
Script length: For best lip-sync quality, keep scripts concise.
Test with Standard tier: Use tier: "standard" for testing before final production runs.

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

On this page